Hey! These docs are for version 2.13, which is no longer officially supported. Click here for the latest version, 2.18!

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:

## The `vcs_version` target

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

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:

## Using the generated version

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

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.