setuptools-scm-git-archive

1.4.1 · deprecated · verified Sun Apr 12

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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.
Fix: Ensure your `.gitattributes` file contains the line `.git_archival.txt export-subst`. Additionally, verify that your Git hosting provider supports archive template expansion.
gotcha 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.
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.
gotcha `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.
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.

Install

pip install setuptools-scm-git-archive Latest Version (Deprecated)

Quickstart

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.

# 1. Add to pyproject.toml (for modern projects) or setup.py (legacy)
# pyproject.toml
# [build-system]
# requires = [
#     "setuptools>=61",
#     "setuptools-scm",
#     "setuptools-scm-git-archive" # REMOVE THIS FOR setuptools-scm >= 7.0.0
# ]
# [project]
# dynamic = ["version"]

# setup.py (legacy)
# from setuptools import setup
# setup(
#     name="my_project",
#     use_scm_version=True,
#     setup_requires=['setuptools_scm', 'setuptools-scm-git-archive'], # REMOVE 'setuptools-scm-git-archive' FOR setuptools-scm >= 7.0.0
# )

# 2. Configure .git_archival.txt and .gitattributes
# .git_archival.txt (place in repository root)
# node: $Format:%H$
# node-date: $Format:%cI$
# describe-name: $Format:%(describe:tags=true)$
# ref-names: $Format:%D$ # Consider removing 'ref-names' for more stable archive checksums (see warnings)

# .gitattributes (place in repository root)
# .git_archival.txt export-subst
# .gitignore export-ignore

# 3. Build your project (e.g., from a Git archive)
# git archive --format=tar.gz --output=my_project.tar.gz HEAD
# tar -xf my_project.tar.gz
# cd my_project
# pip install . --no-build-isolation # Or python -m build --sdist

view raw JSON →