repository·master·Indexed 41 days ago
https://github.com/ofek/hatch-vcsA plugin for the Hatch build tool that leverages version control systems, primarily Git, to automatically manage and inject project versions into metadata and version files. It provides a version source, a build hook for generating version files, and a metadata hook for injecting VCS data like commit hashes into project URLs.
If you are migrating from setuptools_scm, you can use hatch commands to interact with the version without a full build:
Display the version (prints to terminal without modifying source):
hatch versionWrite the version to a file (updates the version-file defined in your config without creating sdists/wheels):
hatch build --hooks-onlyTo use hatch-vcs for versioning in a Hatch project, you must include it in the build-system.requires list within your pyproject.toml file.
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"Set the version source plugin name to vcs to allow Hatch to determine the project version from your version control system (e.g., Git).
In pyproject.toml:
[tool.hatch.version]
source = "vcs"In hatch.toml:
[version]
source = "vcs"The vcs build hook can automatically write the current version to a file during the build or install process. The plugin name is vcs.
In pyproject.toml:
[tool.hatch.build.hooks.vcs]
version-file = "_version.py"In hatch.toml:
[build.hooks.vcs]
version-file = "_version.py"If the latest tag is v1.2.3, the generated _version.py will look like:
# 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)The vcs metadata hook allows inserting VCS data (currently only the commit hash) into metadata fields. Note: Only Git is supported.
To use it, add the hook to your configuration and ensure the target fields are listed in project.dynamic.
In pyproject.toml:
[project]
dynamic = [
"urls",
]
[tool.hatch.metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"In hatch.toml:
[metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"Supported context fields for URLs:
commit_hash: the latest commit hash[tool.hatch.metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"When configuring the vcs build hook in pyproject.toml, you can use the following options:
version-file (Required): A string specifying the path to the file where the version will be written.template (Optional): A string representing a template used by setuptools_scm.dump_version to format the version file content. If provided, it must be a string.You can configure the vcs plugin using the following options in your Hatch configuration (e.g., pyproject.toml):
tag-pattern (string): A regex pattern used to match version tags in the VCS. This is passed to setuptools_scm as tag_regex.fallback-version (string): The version to use if no version can be determined from the VCS. This is passed to setuptools_scm as fallback_version.raw-options (table/dict): A dictionary of additional options passed directly to setuptools_scm.Note: Options like write_to and write_to_template are automatically removed from the configuration before being passed to setuptools_scm to avoid conflicts.
The urls option in the VCSMetadataHook configuration must be a table (dictionary). Each key in the table is a name for the URL, and each value must be a string.
Supported formatting:
You can use the {commit_hash} placeholder within the URL strings. The hook will automatically replace this placeholder with the actual commit hash from your VCS at build time.
Errors:
urls is not a table, a TypeError is raised.urls table is not a string, a TypeError is raised.SETUPTOOLS_SCM_PRETEND_VERSION environment variable is defined and not empty, hatch-vcs uses its value as the primary version source (as an unparsed string).The vcs build hook accepts the following 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. Default behavior depends on file extension. |
You can fine-tune how the version is extracted using the following options in your [tool.hatch.version] (pyproject.toml) or [version] (hatch.toml) section:
| Option | Type | Default | Description |
|---|---|---|---|
tag-pattern | str | see code | A regex to extract the version from VCS tags. Must contain a single match group or a group named version |
fallback-version | str | The version used if detection fails. If omitted, failure raises an error | |
raw-options | dict | A table of [setuptools-scm parameters](https://setuptools-scm.readthedocs.io/en/latest/config/) to override defaults. Note: write_toandwrite_to_template` are ignored |
Example: Setting a custom version_scheme via raw-options:
[tool.hatch.version.raw-options]
version_scheme = "no-guess-dev"The VCSBuildHook is a Hatch build hook plugin that automates version file generation using setuptools_scm. It allows you to extract the version from your Version Control System (VCS) and write it to a specified file during the build process.
To use this plugin, you must configure it in your pyproject.toml file. The plugin requires a version-file option to specify where the version should be written.
[tool.hatch.build.hooks.vcs]
version-file = "version.txt"
template = "version = {version}\n"