setuptools-git-versioning

Warnings

• breaking Version 3.0.0 introduced breaking changes: most arguments in `version_from_git` became keyword-only, `version_from_git` and `infer_version` now return `packaging.version.Version` objects instead of strings, and timestamps in version templates are now timezone-aware.
  Fix: 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.
• breaking Version 2.0.0 removed the deprecated `get_branch_tags` function and the `version_config` keyword argument from `setup.py`. It also changed the precedence for the `version_file` option, which now takes priority over tags in the current branch.
  Fix: Remove usages of `get_branch_tags` and `version_config`. If relying on tag-based versioning, be aware `version_file` will override it if present.
• gotcha Building in environments without `git` installed or from shallow clones (e.g., GitHub tarballs or CI/CD without full `git` history) can cause `OSError` exceptions or incorrect version detection. The library relies on `git` executable and a full `.git` folder.
  Fix: 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).
• gotcha The package can report a 'dirty' version (e.g., `1.2.3.post0+git.d2bc6516.dirty`) if there are untracked or uncommitted changes in the repository during the build. This is common in CI pipelines due to build artifacts.
  Fix: Add build artifacts and other temporary files to your `.gitignore` file to ensure the repository state is 'clean' during packaging.
• gotcha If you define a static `version = "X.Y.Z"` in the `[project]` section of `pyproject.toml`, `setuptools-git-versioning` will be ignored.
  Fix: To enable dynamic versioning, remove the `version` field from `[project]` and instead add `dynamic = ["version"]` to the `[project]` section.
• gotcha Directly calling internal functions like `setuptools_git_versioning.get_version()` or `get_tag()` from your application's runtime code is strongly discouraged and unsupported. These functions are not part of the public API and may change without backward compatibility. Furthermore, the `.git` folder is not included in the installed package.
  Fix: 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.

Install

• pip install setuptools-git-versioning Install library
• pip install "setuptools-git-versioning<4,>=3.0" Install with version constraint (recommended)

Imports

• setuptools-git-versioning

  python -m setuptools_git_versioning

  Used as a command-line tool or via `python -m` to inspect the inferred version; direct internal Python imports are discouraged for application runtime use.

Quickstart

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.

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

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

[tool.setuptools-git-versioning]
enabled = true
# Optional: Customize version format
# template = "{tag}.post{ccount}+{gitsha}"
# dev_template = "{tag}.dev{ccount}+{gitsha}"
# dirty_template = "{tag}.dirty{ccount}+{gitsha}"