tag-version

This utility makes semantic versioning of source code with git tags easy and consistent.

This tool is mostly based around git's describe subcommand with the addition including the branch name in the version string.

Installation

pip install tag-version

More information at: https://pypi.python.org/pypi/tag-version

Usage

On a new project, tag-version displays a friendly suggestion:

$ tag-version
No version found, use --bump to set to 0.0.1

Upon using the --bump flag, the version is set:

$ tag-version --bump
0.0.1

Attempting to bump a tagged revision will result in an error message:

$ tag-version --bump
Is version=0.0.1 already bumped?

With no flags, the current version will be displayed:

$ tag-version
0.0.1

And when commits are made on top of a tag, tag-version uses git describe to provide a unique version and appends the current branch:

$ tag-version
0.0.1-2-g5bd60a7-master

This is especially useful when branch names are descriptive and include an ID referring to an issue tracker:

$ tag-version
0.0.1-2-g5bd60a7-bugfix--482-modal-options

Appending the branch can be disabled with the --no-branch option:

$ tag-version --no-branch
0.0.1-2-g5bd60a7

Semantic versioning

The --bump flag will monotonically increase the version number. By default, the patch version -- that is, the third number in the dotted sequence. This can be explicitly specified by running tag-version --bump --patch.

Similarly, the --minor or --major argument can be given to increment the minor or major versions respectively.

Monorepo support

There is initial support for independently versioning different components within a monorepo structure. Support is using a convention where a component's version is prefixed with the name of the component. For example, a monorepo may have a component named api. Tags for api changes can be prefixed with the name of the component, for example, api/1.2.3.

Special formats

In some cases it's necessary to output the version in different formats. For instance, using tag-version to produce a Docker tag will break docker if a monorepo version as described above is used (docker does not like slashes in the tag). To get a version that is docker-compatible, use the command:

tag-version version --format docker

JSON format

In the event that using the command's output for further processing within another piece of code is desires, the JSON format provides the version in a machine-usable format:

$ tag-version version --format json
{"version_triple": "0.1.0", "major": "0", "minor": "1", "patch": "0", "prefix": "", "prefix_separator": "", "tags": "rc5-1-g2e13a96-feature--handle-monorepo-project-tag", "prerelease": "rc5-1-g2e13a96-feature--handle-monorepo-project-tag", "prerelease_separator": "", "build": ""}

Help text

$ tag-version version --help
usage: tag-version version [-h] [--bump] [--patch] [--minor] [--major]
                           [--set SET] [--no-branch]

optional arguments:
  -h, --help   show this help message and exit
  --bump       perform a version bump, by default the current version is
               displayed
  --patch      bump the patch version, this is the default bump if one is not
               specified
  --minor      bump the minor version and reset patch back to 0
  --major      bump the major version and reset minor and patch back to 0
  --set SET    set version to the given version
  --no-branch  do not append branch to the version when current commit is not
               tagged

Write subcommand

Running tag-version write <path> will rewrite any {{ version }} tags in the given path with the current tag version.

Help text

[berto@g6]$ tag-version write --help
usage: tag-version write [-h] [--branch] [--pattern PATTERN] path

positional arguments:
  path               path to the file to write version in

optional arguments:
  -h, --help         show this help message and exit
  --pattern PATTERN  a regex pattern to search and replace with the version,
                     default "(?P<start>.*?){{\s*version\s*}}(?P<content>.*)"

Release Candidates

To generate a release candidate tag, add the --rc flag to your tag-version --bump invocation:

tag-version --bump --rc

If the latest version if already a release candidate, then bumping with --rc will increment the release candidate number.

Meanwhile if the latest version is a proper release, adding --rc will first bump the version according to the specified flags (e.g --minor) then append -rc1.

Example Usage

# latest tag: 0.0.1
tag-version --bump --minor --rc
# latest tag: 0.1.0-rc1
tag-version --bump --rc
# latest tag: 0.1.0-rc2
tag-version --bump
# latest tag: 0.1.0