Automatically increment version tags to a git repo based on commit messages.
- AutoTag
- Git 2.x available in PATH
Version v1.0.0+ depends on the Git CLI, install Git with your distribution's package management system.
Versions prior to v1.0.0 use cgo libgit or native golang Git, the binary will work standalone.
| OS | Arch | binary |
|---|---|---|
| macOS | amd64 | autotag |
| Linux | amd64 | autotag |
| Arch | Images |
|---|---|
| amd64 | quay.io/pantheon-public/autotag:latest, vX.Y.Z, vX.Y, vX |
An install script generated by godownloader is available for all supported platforms. This is often a convenient option for CI pipelines.
Examples:
Download and install latest version of autotag at ./bin/autotag:
curl -sL https://git.io/autotag-install | sh --
Install to a different location using -b flag:
curl -sL https://git.io/autotag-install | sh -s -- -b /usr/bin
Install a specific version of autotag:
curl -sL https://git.io/autotag-install | sh -- v1.2.1
Only versions v1.2.0+ are supported by the install script.
The autotag utility will use the current state of the git repository to determine what the next
tag should be and then creates the tag by executing git tag. The -n flag will print the next tag but not apply it.
autotag scans the master branch for commits by default. Use -b/--branch to scan a different
branch. The utility first looks to find the most-recent reachable tag that matches a supported
versioning scheme. If no tags can be found the utility bails-out, so you do need to create a
v0.0.0 tag before using autotag.
Once the last reachable tag has been found, the autotag utility inspects each commit between the
tag and HEAD of the branch to determine how to increment the version.
Commit messages are parsed for keywords via schemes. Schemes influence the tag selection according to a set of rules.
Schemes are specified using the -s/--scheme flag:
The autotag scheme implements SemVer style versioning vMajor.Minor.Patch (e.g., v1.2.3).
Before using autotag for the first time create an initial SemVer tag,
eg: git tag v0.0.0 -m'initial tag'
The next version tag is calculated based on the contents of commit message according to these rules:
- Bump the major version by including
[major]or#majorin a commit message, eg:
[major] breaking change
- Bump the minor version by including
[minor]or#minorin a commit message, eg:
[minor] new feature added
- Bump the patch version by including
[patch]or#patchin a commit message, eg:
[patch] bug fixed
If no keywords are specified a Patch bump is applied.
Specify the Conventional Commits v1.0.0
scheme by passing --scheme=conventional to autotag.
Conventional Commits implements SemVer style versioning vMajor.Minor.Patch similar to the
autotag scheme, but with a different commit message format.
Examples of Conventional Commits:
- A commit message footer containing
BREAKING CHANGE:will bump the major version:
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
- A commit message header containing a type of
featwill bump the minor version:
feat(lang): add polish language
- A commit message header containg a
!after the type is considered a breaking change and will bump the major version:
refactor!: drop support for Node 6
If no keywords are specified a Patch bump is applied.
autotag supports appending additional test to the calculated next version string:
-
Use
-p/--pre-release-name=to append a pre-release name to the version. Pre-release names are subject to the rules outlined in the SemVer spec. -
Use
-T/--pre-release-timestmap=to append timestamp to the version. Allowed timetstamp formats aredatetime(YYYYMMDDHHMMSS) orepoch(UNIX epoch timestamp in seconds).
Optional SemVer build metadata can be appended to the version string after a + character using the -m/--build-metadata flag. eg: v1.2.3+foo
Build metadata is subject to the rules outlined in the SemVer spec.
A common uses might be the current git reference: git rev-parse --short HEAD.
Multiple metadata items should be seperated by a ., eg: foo.bar
$ autotag
3.2.1$ autotag -p pre
3.2.1-pre
$ autotag -T epoch
3.2.1-1499320004
$ autotag -T datetime
3.2.1-20170706054703
$ autotag -p pre -T epoch
3.2.1-pre.1499319951
$ autotag -p rc -T datetime
3.2.1-rc.20170706054528
$ autotag -m g$(git rev-parse --short HEAD)
3.2.1+ge92b825
$ autotag -p dev -m g$(git rev-parse --short HEAD)
3.2.1-dev+ge92b825
$ autotag -m $(date +%Y%M%d)
3.2.1-dev+20200518
$ autotag -m g$(git rev-parse --short HEAD).$(date +%s)
3.2.1+g11492a8.1589860151For additional help information use the -h/--help flag:
autotag -hautotag works well with goreleaser for automating the process of
creating new versions and releases from CI.
An example of a Circle-CI job utilizing both autotag and goreleaser:
jobs:
release:
steps:
- run:
name: install autotag binary
command: |
curl -sL https://git.io/autotag-install | sudo sh -s -- -b /usr/bin
- run:
name: increment version
command: |
autotag
- run:
name: build and push releases
command: |
curl -sL https://git.io/goreleaser | bash -s -- --parallelism=2 --rm-dist
workflows:
version: 2
build-test-release:
jobs:
- release
requires:
- build
filters:
branches:
only:
- mastererror getting head commit: object does not exist [id: refs/heads/master, rel_path: ]
You may run into this error on certain CI platforms such as Github Actions or Azure DevOps
Pipelines. These platforms tend to make shallow clones of the git repo leaving out important data
that autotag expects to find. This can be solved by adding the following commands prior to
running autotag:
# fetch all tags and history:
git fetch --tags --unshallow --prune
if [ $(git rev-parse --abbrev-ref HEAD) != "master" ]; then
# ensure a local 'master' branch exists at 'refs/heads/master'
git branch --track master origin/master
fiAssuming you have Go 1.5+ installed you can checkout and run make deps build to compile the binary
at ./autotag/autotag.
git clone git@github.com:pantheon-systems/autotag.git
cd autotag
make test
make buildAutotag itself uses autotag to increment releases. The default autotag
scheme is used for version selection.