versioningit 3.1.3

Installation & Setup

versioningit requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install versioningit and its dependencies:

python3 -m pip install versioningit

However, usually you won’t need to install versioningit in your environment directly. Instead, you specify it in your project’s pyproject.toml file in the build-system.requires key, like so:

# If using Setuptools:
[build-system]
requires = [
    "setuptools",
    "versioningit",
]
build-backend = "setuptools.build_meta"

# If using Hatch:
[build-system]
requires = [
    "hatchling",
    "versioningit",
]
build-backend = "hatchling.build"

# This setting is also required if you're using Hatch:
[tool.hatch.version]
source = "versioningit"

Then, you configure versioningit by adding a [tool.versioningit] table to your pyproject.toml. See the documentation for details, but you can get up & running with just the minimal configuration, an empty table:

[tool.versioningit]

versioningit eliminates the need to list an explicit version in setup.py, setup.cfg, or pyproject.toml (and any explicit version you do list will be ignored when using versioningit), so you should remove any such settings in order to reduce confusion.

Note: If you’re specifying your project metadata via a [project] table in pyproject.toml, you need to set project.dynamic = ["version"] in order for versioningit to work.

Once you have a [tool.versioningit] table in your pyproject.toml — and once your repository has at least one tag — building your project with build or similar will result in your project’s version automatically being set based on the latest tag in your Git repository. You can test your configuration and see what the resulting version will be using the versioningit command (see the documentation).

Example Configurations

One of versioningit’s biggest strengths is its ability to configure the version format using placeholder strings. The default format configuration looks like this:

[tool.versioningit.format]
# Format used when there have been commits since the most recent tag:
distance = "{base_version}.post{distance}+{vcs}{rev}"
# Example formatted version: 1.2.3.post42+ge174a1f

# Format used when there are uncommitted changes:
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922

# Format used when there are both commits and uncommitted changes:
distance-dirty = "{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3.post42+ge174a1f.d20230922

Other format configurations of interest include:

• The default format used by setuptools_scm:

  [tool.versioningit.next-version]
  method = "smallest"
  
  [tool.versioningit.format]
  distance = "{next_version}.dev{distance}+{vcs}{rev}"
  # Example formatted version: 1.2.4.dev42+ge174a1f
  
  dirty = "{base_version}+d{build_date:%Y%m%d}"
  # Example formatted version: 1.2.3+d20230922
  
  distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
  # Example formatted version: 1.2.4.dev42+ge174a1f.d20230922

• The format used by versioneer:

  [tool.versioningit.format]
  distance = "{base_version}+{distance}.{vcs}{rev}"
  # Example formatted version: 1.2.3+42.ge174a1f
  
  dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
  # Example formatted version: 1.2.3+42.ge174a1f.dirty
  
  distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
  # Example formatted version: 1.2.3+42.ge174a1f.dirty

• The format used by vcversioner:

  [tool.versioningit.format]
  distance = "{base_version}.post{distance}"
  # Example formatted version: 1.2.3.post42
  
  dirty = "{base_version}"
  # Example formatted version: 1.2.3
  
  distance-dirty = "{base_version}.post{distance}"
  # Example formatted version: 1.2.3.post42