| CI/CD | |
| Package |   |
| Meta |      |
This provides a plugin for Hatch that uses your preferred version control system (like Git) to determine project versions.
Table of Contents
Ensure hatch-vcs is defined within the build-system.requires field in your pyproject.toml file.
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"The version source plugin name is vcs.
-
pyproject.toml
[tool.hatch.version] source = "vcs"
-
hatch.toml
[version] source = "vcs"
| Option | Type | Default | Description |
|---|---|---|---|
tag-pattern |
str |
see code | A regular expression used to extract the version part from VCS tags. The pattern needs to contain either a single match group, or a group named version, that captures the actual version information. |
fallback-version |
str |
The version that will be used if no other method for detecting the version is successful. If not specified, unsuccessful version detection will raise an error. | |
raw-options |
dict |
A table of setuptools-scm parameters that will override any of the options listed above. The write_to and write_to_template parameters are ignored. |
For example, to prevent incrementing version numbers on non-release commits, you can adjust the version_scheme parameter for setuptools-scm as follows:
-
pyproject.toml
[tool.hatch.version.raw-options] version_scheme = "no-guess-dev"
-
hatch.toml
[version.raw-options] version_scheme = "no-guess-dev"
SETUPTOOLS_SCM_PRETEND_VERSION: When defined and not empty, it's used as the primary source for the version, in which case it will be an unparsed string.
The build hook plugin name is vcs.
-
pyproject.toml
[tool.hatch.build.hooks.vcs] version-file = "_version.py"
-
hatch.toml
[build.hooks.vcs] version-file = "_version.py"
Building or installing when the latest tag is v1.2.3 will generate the file
-
_version.py
# coding: utf-8 # file generated by setuptools_scm # don't change, don't track in version control __version__ = version = '1.2.3' __version_tuple__ = version_tuple = (1, 2, 3)
| Option | Type | Default | Description |
|---|---|---|---|
version-file |
str |
REQUIRED | The relative path to the file that gets updated with the current version. |
template |
str |
The template used to overwrite the version-file. See the code for the default template for each file extension. |
The version file is only updated upon install or build. Thus the version number in an editable install (Hatch's dev mode) will be incorrect if the version changes and the project is not rebuilt. An unsupported workaround for keeping the version number up-to-date can be found at hatch-vcs-footgun-example.
Note: only Git is supported
The metadata hook plugin is for inserting VCS data (currently the commit hash) into metadata fields other than version. Its name is vcs.
-
pyproject.toml
[tool.hatch.metadata.hooks.vcs]
-
hatch.toml
[metadata.hooks.vcs]