Package: hatch-vcs
hatch-vcsCI/CDPackageMetaThis provides a plugin forHatchthat uses your preferred version control system (like Git) to determine project versions.Table of ContentsGlobal dependencyVersion sourceVersion source optionsVersion source environment variablesBuild hookBuild hook optionsEditable installsMetadata hookMetadata hook optionsURLsExampleLicenseGlobal dependencyEnsurehatch-vcsis defined within thebuild-system.requiresfield in yourpyproject.tomlfile.[build-system]requires=["hatchling","hatch-vcs"]build-backend="hatchling.build"Version sourceTheversion source pluginname isvcs.pyproject.toml[tool.hatch.version]source="vcs"hatch.toml[version]source="vcs"Version source optionsOptionTypeDefaultDescriptiontag-patternstrseecodeA regular expression used to extract the version part from VCS tags. The pattern needs to contain either a single match group, or a group namedversion, that captures the actual version information.fallback-versionstrThe 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-optionsdictA table ofsetuptools-scmparametersthat will override any of the options listed above. Thewrite_toandwrite_to_templateparameters are ignored.Version source environment variablesSETUPTOOLS_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 hookThebuild hook pluginname isvcs.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 isv1.2.3will 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 optionsOptionTypeDefaultDescriptionversion-filestrREQUIREDThe relative path to the file that gets updated with the current version.templatestrThe template used to overwrite theversion-file. See thecodefor the default template for each file extension.Editable installsThe version file is only updated upon install or build. Thus the version number in aneditable install(Hatch'sdev 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 athatch-vcs-footgun-example.Metadata hookNote:only Git is supportedThemetadata hook pluginis for inserting VCS data (currently the commit hash) into metadata fields other thanversion. Its name isvcs.pyproject.toml[tool.hatch.metadata.hooks.vcs]hatch.toml[metadata.hooks.vcs]Metadata hook optionsURLsTheurlsoption is equivalent toproject.urlsexcept that each URL supportscontext formattingwith the following fields:commit_hash- the latest commit hashBe sure to addurlstoproject.dynamic:pyproject.toml[project]dynamic=["urls",]Examplepyproject.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 tipsIf you are migrating fromsetuptools, you may want access to
the version without performing a full build.By default,python -m setuptools_scmwill display the version and perform any side-effects
like writing to a file.hatchseparates these functions.Display versionhatch versionwill print the version to the terminal without modifying the source directory.$hatchversion23.0.0.dev17+g462372baWrite version to fileIfversion-fileis defined, you can write it to the source directory with thebuildcommand,
using the--hooks-onlyflag to modify the source tree but skip creation of sdists or wheels.$hatchbuild--hooks-only$catpackage/_version.py#filegeneratedbysetuptools_scm#don't change, don'ttrackinversioncontrol__version__ = version = '23.0.0.dev17+g462372ba'__version_tuple__ = version_tuple = (23, 0, 0, 'dev17', 'g462372ba')Licensehatch-vcsis distributed under the terms of theMITlicense.