CMake Git Version
December 31, 2025 ยท View on GitHub
Seamlessly integrate git version tags into your CMake project. Inspired by Versioneer for Python projects.
This small CMake script ensures that your project's internal version metadata is always up-to-date with Git version data, whether your repository is cloned or exported as a source tarball via the GitHub release mechanism.
The targeted version format is Semantic Versioning, but CgvFindVersion provides hooks to support other formats.
Installation
A tiny installation script copies the files in the cmake directory to your
project's CMake directory and configures the gitattributes file.
$ ./install.sh /path/to/myproject/cmake
-- Copied script to /path/to/myproject/cmake/CgvFindVersion.cmake
-- Updated /path/to/myproject/cmake/.gitattributes
Usage
Typically you will want to use the exported version metadata from CGV to inform CMake of your project's version:
# OPTIONAL: provide fallback version for the case of shallow git clones
# set(MyProject_VERSION 1.2.3)
include("${CMAKE_CURRENT_LIST_DIR}/cmake/CgvFindVersion.cmake")
cgv_find_version(MyProject)
project(MyProject VERSION "${MyProject_VERSION}" LANGUAGES CXX)
CMake will parse the supplied version number into major/minor/patch versions
that can be used by a config.h.in file:
static const char myproject_version[] = "@MyProject_VERSION_STRING@";
static const int myproject_version_major = @PROJECT_VERSION_MAJOR@;
static const int myproject_version_minor = @PROJECT_VERSION_MINOR@;
static const int myproject_version_patch = @PROJECT_VERSION_PATCH@;
which will let CMake generate a header file:
configure_file("config.h.in" "MyProject_config.h" @ONLY)
You can test the version information by running CMake from the command line:
cmake -P cmake/CgvFindVersion.cmake
and you can integrate your code's version into shell scripts or other workflows with
cmake -DONLY=VERSION -P CgvFindVersion.cmake
which writes the parsed version to stderr.