{"id":3272,"library":"setuptools-git-versioning","title":"setuptools-git-versioning","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/dolfinus/setuptools-git-versioning","tags":["setuptools","versioning","git","pep440","build-system"],"install":[{"cmd":"pip install setuptools-git-versioning","lang":"bash","label":"Install library"},{"cmd":"pip install \"setuptools-git-versioning<4,>=3.0\"","lang":"bash","label":"Install with version constraint (recommended)"}],"dependencies":[{"reason":"Build-system requirement for package metadata and build backend.","package":"setuptools","optional":false},{"reason":"Build-system requirement for building distribution archives.","package":"wheel","optional":false}],"imports":[{"note":"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.","symbol":"setuptools-git-versioning","correct":"python -m setuptools_git_versioning"}],"quickstart":{"code":"[build-system]\nrequires = [\"setuptools>=41\", \"wheel\", \"setuptools-git-versioning>=3.0,<4\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"my_package\"\ndynamic = [\"version\"]\n\n[tool.setuptools-git-versioning]\nenabled = true\n# Optional: Customize version format\n# template = \"{tag}.post{ccount}+{gitsha}\"\n# dev_template = \"{tag}.dev{ccount}+{gitsha}\"\n# dirty_template = \"{tag}.dirty{ccount}+{gitsha}\"","lang":"toml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add build artifacts and other temporary files to your `.gitignore` file to ensure the repository state is 'clean' during packaging.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To enable dynamic versioning, remove the `version` field from `[project]` and instead add `dynamic = [\"version\"]` to the `[project]` section.","message":"If you define a static `version = \"X.Y.Z\"` in the `[project]` section of `pyproject.toml`, `setuptools-git-versioning` will be ignored.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}