hatch-vcs


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

Global dependency
Version source
- Version source options
- Version source environment variables
Build hook
- Build hook options
- Editable installs
Metadata hook
- Metadata hook options
  - URLs
- Example
License

Global dependency

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"

Version source

The version source plugin name is vcs.

pyproject.toml
```
[tool.hatch.version]
source = "vcs"
```
hatch.toml
```
[version]
source = "vcs"
```

Version source options

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"

Version source environment variables

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.

Build hook

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)

Build hook options

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.

Editable installs

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.

Metadata hook

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]
```

Metadata hook options

URLs

The urls option is equivalent to project.urls except that each URL supports context formatting with the following fields:

commit_hash - the latest commit hash

Be sure to add urls to project.dynamic:

pyproject.toml
```
[project]
dynamic = [
  "urls",
]
```

Example

pyproject.toml

[tool.hatch.metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"

hatch.toml

[metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"

Migration tips

If you are migrating from setuptools, you may want access to
the version without performing a full build.

By default, python -m setuptools_scm will display the version and perform any side-effects
like writing to a file. hatch separates these functions.

Display version

hatch version will print the version to the terminal without modifying the source directory.

$ hatch version
23.0.0.dev17+g462372ba

Write version to file

If version-file is defined, you can write it to the source directory with the build command,
using the --hooks-only flag to modify the source tree but skip creation of sdists or wheels.

$ hatch build --hooks-only
$ cat package/_version.py
# file generated by setuptools_scm
# don't change, don't track in version control
__version__ = version = '23.0.0.dev17+g462372ba'
__version_tuple__ = version_tuple = (23, 0, 0, 'dev17', 'g462372ba')

License

hatch-vcs is distributed under the terms of the MIT license.

Dependencies of hatch-vcs (2).
Dependency	Optional
hatchling	false
setuptools-scm	false

Package profile

hatch-vcs

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description