Package: git-versioner
git-versionerManages 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
appropriate level of the semantic version.When on a git tag likev1.2the version will be reported asv1.2in
short form orv1.2-g<githash>in the (default) long form, eg.v1.2-ga1b2c3After editing you working tree, by default the minor version attribute
will be updated, egv1.2->v1.3or1.2.3->1.3.0Version IncrementsThe increment can be changed by adding one of the following footers to
any commit since the previous tag:CHANGE: majorCHANGE: minorCHANGE: patchThen the most significant increment specified in any commit will be
used.Alternatively this can be overridden at runtime by setting the
environment variableVERSION_INCREMENTto one ofmajor,minororpatchBy default on new projects a 2 point version scheme will be used, eg
v1.2, however the patch level (v1.2.3) will be used if either:the previous tag includes itpatch level increment is set via commit footer orVERSION_INCREMENTenvthe following env variable is
configured:VERSION_SUPPORT_PATCH=1This setting will be persisted if saved, egVERSION_SUPPORT_PATCH=1 python -m __version__ --saveProject VersionThe 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 runpython -m __version__ --tagto 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.ymlfor an example of a manual CI task to "release this commit".gitlab-versioner can be used to provide dynamic versioning in
setuptools, with support for bothpyproject.tomland the
oldersetup.pyForpyproject.tomlusage; enable dynamic versions in the project section, addgit-versionerto the build requirements list and add a[tool.git-versioner]section to enable git-versioner. Settings[project]name="my-project"...dynamic=["version"][build-system]requires=["setuptools\>=57","wheel","git-versioner>=6.0"]build-backend="setuptools.build_meta"[tool.git-versioner]Alternatively forsetup.py; add the kwarguse_git_versioner=<True or settings>and includegit-versionerin
thesetup_requireslist:setup(name="my-project",author="Andrew Leech",author_email="andrew@alelec.net",use_git_versioner=True,setup_requires=["git-versioner"],...)Dynamic package version optionsIf no extra settings are added to thepyproject.toml/[tool.git-versioner]section, oruse_git_versioner=Trueis set insetup.pythen default
version format will be used.This will be the full / long version followingPEP440local version format.If you want to push the package to PyPI however the short version must
be used which can be specified with :[tool.git-versioner]short=trueoruse_git_versioner="short"The full python version number can also added to the description, which
can be especially useful when the package is published with the short
number. Do enable this you can usedesc = true/use_git_versioner="desc"in which case a line likeversion: 1.2.3+ga1b2c3dwill be added to the bottom of the "long
description" metadata.When building a package, the version details can be automatically saved
into<package>.__version__.pyin the built wheel with the settingsnapshot = true/use_git_versioner="snapshot".If being used in Gitlab CI for builds an automated versioning scheme can
be specified withgitlab = true/use_git_versioner="gitlab". In
this mode, potential release builds from the default / main branch or
from tags will use the short version, with anything else (eg. dev
branches, pr's, local builds) using the long version scheme.Multiple settings can be combined insetup.pybut including them all
in the settings string, eguse_git_versioner="short,desc,snapshot".Runtime AccessTo access the version in your project at runtime you can either:auto-calculate each run:from__version__importversion,version_short,git_hash,on_tagget the details from previous run ofpython __version__ --save:from_versionimportversion,version_short,git_hash,on_tagIn an installed package originally built withuse_git_versioner="snapshot":from.__version__importversion,version_short,git_hash,on_tagTestingThe version number can be overridden with the following envirinment
variables. If any / some of these are set, the rest will fallback to
null / invalid values so ensure you set all the ones that may be needed.GIT_VERSIONER_VERSION
GIT_VERSIONER_VERSION_SHORT
GIT_VERSIONER_GIT_HASH
GIT_VERSIONER_ON_TAG
GIT_VERSIONER_DIRTY
GIT_VERSIONER_VERSION_PY
GIT_VERSIONER_VERSION_PY_SHORTCommand LineCan 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