Generating version tags from Git

---

Pants can generate a version string based on Git state that you can use during builds.

Enabling the Python backend

The implementation of this feature relies on a third-party Python library, so to use it you will need to activate the Python backend and its "experimental" extension, even if you're not otherwise using Python in your repo:

pants.toml

backend_packages.add = [
  ...
  "pants.backend.python",
  "pants.backend.experimental.python",
  ...
]

The vcs_version target

To utilize this functionality, you first create a vcs_version target in some BUILD file, e.g.,:

src/foo/BUILD

vcs_version(
    name="version",
    generate_to="src/foo/version.py",
    template='version = "{version}"',
)

When you test, run or package any code that depends (directly or indirectly) on this target, Pants will compute a version string based on the current Git state, and then generate content using the specified template (with {version} serving as a placeholder for the version string) at the path specified by generate_to.

This content will be available at test and run time, and be packaged along with your code and its dependencies. Your code can use the generated content (e.g., by importing it or reading it) and thus have access to a dynamically-generated version.

Note that, similarly to how Pants handles other code generation tools (such as Protobuf), this content is not written out as a file into your source tree. Instead, the content is materialized on the fly, as needed. If you want to inspect the generated contents manually, you can use the export-codegen goal:

pants export-codegen src/foo:version

Using the generated version

Code that depends on the vcs_version target can import and use the generated file:

src/util.py

from version import version
...

In this example we generated a Python source file, but you can generate code in any language, or even generate a text file for some code to load at runtime.

In fact, in the Python case you don't even need an explicit dependency on the vcs_version target, as one will be inferred from the import. This does not work (yet) for other languages, so those will require an explicit dependency.

The generated version string

Pants delegates the version string computation to setuptools_scm. See here for how it computes the version string from the Git state.

We don't yet support any of the configuration options that control how the string is computed. Please let us know if you need such advanced functionality.