A CLI which automates semver versioning.

Overview

Semverbot

github.com release badge github.com workflow badge go.pkg.dev badge goreportcard.com badge img.shields.io MPL2 license badge

A CLI which automates semver versioning based on git information.

Why Semverbot?

There are several reasons why you should consider using sbot for your semver versioning.

Automation and pipelines

  • sbot uses git under the hood, which is today's widely adopted version control system
  • sbot does not use a file to keep track of the version
    • no pipeline loops
    • no need to maintain the version in two places, e.g., both a package.json file and git tags
  • sbot is ready to be used in pipelines out of the box

Note: it is still possible to use sbot and file-based versioning tools side-by-side

Convenience

  • sbot is designed to be used by both developers and pipelines
  • sbot is platform independent
    • support for Windows, Linux and macOS
    • no dependency on 'complex' npm, pip or other package management installations
  • sbot is fast
  • sbot heavily simplifies incrementing semver levels based on git information
    • today's git projects already hold a lot of useful semver information, e.g., branch names like feature/xxx or commit messages like [fix] xxx
    • no need to create and maintain custom code for semver level detection

Configurability

  • sbot supports a well-documented configuration file
    • intuitively customize how patch, minor and major levels are detected
  • sbot supports some flags to override parts of the configuration file on the fly

Requirements

sbot requires a git installation.

How to install

sbot can be retrieved from GitHub or a Homebrew tap. Run sbot -h to validate the installation. The tool is available for Windows, Linux and macOS.

github

The following example works for a GitHub Workflow, other CI/CD tooling will require a different path setup. The curl command remains the same.

SEMVERBOT_VERSION=0.1.2
mkdir bin
echo "$(pwd)/bin" >> $GITHUB_PATH
curl -o bin/sbot -L https://github.com/restechnica/semverbot/releases/download/v$SEMVERBOT_VERSION/sbot-linux-amd64
chmod +x bin/sbot

homebrew

sbot is available through the public tap github.com/restechnica/homebrew-tap

brew tap restechnica/tap [email protected]:restechnica/homebrew-tap.git
brew install restechnica/tap/semverbot

Commands

Each command has a -h, --help flag available.

sbot get version

Gets the current version, which is the latest git annotated tag without any prefix.

sbot init

Generates a configuration with defaults, see configuration defaults.

sbot predict version [-m, --mode] <mode>

Gets the next version, without any prefix. Uses a mode to detect which semver level it should increment. Defaults to mode auto. See Modes for more documentation on the supported modes.

sbot push version

Pushes the latest git tag. Equivalent to git push origin {prefix}{version}.

sbot release version [-m, --mode] <mode>

Creates a new version, which is a git annotated tag. Uses a mode to detect which semver level it should increment. Defaults to mode auto. See Modes for more documentation on the supported modes.

sbot update version

Fetches all tags with git to make sure the git repo has the latest tags available. Equivalent to git fetch --unshallow. This command is very useful in pipelines where shallow clones are often the default to save time and space.

Modes

auto (default)

Attempts a series of modes in the following order:

  1. git-branch
  2. git-commit - only if git-branch failed to detect a semver level to increment
  3. patch - only if git-commit failed to detect a semver level to increment

git-branch

Detects which semver level to increment based on the name of the git branch from where a merge commit originated from. This only works when the old branch has not been deleted yet.

The branch name is matched against the 'semver.detection' configuration.

git-commit

Detects which semver level to increment based the message of the latest git commit.

The commit message is matched against the 'semver.detection' configuration.

major

Increments the major level.

minor

Increments the minor level.

patch

Increments the patch level.

How to configure

sbot supports a configuration file. It looks for a .semverbot.toml file in the current working directory by default. .json and .yaml formats are also supported, but .toml is highly recommended.

Defaults

sbot init generates the following configuration:

[git]

[git.config]
email = "[email protected]"
name = "semverbot"

[git.tags]
prefix = "v"

[semver]
mode = "auto"

[semver.detection]
patch = ["fix/", "[fix]"]
minor = ["feature/", "[feature]"]
major = ["release/", "[release]"]

Configuration properties

git

sbot works with git under the hood, which needs to be set up properly. These config options make sure git is set up properly for your environment before running an sbot command.

git.email

git requires user.email to be set. If not set, sbot will set user.email to the value of this property. Rest assured, sbot will not override an existing user.email value.

Without this config sbot might show unexpected behaviour.

git.name

git requires user.name to be set. If not set, sbot will set user.name to the value of this property. Rest assured, sbot will not override an existing user.name value.

Without this config sbot might show unexpected behaviour.

git.tags.prefix

Different platforms and environments work with different (or without) version prefixes. This option enables you to set whatever prefix you would like to work with. The 'v' prefix, e.g. v1.0.1 is used by default due to its popularity, e.g. some Golang tools completely depend on it.

Note: sbot will always display the version without the prefix.

semver.detection

Some sbot semver modes require input to detect which semver level should be incremented. Each level will be assigned a collection of matching strings, which are to be matched against git information.

See Modes for documentation about the supported modes.

semver.detection.[level]

An array of strings which are to be matched against git information, like branch names and commit messages. Whenever a match happens, sbot will increment the corresponding level.

semver.mode

sbot supports multiple modes to detect which semver level it should increment. Each mode works with different criteria. A mode flag enables you to switch modes on the fly.

See Modes for documentation about the supported modes.

Examples

Local

Make sure sbot is installed.

sbot init
sbot release version
sbot push version

These commands are basically all you need to work with sbot locally.

GitHub Workflow

Shell

# installation
SEMVERBOT_VERSION=0.1.2
mkdir bin
echo "$(pwd)/bin" >> $GITHUB_PATH
curl -o bin/sbot -L https://github.com/restechnica/semverbot/releases/download/v$SEMVERBOT_VERSION/sbot-linux-amd64
chmod +x bin/sbot

# preparation
sbot update version
echo "RELEASE_VERSION=$(sbot predict version)" >> $GITHUB_ENV

# usage
echo "current version: $(sbot get version)"
echo "next version: $RELEASE_VERSION"
sbot release version
sbot push version

Yaml

name: main

on:
  push:
    branches: [ main ]

env:
  SEMVERBOT_VERSION: "0.1.2"

jobs:
  build:
    name: pipeline
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
        - 
      - name: set up path
        run: |
          mkdir bin
          echo "$(pwd)/bin" >> $GITHUB_PATH

      - name: install semverbot
        run: |
          curl -o bin/sbot -L https://github.com/restechnica/semverbot/releases/download/v$SEMVERBOT_VERSION/sbot-linux-amd64
          chmod +x bin/sbot
          
      - name: prepare release
        run: |
          sbot update version
          echo "RELEASE_VERSION=$(sbot predict version)" >> $GITHUB_ENV    
          
      - name: release
        run: |
          echo "current version: $(sbot get version)"
          echo "next version: $RELEASE_VERSION"

          sbot release version
          sbot push version
Issues
  • Goreleaser to provide automated homebrew and Scoop install packages for developer installs

    Goreleaser to provide automated homebrew and Scoop install packages for developer installs

    If you leverage goreleaser for the build, github release, homebrew update, and scoop packages can all be done with minimal effort as it's built into that tool.

    I suggest Scoop since it's similar to Homebrew, but focused on Windows dev tools. Would be a nice way to make it more accessible to the different development platforms.

    If you want a goreleaser config PR to help jump start just let me know. Be more than willing to help as I get some time.

    enhancement 
    opened by sheldonhull 6
  • Recent git error handling improvements show unexpected log outputs (not breaking)

    Recent git error handling improvements show unexpected log outputs (not breaking)

    image

    These logs/prints are shown due to the git command exit status being different that 0 or the stderr containing bytes when it really shouldn't. Semverbot still works as intended but simply outputs strange logs.

    The go Cobra library shows usage whenever an error occurs, even when the error is not due to faulty usage of the CLI. We can fix this with a combination of a logging implementation and using cmd.SilenceUsage = true.

    bug 
    opened by shiouen 3
  • Create a decent wiki page and gather FAQ from introductory Reddit post

    Create a decent wiki page and gather FAQ from introductory Reddit post

    People have posted really good questions on an introductory Reddit post, to the extent that the readme should be cleared up or replaced with a decent wiki. The questions can be compiled into an FAQ.

    documentation 
    opened by shiouen 3
  • sbot is not M1-docker compatible

    sbot is not M1-docker compatible

    Context:

    I have the below dockerfile on an M1 mac:

    FROM node:16
    ARG SEMVERBOT_VERSION=1.1.0
    # install sbot 
    RUN curl -o /usr/local/bin/sbot https://github.com/restechnica/semverbot/releases/download/v$SEMVERBOT_VERSION/sbot-linux-amd64 && \
        chmod +x /usr/local/bin/sbot
    
    CMD ["/bin/bash"]
    

    I build the image with the command docker build . --tag testimage We enter it via docker run --user 0 -it testimage /bin/bash

    Behaviour:

    Running the command sbot --help renders the following output: qemu-x86_64: Could not open '/lib64/ld-linux-x86-64.so.2': No such file or directory

    Expected behaviour:

    sbot --help should output the help options

    Temporary solution:

    Build the dockerfile using the command: docker build . --tag testimage --platform linux/x86_64 Run the image using the command: docker run --platform linux/x86_64 --user 0 -it testimage /bin/bash sbot --help now outputs the correct information

    Is this by design or a bug in docker or sbot?

    bug 
    opened by ToneVDB 2
  • Support the semantic-release specification as an option when generating a semverbot config file with `sbot init`

    Support the semantic-release specification as an option when generating a semverbot config file with `sbot init`

    Following comments on a introductory Reddit post, people have shown enough interest in the option of generating a semverbot configuration file for the semantic-release specification. It might even be made default.

    Topics to investigate:

    • should semantic-release be used as default?
    • should it be implemented as an option for the init command? e.g. sbot init -t, --template semantic-release
    enhancement 
    opened by shiouen 2
  • [FEAT] 'dig' until semver tag

    [FEAT] 'dig' until semver tag

    Situation

    We have a repo that has the following tags

    1.0.1
    1.1.0
    2.0.0
    2.1.0
    PROD
    

    Behaviour

    When running

    sbot release version
    sbot push version
    

    sbot creates a new tag 0.0.1 as the last tag is PROD - This is by design at the moment

    Expected behaviour

    sbot should ignore the first x amount of non semver tags when running the same commands the expectation is that sbot creates for example the 2.1.1 tag

    Potential fix

    Add a --dig / --depth comand line option / config file option that searches further back to find the 'latest' semver tag This could also become the default in case the oldest tag is non-semver compliant

    Example code

    To retrive the last 3 tags in git, sorted by 'potential' semver structure you could use

    git tag --sort=-version:refname | head -n 3
    

    This would yield the following example output:

    2.1.0
    2.0.0
    1.1.0
    

    'ignoring' the PROD tag.

    A solution in pkg/git/cli.go could be:

    // GetLastNumberAnnotatedTags gets the last x amount of semver-like tags - default is 5 tags
    // Returns the list of git tags and an error if the command fails
    func (api CLI) GetLastNumberAnnotatedTags(amount int) (tag string, err error) {
    	if amount == 0 {
    		amount = 5
    	}
    	strAmount := strconv.Itoa(amount)
    	return api.Commander.Output("git", "tag", "--sort=-version:refname", "|", "head", "-n", strAmount)
    }
    
    enhancement 
    opened by ToneVDB 1
  • Support the conventional-commits specification as an option when generating a semverbot config file with `sbot init`

    Support the conventional-commits specification as an option when generating a semverbot config file with `sbot init`

    Following comments on a introductory Reddit post, people have shown enough interest in the option of generating a semverbot configuration file for the conventional-commits specification. It might even be made default.

    Topics to investigate:

    • should semantic-release be used as default?
    • should it be implemented as an option for the init command? e.g. sbot init -t, --template conventional-commits
    enhancement 
    opened by shiouen 1
  • feature/separate-mode-from-semver-package

    feature/separate-mode-from-semver-package

    • breaking changes to the semverbot config file
    • semver level mappings are now re-usable among different modes and do not need special characters anymore
    • the special characters are now part of the logic of modes (git-branch and git-commit specifically) in the form of delimiters
    • added sensible defaults for the delimiters
    • made the delimiters configurable
    • fixed a bug with prefixing git tags
    • some code refactors
    opened by shiouen 0
  • fix/build-setup

    fix/build-setup

    • completed core package logic
    • finalized core package documentation
    • moved api package components to their own packages (semver, git and versions)
    • moved pieces of core package logic to version api for reusability
    • moved all remaining 'rogue' git command executions to the git api
    • project structure revamp (except for semver package)
    opened by shiouen 0
  • feature/core

    feature/core

    • project structure overhaul with focus on moving certain logic to the core package
    • documented core package
    • made CLI defaults configurable (e.g. config file location)
    opened by shiouen 0
  • fix/commander-error-handling

    fix/commander-error-handling

    Improved error handling for command runs

    • stderr is no longer used to detect errors
    • implemented custom command error which displays the command arguments, exit status code and command output
    opened by shiouen 0
  • [FEAT] Add support for pyproject.toml

    [FEAT] Add support for pyproject.toml

    It would be nice that instead of having a dedicated .semverbot.toml file in python repo's, we could add to the existing pyproject.toml file

    eg pyproject.toml :

    [tool.semverbot]
    mode = "auto"
    
    [tool.semverbot.config]
    patch = ["fix", "bug"]
    minor = ["feature", "feat"]
    major = ["release"] 
    

    This would possibly simplify the repo. Open for suggestions / concerns / ...

    enhancement 
    opened by ToneVDB 0
Releases(v1.1.0)
News-parser-cli - Simple CLI which allows you to receive news depending on the parameters passed to it

news-parser-cli Simple CLI which allows you to receive news depending on the par

Maxym 0 Jan 4, 2022
Nebula Diagnosis CLI Tool is an information diagnosis cli tool for the nebula service and the node to which the service belongs.

Nebula Diagnosis CLI Tool is an information diagnosis cli tool for the nebula service and the node to which the service belongs.

Katz 1 Jan 12, 2022
Rem is a CLI trash which makes it ridiculously easy to recover files.

Rem is a CLI trash which makes it ridiculously easy to recover files. We've all had that moment when we've deleted something we realised we shouldn't have. It sucks. Let's fix that!

Ishan Goel 43 Mar 31, 2022
PingMe is a CLI tool which provides the ability to send messages or alerts to multiple messaging platforms & email.

PingMe is a personal project to satisfy my needs of having alerts, most major platforms have integration to send alerts but its not always useful, either you are stuck with one particular platform, or you have to do alot of integrations. I needed a small app which i can just call from my backup scripts, cron jobs, CI/CD pipelines or from anywhere to send a message with particular information. And i can ship it everywhere with ease. Hence, the birth of PingMe.

Khaliq 527 Jun 26, 2022
CLI for SendGrid, which helps in managing SSO users, can install and update users from yaml config

Sendgrid API This script is needed to add new users to SendGrid as SSO teammates. Previously, all users were manually added and manually migrating the

ANNA 4 Nov 12, 2021
A CLI tool which loads data from yaml files into the Google Cloud Spanner tables

splanter A CLI tool which loads data from yaml files into the Google Cloud Spanner tables (mainly for the development).

Yuki Ito 6 Jun 20, 2022
Go-ticket-booking-app - Simple CLI application which books tickets for a Go conference made to learn the fundamentals of Go programming language.

go-ticket-booking-app Simple CLI application which books ticket for a Go conference made to learn the fundamentals of Go programming language. Gorouti

Aditya Garde 0 Jan 2, 2022
Adventure is a CLI game, which is a project of the OOP course of ZJU

Adventure is a CLI game, which is a project of the OOP course of ZJU. This is the go version of ZJU-OOP-Adventure.

null 0 Jan 25, 2022
K-Mesh is an experimental Knative distribution which provides a fresh, CLI-focused, holistic user experience of running and managing Knative.

K-Mesh is an experimental Knative distribution which provides a fresh, CLI-focused, holistic user experience of running and managing Knative. N

Ahmed Abdalla Abdelrehim 0 Feb 14, 2022
Elegant CLI wrapper for kubeseal CLI

Overview This is a wrapper CLI ofkubeseal CLI, specifically the raw mode. If you just need to encrypt your secret on RAW mode, this CLI will be the ea

Elm 4 Jan 8, 2022
CLI to run a docker image with R. CLI built using cobra library in go.

BlueBeak Installation Guide Task 1: Building the CLI The directory structure looks like Fastest process: 1)cd into bbtools 2)cd into bbtools/bin 3)I h

Aniruddha Chattopadhyay 0 Dec 20, 2021
A wrapper of aliyun-cli subcommand alidns, run aliyun-cli in Declarative mode.

aliyun-dns A wrapper of aliyun-cli subcommand alidns, run aliyun-cli in Declarative mode. Installation Install aliyun-cli. Usage $ aliyun-dns -h A wra

许嘉华 0 Dec 21, 2021
Symfony-cli - The Symfony CLI tool For Golang

Symfony CLI Install To install Symfony CLI, please download the appropriate vers

Symfony CLI 330 Jun 20, 2022
Go-file-downloader-ftctl - A file downloader cli built using golang. Makes use of cobra for building the cli and go concurrent feature to download files.

ftctl This is a file downloader cli written in Golang which uses the concurrent feature of go to download files. The cli is built using cobra. How to

Dipto Chakrabarty 2 Jan 2, 2022
Cli-algorithm - A cli program with A&DS in go!

cli-algorithm Objectives The objective of this cli is to implement 4 basic algorithms to sort arrays been Merge Sort Insertion Sort Bubble Sort Quick

Leonardo Brombilla Antunes 0 Jan 2, 2022
Nebulant-cli - Nebulant's CLI

Nebulant CLI Website: https://nebulant.io Documentation: https://nebulant.io/docs.html The Nebulant CLI tool is a single binary that can be used as a

Develatio 2 Jan 11, 2022
Go-api-cli - Small CLI to fetch data from an API sync and async

Async API Cli CLI to fetch data on "todos" from a given API in a number of ways.

Pete Robinson 0 Jan 13, 2022
Syno-cli - Synology unofficial API CLI and library

Synology CLI Unofficial wrapper over Synology API in Go. Focus on administrative

Aleksandr Baryshnikov 11 Jun 16, 2022