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

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

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

Example

• pyproject.toml

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

• hatch.toml

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

License

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