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!