git-version

Make git version information (e.g. git tag name, git commit id, ...) available to your source files. A simple use case scenario is to output this version information when the application is called with "--version".

This repository contains

• A python script to generate C++ headers or python modules with this version information. You can add the python script to your build process to autogenerate the files on each build.
• A CMake script which can be directly included into a CMake projects. It will then automatically be run on each build and you only have to #include the generated file.

Use manually (C++ and Python)

Install (editable only)

Requirements, before installing the tool:

• git
• python3

To install the tool:

cd /PATH/TO/git-version
pip install -e . 

!WARNING!: ONLY USE WITH AN EDITABLE INSTALLATION

To generate a version.h file containing C++ version information for the git repository located in myrepositorydir:

python -m gitversionbuilder --dir myrepositorydir --lang cpp version.h

Or to generate a module with version information for python:

python -m gitversionbuilder --dir myrepositorydir --lang python version.py

Available Information

Basic Information

The following table shows the basic variables that are always available.

VERSION_STRING	1.0	Built from git tag "1.0".
	v0.8alpha	Built from git tag "v0.8alpha".
	0.8.dev3+rev4fa254c	Built from 3 commits after git tag "0.8". The current git commit has commit id 4fa254c.
	dev2+rev4fa254c	The repository doesn't have any git tags yet. There are 2 commits since the repository started and the current git commit has commit id 4fa254c.
	0.8-modified	The suffix "-modified" will be used if there have been modifications since the last commit.
	0.8.dev3+rev4fa254c-modified
GIT_TAG_NAME	The name of the last git tag. If there is no git tag, then this is the name of the git branch.
GIT_COMMITS_SINCE_TAG	The number of git commits since the last git tag. If the repository doesn't have any git tags, then this is the number of git commits since the repository started
GIT_COMMIT_ID	The commit id of the git commit this was built from.
MODIFIED_SINCE_COMMIT	True, if there are uncommitted changes in the git working directory or index since the last commit; i.e. untracked (and not ignored) files, or modified files in the working directory or the index.
IS_DEV_VERSION	True, if this is a development version; i.e. there are no tags yet or GIT_COMMITS_SINCE_TAG > 0 or MODIFIED_SINCE_COMMIT.

Additional Information

We will parse the git tag name and provide additional information if you use the following versioning scheme for your git tag names:

/^v?[0-9]+(\.[0-9]+)*(-?((alpha|beta|rc|pre|m)[0-9]?|stable|final))?$/

In words, we support a set of numeric version components separated by a dot, then optionally a version tag like "alpha", "beta", "beta2", "rc2", "M3", "pre2", "stable", "final". The version tag can optionally be separated with a dash and the version number can optionally be prefixed with "v". The version tag is matched case insensitive. It is for example also allowed to write "RC" instead of "rc".

Examples for supported version numbers:

• 0.8.1
• v3.0
• 1.1-alpha
• 1.2alpha
• 1.4.3beta
• 1.4.3beta2
• 2.0-M2
• 4-RC2
• 3.0final
• 2.1-stable
• ...

If you use a version scheme supported by this, we will provide the following additional information

IS_STABLE_VERSION	True, if built from a final tag; i.e. IS_DEV_VERSION == false and GIT_COMMITS_SINCE_TAG == 0 and VERSION_TAG in {"", "stable", "final"}
VERSION_COMPONENTS	An array containing the version number split at the dots. That is, git tag "1.02.3alpha" will have VERSION_COMPONENTS=["1","02","3"].
VERSION_TAG	The version tag ("alpha", "beta", "rc4", "M2", "stable", "final", "", ...) that follows after the version number. If the version tag is separated by a dash, the dash is not included.