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 the project.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 about onbuild below). However, with Hatch, you have two possible locations to put versioningit’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 the onbuild 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!