git-versioner 2.3

Manage current / next version for project

Manages the version number for the project based on git tags. The goal of this packages versioning scheme is to avoid ever needing to manually create versions numbers or update version details in files that need to be committed to the repository.

The general rule is:

• If on a tag, report that as-is.

• When changes are made / git commits added, auto-increment the desired level of semantic version.

When on a git tag like v1.2 the version will always be reported as v1.2 in short form or v1.2-g<githash>, eg. v1.2-ga1b2c3

After editing, by default the least significant version attribute will be updated, eg v1.2 -> v1.3 or 1.2.3 -> 1.2.4

Version Increments

The increment can be changed by adding one of the following footers to any commit since the previous tag:

• CHANGE: major

• CHANGE: minor

• CHANGE: patch

Then the most significant increment specified in any commit will be used.

Alternatively this can be overridden at runtime by setting the environment variable VERSION_INCREMENT to one of major, minor or patch

By default a 2 point version scheme will be used, eg v1.2 but the patch level (v1.2.3) can be enabled with the env var VERSION_SUPPORT_PATCH set to 1

This setting will be persisted if saved, eg VERSION_SUPPORT_PATCH=1 python -m __version__ --save

Project Version

The overall goal is for any commit to be suitable as a potential release. As such you can build away, testing your main branch builds and as soon as one of them is ready to go simply run python -m __version__ --tag to have it tagged off with the same version number the build already had. Indeed this step can be done in CI, take at a look at this projects’ .gitlab-ci.yml for an example of a manual CI task to “release this commit”.

To use this to auto-version python packages, this projects’ setup.py the following pattern can be followed:

setup(
    name="git-versioner",
    author="Andrew Leech",
    author_email="[e-mail]",
    use_git_versioner=True,
    setup_requires=["git-versioner"],
    ...
)

Runtime Access

To access the version in your project at runtime you can either from __version__ import version, version_short, git_hash, on_tag to auto-calculate each run, or from _version import version, version_short, git_hash, on_tag to get the details from previous run of python __version__ --save

Command Line

Can also be used as command line tool to generate _version.py, print version, rename files or fill a template file with version details.:

usage: __version__.py [-h] [--save] [--short] [--git] [--rename RENAME] [--template template output]

Mange current/next version.

optional arguments:
  -h, --help            show this help message and exit
  --save                Store in _version.py
  --short               Print the short version string
  --git                 Print the release git hash
  --rename RENAME       Add version numbers to filename(s)
  --template template output
                        Add version to <template> and write result to <output>
  --tag                 Creates git tag to release the current commit