igit-cn / git-semver

Owner: DevOps WG

GIT SemVer

Create and manage a .semver directory right next to your .git directory, for all of your Semantic Versioning needs.

Installation

Go

If you're using Go (1.11.4+):

go get github.com/edgexfoundry/git-semver

Assuming that your $GOPATH/bin is in your path, that's it.

Usage

NOTE: As of yet, authentication is the default provided by src-d/go-git, i.e. ssh-agent auth for SSH URLs.

git semver init [-ver=<version>] [-force]

Prepare the repository (and the current branch) for Semantic Versioning:

# git [init|clone] ...
git semver init

This will:

• create an orphaned branch named semver.
• create and commit a single file named after your current branch, i.e. master, with the content of 0.0.0 unless a version is specified. The default version can be overridden by specifying the -ver=<version> flag to init. Note, if specified, the version must be a valid semantic version otherwise the command will return an error.
• move this new checkout to .semver in your current repository
• modify the .git/info/exclude to ignore .semver
• push the semver branch to your current .git repository directory as if it were a remote.
• force will force set the specified or default version regardless of an existing version being present.

This invocation is idempotent-ish in that it will inspect your current repository and make modifications to the semver configuration accordingly. It will also attempt to clone (or checkout) the semver branch if it already exists instead of creating it anew.

git semver

Write to STDOUT the current version for the current branch.

git semver bump [-pre=<prefix>] major|minor|patch|final|pre

This will bump the specified axis and commit the change to the semver branch. final lops off any pre-release semver suffix whereas pre appends it. The default pre-release prefix is "pre" when bumping the pre axis but can be overridden by specifying the -pre=prefix flag to bump. Additionally, specifying the -pre=prefix flag to major, minor, or patch will initialize the pre-release semver suffix after bumping the specified axis.

For example, if currently on the master branch and the value returned by git semver is 1.0.0 invoking git semver bump -pre=rc patch will result in 1.0.1-rc.1 written to $PWD/.semver/master and commited, the written to STDOUT.

git semver tag [-force]

Attempt to tag the current HEAD with a tag that is effectively v$(git semver). This will fail if git-semver detects a tag on the current HEAD that can be parsed as a Semantic Version, unless the force flag is specified. The force flag will tag the current HEAD regardless if there is an existing tag present on HEAD.

git semver push

Push semver branch commits to the remote. Also push tags from the current repo that match the ref-spec refs/tags/v*:refs/tags/v*.

Environment Variables

From scope/scope.go, these values have default values that can be over-ridden:

• SEMVER_ORIGIN_NAME = origin
• SEMVER_PRE_PREFIX = pre
• SEMVER_USER_EMAIL = [email protected]
• SEMVER_USER_NAME = semver

Additionally, $SEMVER_BRANCH (then $GIT_BRANCH if empty, then $BRANCH_NAME) will be dereferenced if git-semver is unable to detect the current branch (common with the default clone/checkout in Jenkins).

As described below, there is also SEMVER_DEBUG which interprets as per strconv.ParseBool() with the caveat that "on", "On, or "ON" are are treated as true.

When Things Go Wrong

If this darn tool just isn't behaving the way you expect, consider invoking it with the SEMVER_DEBUG=on to log a bit more detail to STDERR, e.g.

export SEMVER_DEBUG=on
git semver init
# $GIT_DIR = /tmp/test/.git
# $GIT_WORK_TREE = /tmp/test
# $SEMVER_ORIGIN_NAME = origin
# $SEMVER_USER_EMAIL = [email protected]
# $SEMVER_USER_NAME = semver
# $SEMVER_BRANCH = master
# $SEMVER_TEMP = /var/folders/7s/bwc8hz3n5498r68fw4gq6cxr0000gq/T/semver-546746833
# git clone --branch semver /tmp/test/.git $SEMVER_TEMP
# -> Clone(): remote repository is empty
# git init /var/folders/7s/bwc8hz3n5498r68fw4gq6cxr0000gq/T/semver-546746833
# git push /tmp/test/.git semver
# '/var/folders/7s/bwc8hz3n5498r68fw4gq6cxr0000gq/T/semver-546746833' -> '/tmp/test/.semver'
# $SEMVER_DIR = /tmp/test/.semver
git semver
# $GIT_DIR = /tmp/test/.git
# $GIT_WORK_TREE = /tmp/test
# $SEMVER_ORIGIN_NAME = origin
# $SEMVER_USER_EMAIL = [email protected]
# $SEMVER_USER_NAME = semver
# $SEMVER_BRANCH = master
# $SEMVER_DIR = /tmp/test/.semver
0.0.0

Submitting such output with your bug reports will be helpful!

---