setuptools-git-versioning is a Python library that automatically infers package versions from Git repository data, adhering to PEP 440. It allows configuration via `pyproject.toml` or `setup.py`/`setup.cfg` and supports tag-, file-, and callback-based versioning schemas with flexible templating. The library is actively maintained, with frequent patch releases and occasional major version bumps introducing breaking changes.
pip install setuptools-git-versioningVerified import paths — ran on the pinned version, not inferred.
Configure `setuptools-git-versioning` in your `pyproject.toml` to dynamically set your package's version based on Git tags and repository state. Ensure `setuptools-git-versioning` is in `build-system.requires` and `project.dynamic = ["version"]` is set.
Review calls to `version_from_git` or `infer_version` (if used against recommendations), ensure keyword arguments are used, and adapt code expecting a string return type or naive timestamps.
Remove usages of `get_branch_tags` and `version_config`. If relying on tag-based versioning, be aware `version_file` will override it if present.
Ensure `git` is installed and the repository has its full `.git` history. For CI/CD, use `git fetch --unshallow` or configure your CI to not use shallow clones. Alternatively, use the `version_file` option to store the version, or provide an environment variable to override it if the library supports it (though `setuptools-git-versioning` officially recommends `version_file` for this scenario).
Add build artifacts and other temporary files to your `.gitignore` file to ensure the repository state is 'clean' during packaging.
To enable dynamic versioning, remove the `version` field from `[project]` and instead add `dynamic = ["version"]` to the `[project]` section.
To retrieve the package version at runtime, use `importlib.metadata.version('your-package-name')` (Python 3.8+) or configure `version_file` to write the version to a file within your package during build, and then read that file at runtime.