setuptools-git-versioning 3.1.0

Use git repo data for building a version number according to PEP-440

Use git repo data (latest tag, current commit hash, etc) for building a version number according to PEP 440.

Features:

• Can be installed & configured through both setup.py and PEP 518’s pyproject.toml

• Does not require to change source code of the project

• Tag-, file-, and callback-based versioning schemas are supported

• Templates for tag, dev and dirty versions are separated

• Templates support a lot of substitutions including git and environment information

• Well-documented

See comparison between setuptools-git-versioning and other tools.

Limitations:

• Currently the only supported VCS is Git

• Only Git v2 is supported

• Setuptools and scikit-build-core build backends are supported (no Poetry & others)

• Currently does not support automatic exporting of package version to a file for runtime use (but you can use setuptools-git-versioning > file redirect instead)

Documentation

See https://setuptools-git-versioning.readthedocs.io/en/stable/

Install

pyproject.toml

Just add setuptools-git-versioning to build-sytem section of your pyproject.toml, add a section tool.setuptools-git-versioning with config options, and mark the project version as dynamic.

[build-system]
requires = [ "setuptools>=41", "wheel", "setuptools-git-versioning>=3.0,<4", ]
build-backend = "setuptools.build_meta"

[tool.setuptools-git-versioning]
enabled = true

[project]
dynamic = ["version"]

And check the package version generated (see command help):

$ python -m setuptools_git_versioning
0.0.1

# or

$ setuptools-git-versioning
0.0.1

When add a git tag:

$ git add .
$ git commit -m "Test tagged"
$ git tag 1.2.3

And now version is based on git tag:

$ setuptools-git-versioning
1.2.3

$ echo 1 > uncommitted.change
$ git add .
$ setuptools-git-versioning
1.2.3.post0+git.d2bc6516.dirty

$ git commit -m "Test committed"
$ setuptools-git-versioning
1.2.3.post1+git.d452190b

setup.py

Just add setuptools-git-versioning to setup_requires argument of setuptools.setup function call, and then add new argument setuptools_git_versioning with config options:

import setuptools

setuptools.setup(
    ...,
    setuptools_git_versioning={
        "enabled": True,
    },
    setup_requires=["setuptools-git-versioning>=3.0,<4"],
)

Commands are the same as above, plus python -m setup.py returns the same version.

scikit-build-core

If your project uses the scikit-build-core build backend, add setuptools-git-versioning to build-system.requires, mark the version field as dynamic, register the dynamic-metadata provider, and configure options under the usual [tool.setuptools-git-versioning] section:

[build-system]
requires = [ "scikit-build-core", "setuptools-git-versioning>=3.0,<4", ]
build-backend = "scikit_build_core.build"

[project]
name = "mypackage"
dynamic = ["version"]

[tool.scikit-build.metadata.version]
provider = "setuptools_git_versioning.scikit_metadata"

[tool.setuptools-git-versioning]
enabled = true

All options under [tool.setuptools-git-versioning] work exactly as the for setuptools backend. Inline configuration under [tool.scikit-build.metadata.version] is not supported.