{"id":4762,"library":"setuptools-scm-git-archive","title":"setuptools-scm-git-archive","description":"This library is a `setuptools_scm` plugin designed to extract version information from Git archives, such as those automatically generated by platforms like GitHub. It enabled projects to automatically infer their version from Git tags when building from a source archive. As of `setuptools-scm` version 7.0.0 and later, this functionality is natively supported within `setuptools-scm` itself, rendering this plugin largely obsolete. The current version is 1.4.1, with releases occurring infrequently as the project is now considered deprecated.","status":"deprecated","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/Changaco/setuptools_scm_git_archive/","tags":["scm","git","versioning","build-system","setuptools","plugin","archive","deprecated"],"install":[{"cmd":"pip install setuptools-scm-git-archive","lang":"bash","label":"Latest Version (Deprecated)"}],"dependencies":[{"reason":"This is a plugin for setuptools-scm. Versions 7.0.0+ of setuptools-scm render this plugin obsolete.","package":"setuptools-scm","optional":false},{"reason":"setuptools-scm requires setuptools >= 61 (recommended >= 80) for best compatibility.","package":"setuptools","optional":false}],"imports":[],"quickstart":{"code":"# 1. Add to pyproject.toml (for modern projects) or setup.py (legacy)\n# pyproject.toml\n# [build-system]\n# requires = [\n#     \"setuptools>=61\",\n#     \"setuptools-scm\",\n#     \"setuptools-scm-git-archive\" # REMOVE THIS FOR setuptools-scm >= 7.0.0\n# ]\n# [project]\n# dynamic = [\"version\"]\n\n# setup.py (legacy)\n# from setuptools import setup\n# setup(\n#     name=\"my_project\",\n#     use_scm_version=True,\n#     setup_requires=['setuptools_scm', 'setuptools-scm-git-archive'], # REMOVE 'setuptools-scm-git-archive' FOR setuptools-scm >= 7.0.0\n# )\n\n# 2. Configure .git_archival.txt and .gitattributes\n# .git_archival.txt (place in repository root)\n# node: $Format:%H$\n# node-date: $Format:%cI$\n# describe-name: $Format:%(describe:tags=true)$\n# ref-names: $Format:%D$ # Consider removing 'ref-names' for more stable archive checksums (see warnings)\n\n# .gitattributes (place in repository root)\n# .git_archival.txt export-subst\n# .gitignore export-ignore\n\n# 3. Build your project (e.g., from a Git archive)\n# git archive --format=tar.gz --output=my_project.tar.gz HEAD\n# tar -xf my_project.tar.gz\n# cd my_project\n# pip install . --no-build-isolation # Or python -m build --sdist","lang":"python","description":"This quickstart demonstrates the original usage pattern for `setuptools-scm-git-archive` for historical context. However, it is crucial to note that this plugin is obsolete. For projects using `setuptools-scm >= 7.0.0`, simply ensure `setuptools-scm` is in your `build-system.requires` and configure `.git_archival.txt` and `.gitattributes` as shown (but without needing to list `setuptools-scm-git-archive` as a dependency). This setup enables `setuptools-scm` to infer the package version when building from a Git archive."},"warnings":[{"fix":"Remove `setuptools-scm-git-archive` from your project's `setup_requires` (in `setup.py`) or `build-system.requires` (in `pyproject.toml`). Ensure `setuptools-scm >= 7.0.0` is installed and that your `.git_archival.txt` and `.gitattributes` files are correctly configured for `setuptools-scm`'s native archive support.","message":"The `setuptools-scm-git-archive` plugin is obsolete. `setuptools-scm` versions 7.0.0 and above now include native support for Git archives, rendering this plugin unnecessary. Continuing to use it alongside newer `setuptools-scm` versions may lead to conflicts or unexpected behavior.","severity":"breaking","affected_versions":"<=1.4.1"},{"fix":"Use a stable `.git_archival.txt` format that omits `ref-names` unless absolutely necessary and you understand the stability implications. The `setuptools-scm` documentation provides guidance on stable archive configurations.","message":"Including `ref-names: $Format:%D$` in your `.git_archival.txt` can lead to unstable Git archive checksums. The archive's hash may change after new commits are added to branches referenced in the archive, even if the tag itself hasn't moved, which can impact reproducible builds.","severity":"gotcha","affected_versions":"All versions (and setuptools-scm's native support)"},{"fix":"Ensure your `.gitattributes` file contains the line `.git_archival.txt export-subst`. Additionally, verify that your Git hosting provider supports archive template expansion.","message":"Version detection may fail when building from Git archives if the `.gitattributes` file in your repository root is not configured with `export-subst` for `.git_archival.txt`. Without this, Git will not expand the version templates within the archive.","severity":"gotcha","affected_versions":"All versions (and setuptools-scm's native support)"},{"fix":"Ensure your build environment includes a sufficiently recent version of `setuptools`, preferably `setuptools >= 80`. Update your `pyproject.toml`'s `build-system.requires` to specify this requirement.","message":"The `setuptools-scm` library (which this plugin extends) has specific `setuptools` version requirements. `setuptools-scm` requires `setuptools >= 61` at a minimum, with `setuptools >= 80` recommended for optimal compatibility. Using older `setuptools` versions may lead to build failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that releases intended for PyPI are made from clean, tagged commits. If local development versions are causing issues, you might need to configure `setuptools-scm`'s versioning scheme (e.g., `local_scheme` in `pyproject.toml`) or explicitly provide a version for releases. For dirty working directories, a `git tag vX.Y.Z` will produce a clean release version.","message":"`setuptools-scm` (and by extension, projects using this plugin) can generate local versions with `.devXXX` suffixes for untagged commits or dirty working directories. While useful for development, these versions are often invalid for upload to PyPI or other package indexes, which enforce stricter version format compliance.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}