package module
Version: v1.3.9 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 17, 2021 License: Apache-2.0 Imports: 13 Imported by: 7



CI Coverage Status Go Report Card

Automatically increment version tags to a git repo based on commit messages.


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.


Pre-built binaries
OS Arch binary
macOS amd64 autotag
Linux amd64 autotag
Docker images
Arch Images
amd64, 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.


Download and install latest version of autotag at ./bin/autotag:

curl -sL | sh --

Install to a different location using -b flag:

curl -sL | sh -s -- -b /usr/bin

Install a specific version of autotag:

curl -sL | 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:

Scheme: Autotag (default)

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 #major in a commit message, eg:
[major] breaking change
  • Bump the minor version by including [minor] or #minor in a commit message, eg:
[minor] new feature added
  • Bump the patch version by including [patch] or #patch in a commit message, eg:
[patch] bug fixed

If no keywords are specified a Patch bump is applied.

Scheme: Conventional Commits

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 feat will 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.

Pre-Release Tags

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 are datetime (YYYYMMDDHHMMSS) or epoch (UNIX epoch timestamp in seconds).

Build metadata

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:


$ autotag
$ autotag -p pre

$ autotag -T epoch

$ autotag -T datetime

$ autotag -p pre -T epoch

$ autotag -p rc -T datetime

$ autotag -m g$(git rev-parse --short HEAD)

$ autotag -p dev -m g$(git rev-parse --short HEAD)

$ autotag -m $(date +%Y%M%d)

$ autotag  -m g$(git rev-parse --short HEAD).$(date +%s)

For additional help information use the -h/--help flag:

autotag -h

autotag 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:

      - run:
          name: install autotag binary
          command: |
            curl -sL | sudo sh -s -- -b /usr/bin
      - run:
          name: increment version
          command: |
      - run:
          name: build and push releases
          command: |
            curl -sL | bash -s -- --parallelism=2 --rm-dist

  version: 2
      - release
            - build
                - master


error getting head commit: object does not exist [id: refs/heads/master, rel_path: ]
error 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

Build from Source

Assuming you have Go 1.5+ installed you can checkout and run make deps build to compile the binary at ./autotag/autotag.

git clone

cd autotag

make test
make build

Release information

Autotag itself uses autotag to increment releases. The default autotag scheme is used for version selection.




This section is empty.


This section is empty.


This section is empty.


type GitRepo

type GitRepo struct {
	// contains filtered or unexported fields

GitRepo represents a repository we want to run actions against

func NewRepo

func NewRepo(cfg GitRepoConfig) (*GitRepo, error)

NewRepo is a constructor for a repo object, parsing the tags that exist

func (*GitRepo) AutoTag

func (r *GitRepo) AutoTag() error

AutoTag applies the new version tag thats calculated

func (*GitRepo) LatestVersion

func (r *GitRepo) LatestVersion() string

LatestVersion Reports the Latest version of the given repo TODO:(jnelson) this could be more intelligent, looking for a nil new and reporting the latest version found if we refactor autobump at some point Mon Sep 14 13:05:49 2015

func (*GitRepo) MajorBump

func (r *GitRepo) MajorBump() (*version.Version, error)

MajorBump will bump the version one major rev 1.0.0 -> 2.0.0

func (*GitRepo) MinorBump

func (r *GitRepo) MinorBump() (*version.Version, error)

MinorBump will bump the version one minor rev 1.1.0 -> 1.2.0

func (*GitRepo) PatchBump

func (r *GitRepo) PatchBump() (*version.Version, error)

PatchBump will bump the version one patch rev 1.1.1 -> 1.1.2

type GitRepoConfig added in v1.1.2

type GitRepoConfig struct {
	// Repo is the path to the root of the git repository.
	RepoPath string

	// Branch is the name of the git branch to be tracked for tags. This value
	// must be provided.
	Branch string

	// PreReleaseName is the optional string to be appended to a tag being
	// generated (e.g., v.1.2.3-pre) to indicate the pre-release type.
	// You can provide any string you want (that is valid for a Git tag); here
	// are some recommended values:
	// 		* pre(release)
	// 		* alpha
	// 		* beta
	// 		* rc
	PreReleaseName string

	// PreReleaseTimestampLayout is the optional value that's used to append a
	// timestamp to the git tag. The timezone will always be UTC. This value can
	// either be the string `epoch` to be the UNIX epoch, or a Golang time
	// layout string:
	// *
	// If PreReleaseName is an empty string, the timestamp will be appended
	// directly to the SemVer tag:
	// 		v1.2.3-1499308568
	// Assuming PreReleaseName is set to `pre`, the timestamp is appended to
	// that value separated by a period (`.`):
	// 		v1.2.3-pre.1499308568
	PreReleaseTimestampLayout string

	// BuildMetadata is an optional string appended by a plus sign and a series of dot separated
	// identifiers immediately following the patch or pre-release version. Identifiers MUST comprise
	// only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata
	// MUST be ignored when determining version precedence. Thus two versions that differ only in the
	// build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700,
	// 1.0.0-beta+exp.sha.5114f85
	BuildMetadata string

	// Scheme is the versioning scheme to use when determining the version of the next
	// tag. If not specified the default "autotag" is used.
	//   * "autotag" (default if not specified):
	//     A git commit message header containing one of the following:
	//      * [major] or #major: major version bump
	//      * [minor] or #minor: minor version bump
	//      * [patch] or #patch: patch version bump
	//      * none of the above: patch version bump
	//   * "conventional" implements the Conventional Commits v1.0.0 scheme.
	//     * w
	Scheme string

	// Prefix prepends literal 'v' to the tag, eg: v1.0.0. Enabled by default
	Prefix bool

GitRepoConfig is the configuration needed to create a new *GitRepo.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL