Hatch Integration
Added in version 2.3.0.
If you’re not a setuptools user, versioningit
can also be used as a version
source plugin for the Hatch build backend. You use it in pretty much the same
way as for setuptools:
Include
versioningit
in your build requirements like so:[build-system] requires = ["hatchling", "versioningit"] build-backend = "hatchling.build"
Tell Hatch that you’re using a dynamic version source by including
"version"
in theproject.dynamic
key:[project] name = "your-project-name" dynamic = ["version"] # The rest of your project metadata follows after. # Do not set the `version` key in [project]. If it's currently set, # remove it.
Tell Hatch to use
versioningit
as the version source:[tool.hatch.version] source = "versioningit"
Configure
versioningit
as normal (mostly; see the note aboutonbuild
below). However, with Hatch, you have two possible locations to putversioningit
’s configuration in: either the[tool.versioningit]
table as used with setuptools or under the[tool.hatch.version]
table. Moreover, unlike when using setuptools, you don’t even need the[tool.versioningit]
table if it’s just going to be empty.For example, the following configurations are equivalent:
Using
[tool.versioningit]
:[tool.hatch.version] source = "versioningit" [tool.versioningit] default-version = "0.0.0+unknown" [tool.versioningit.format] distance = "{next_version}.dev{distance}+{vcs}{rev}" dirty = "{version}+dirty" distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
Using
[tool.hatch.version]
:[tool.hatch.version] source = "versioningit" default-version = "0.0.0+unknown" [tool.hatch.version.format] distance = "{next_version}.dev{distance}+{vcs}{rev}" dirty = "{version}+dirty" distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
If you configure
versioningit
via[tool.hatch.version]
and also define a[tool.versioningit]
table (even if it’s empty), a warning will be emitted, and only the[tool.hatch.version]
configuration will be used.If you use the
write
step to create a file containing your project version, and this file is listed in your.gitignore
or.hgignore
, you will need to tell Hatch to include the file in sdists & wheels like so:[tool.hatch.build] # Replace the path below with the path to the file created by the # `write` step: artifacts = ["src/mypackage/_version.py"]
The configuration for the
onbuild
step is placed in the[tool.hatch.build.hooks.versioningit-onbuild]
table (not in[tool.versioningit.onbuild]
or[tool.hatch.version.onbuild]
). In addition, filling out this table is all you need to do to enable theonbuild
step — no fiddling with command classes necessary!
Note
If you use versioningit
with Hatch, you will not be able to set your
project’s version by running hatch version x.y.z
. Just create a tag
instead!