Add support for git archive generated git info files

ktbarrett · ktbarrett · commit ddae79ff2522 · 2026-05-04T15:41:03.000-04:00
The user is intended to write a template file and modify git attributes
to fill in the template with repo information when building the archive.
This is used by Github's `Download as ZIP` function. The implementation
largely follows setuptools-scm's with some minor caveats:
* This tool supports branch in template, this defaults to HEAD when
  there is no branch, just like the case where we have branch info.
* The precedence of version resolving is a bit different. Here we do
  PKG-INFO, then archive file, then git info, while setuptools-scm
  puts git info first, assuming any git info must be the current repo's
  git info. This does mean that dirty clones that have the archival file
  will accidentally use that, but that should be somewhat obvious of a
  diagnosis.
diff --git a/docs/changelog/next_release/131.feature.rst b/docs/changelog/next_release/131.feature.rst
@@ -0,0 +1,5 @@
+Add support for ``git archive`` builds via a tracked ``.git_archival.txt``
+file. When the file is present and its ``$Format:...$`` placeholders have
+been substituted, the version is derived from its contents instead of
+running ``git``. See ``git_archive`` documentation for the required
+``.git_archival.txt`` and ``.gitattributes`` setup.
diff --git a/docs/comparison.rst b/docs/comparison.rst
@@ -37,7 +37,7 @@ VCS support
 +---------------------------+-----+-----------+-------------------------------+-----------------------------+
 | Package                   | Git | Mercurial | Can be used in git submodules | Support for ``git-archive`` |
 +===========================+=====+===========+===============================+=============================+
-| setuptools-git-versioning | yes |     no    |             yes               |              no             |
+| setuptools-git-versioning | yes |     no    |             yes               |             yes             |
 +---------------------------+-----+-----------+-------------------------------+-----------------------------+
 | setuptools-scm            | yes |    yes    |             yes               |             yes             |
 +---------------------------+-----+-----------+-------------------------------+-----------------------------+
diff --git a/docs/git_archive.rst b/docs/git_archive.rst
@@ -0,0 +1,105 @@
+.. _git-archive:
+
+Supporting ``git archive`` builds
+---------------------------------
+
+By default ``setuptools-git-versioning`` reads version information by running
+``git`` against the project's ``.git`` directory. When the project is built
+from a ``git archive`` tarball (for example, GitHub's "Download ZIP", or a
+manual ``git archive HEAD -o release.tar``), no ``.git`` directory exists and
+``git`` cannot be invoked.
+
+To make ``git archive`` builds work, add a ``.git_archival.txt`` file to your
+repository whose contents will be rewritten by git at archive time. The
+project will read the rewritten file when building from the archive.
+
+Setup
+~~~~~
+
+1. Create ``.git_archival.txt`` in the repository root:
+
+   .. code-block:: text
+       :caption: .git_archival.txt
+
+       node: $Format:%H$
+       describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
+
+2. Tell git to substitute the ``$Format:...$`` placeholders by adding the
+   following line to ``.gitattributes`` in the repository root (creating the
+   file if it does not exist):
+
+   .. code-block:: text
+       :caption: .gitattributes
+
+       .git_archival.txt  export-subst
+
+3. Commit both files:
+
+   .. code-block:: bash
+
+       git add .git_archival.txt .gitattributes
+       git commit -m "add git archive support"
+
+When ``git archive`` runs, the placeholders are expanded into the actual
+commit SHA and ``git describe`` output for the archived commit. When the
+package is later built from the extracted archive,
+``setuptools-git-versioning`` reads the file and resolves the version using
+the configured ``template`` / ``dev_template`` / ``dirty_template``.
+
+The same file format is used by ``setuptools-scm``, so a single
+``.git_archival.txt`` works with both tools.
+
+Optional: include branch information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your templates reference ``{branch}``, also add a ``ref-names`` line:
+
+.. code-block:: text
+    :caption: .git_archival.txt (with branch info)
+
+    node: $Format:%H$
+    describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
+    ref-names: $Format:%D$
+
+.. warning::
+
+    Including ``ref-names`` causes the archive's contents to change every
+    time a new ref points at the archived commit (for example, when a new
+    branch is created). This breaks archive checksum stability across
+    re-archivals of the same commit. Only opt in if you actually need
+    ``{branch}`` substitution.
+
+If ``ref-names`` is not present (or is present but indicates a detached
+``HEAD``) and a template references ``{branch}``, the literal string
+``HEAD`` is substituted - matching the output of
+``git rev-parse --abbrev-ref HEAD`` in detached-HEAD state.
+
+Priority and interaction with other schemas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The version source is selected in this order:
+
+1. ``PKG-INFO`` (sdist install) - wins whenever present.
+2. ``.git_archival.txt`` - used when the file exists and its placeholders
+   have been substituted.
+3. The normal flow: ``version_callback``, ``version_file``, live ``git``
+   commands, ``starting_version``.
+
+This means ``.git_archival.txt`` only takes effect when there is no
+``PKG-INFO`` (so a normal sdist install still wins) and is opportunistic in
+working checkouts: a stray un-substituted file logs a warning and is
+ignored, falling through to the live ``git`` flow.
+
+Limitations
+~~~~~~~~~~~
+
+- ``tag_filter``, ``tag_formatter``, and ``sort_by`` have no effect on
+  archive builds. The tag is whatever ``git describe`` chose at archive
+  time.
+- ``count_commits_from_version_file`` and ``version_file`` are not consulted
+  in the archive flow.
+- Older git versions (<2.32) do not understand the ``%(describe...)``
+  placeholder. In that case the file is left with the literal text
+  ``%(describe...)`` and ``setuptools-git-versioning`` will warn and fall
+  back to the ``ref-names`` field for the tag (which only succeeds when
+  ``HEAD`` is exactly on a tag).
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,6 +18,7 @@
     command
     ci
     runtime_version
+    git_archive
     schemas/index
     options/index
     substitutions/index
diff --git a/setuptools_git_versioning/__init__.py b/setuptools_git_versioning/__init__.py
@@ -2,6 +2,7 @@
 
 from typing import TYPE_CHECKING, Any
 
+from setuptools_git_versioning.archival import parse_archival_file, version_from_archival
 from setuptools_git_versioning.git import (
     count_since,
     get_all_tags,
@@ -37,5 +38,7 @@ def parse_config(dist: Distribution, attr: Any, value: Any) -> None:
     "get_version",
     "infer_version",
     "is_dirty",
+    "parse_archival_file",
+    "version_from_archival",
     "version_from_git",
 ]
diff --git a/setuptools_git_versioning/archival.py b/setuptools_git_versioning/archival.py
@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import logging
+import os  # noqa: TC003
+import re
+from dataclasses import dataclass
+from email.parser import HeaderParser
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from setuptools_git_versioning.defaults import (
+    DEFAULT_DEV_TEMPLATE,
+    DEFAULT_DIRTY_TEMPLATE,
+    DEFAULT_TEMPLATE,
+)
+from setuptools_git_versioning.log import DEBUG, INFO
+from setuptools_git_versioning.subst import resolve_substitutions
+
+if TYPE_CHECKING:
+    from packaging.version import Version
+
+ARCHIVAL_FILENAME = ".git_archival.txt"
+DESCRIBE_UNSUPPORTED = "%(describe"
+FORMAT_UNSUBSTITUTED = "$Format"
+DESCRIBE_PARTS = 3  # tag-N-gSHA
+
+REF_TAG_RE = re.compile(r"(?<=\btag: )([^,]+)\b")
+REF_HEAD_RE = re.compile(r"HEAD\s*->\s*([^,]+)")
+FULL_SHA_RE = re.compile(r"^([0-9a-f]{40}|[0-9a-f]{64})$")  # SHA-1 or SHA-256
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ArchivalData:
+    tag: str
+    ccount: int
+    sha: str
+    full_sha: str
+    dirty: bool
+    branch: str | None
+
+
+def parse_archival_file(path: str | os.PathLike) -> dict[str, str]:
+    """Read a .git_archival.txt file and return its key/value pairs.
+
+    Keys are normalized to lowercase so lookups behave consistently
+    regardless of whether the file uses `node:` or `Node:` etc.
+    """
+    content = Path(path).read_text(encoding="utf-8")
+    log.log(DEBUG, "'%s' content:\n%s", ARCHIVAL_FILENAME, content)
+    message = HeaderParser().parsestr(content)
+
+    # HeaderParser treats the first blank line as the end of headers.
+    # Anything after it ends up in the message body and is silently
+    # dropped from .items(). Warn the user instead of losing fields.
+    payload = message.get_payload()
+    if isinstance(payload, str) and payload.strip():
+        log.warning(
+            "'%s' contains content after a blank line; those fields will be ignored",
+            ARCHIVAL_FILENAME,
+        )
+
+    return {key.lower(): value for key, value in message.items()}
+
+
+def _parse_describe(describe: str) -> tuple[str, int, str | None, bool]:
+    """Parse a `git describe`-style string into (tag, ccount, short_sha, dirty)."""
+    dirty = False
+    if describe.endswith("-dirty"):
+        dirty = True
+        describe = describe[: -len("-dirty")]
+
+    parts = describe.rsplit("-", 2)
+    if len(parts) < DESCRIBE_PARTS:
+        return describe, 0, None, dirty
+
+    tag, ccount_str, gnode = parts
+    try:
+        ccount = int(ccount_str)
+    except ValueError:
+        return describe, 0, None, dirty
+
+    short_sha = gnode[1:] if gnode.startswith("g") else gnode
+    return tag, ccount, short_sha, dirty
+
+
+def _branch_from_ref_names(ref_names: str) -> str | None:
+    match = REF_HEAD_RE.search(ref_names)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def archival_to_version_data(data: dict[str, str]) -> ArchivalData | None:
+    """Convert parsed archival data into structured version info, or None.
+
+    Returns None when the file looks unsubstituted or otherwise unusable so
+    the caller can fall through to live git.
+    """
+    if any(FORMAT_UNSUBSTITUTED in value for value in data.values()):
+        log.warning(
+            "'%s' contains unprocessed '$Format:...$' placeholders, skipping",
+            ARCHIVAL_FILENAME,
+        )
+        return None
+
+    node = data.get("node", "").strip()
+    full_sha = node if FULL_SHA_RE.match(node) else ""
+    ref_names = data.get("ref-names", "")
+    branch = _branch_from_ref_names(ref_names)
+    describe = data.get("describe-name", "").strip()
+
+    describe_tag: str | None = None
+    ccount = 0
+    short_sha = ""
+    dirty = False
+
+    if describe and DESCRIBE_UNSUPPORTED not in describe:
+        describe_tag, ccount, parsed_sha, dirty = _parse_describe(describe)
+        if parsed_sha:
+            short_sha = parsed_sha
+    elif describe:
+        log.warning(
+            "git archive did not expand %(describe...) (git <2.32), falling back to ref-names",
+        )
+
+    if describe_tag is not None:
+        tag = describe_tag
+    else:
+        tags = REF_TAG_RE.findall(ref_names)
+        if not tags:
+            log.log(
+                INFO,
+                "'%s' has no usable describe-name or tag in ref-names",
+                ARCHIVAL_FILENAME,
+            )
+            return None
+        tag = tags[0].strip()
+
+    # Prefer the full SHA when available so {sha} matches the live-git
+    # path's `full_sha[:8]` rendering. Fall back to the short SHA from
+    # describe-name only when no valid `node` field is present.
+    if full_sha:
+        short_sha = full_sha[:8]
+    elif short_sha:
+        full_sha = short_sha
+
+    return ArchivalData(
+        tag=tag,
+        ccount=ccount,
+        sha=short_sha[:8],
+        full_sha=full_sha,
+        dirty=dirty,
+        branch=branch,
+    )
+
+
+def version_from_archival(
+    project_root: str | os.PathLike,
+    *,
+    template: str = DEFAULT_TEMPLATE,
+    dev_template: str = DEFAULT_DEV_TEMPLATE,
+    dirty_template: str = DEFAULT_DIRTY_TEMPLATE,
+) -> Version | None:
+    """Return a Version derived from .git_archival.txt, or None if unavailable."""
+    archival_path = Path(project_root).joinpath(ARCHIVAL_FILENAME)
+    if not archival_path.exists():
+        log.log(DEBUG, "No '%s' present at '%s'", ARCHIVAL_FILENAME, project_root)
+        return None
+
+    log.log(INFO, "File '%s' is found, reading its content", archival_path)
+    data = parse_archival_file(archival_path)
+    info = archival_to_version_data(data)
+    if info is None:
+        return None
+
+    log.log(DEBUG, "Parsed archival data: %r", info)
+
+    if info.dirty:
+        log.log(INFO, "Using template from 'dirty_template' option")
+        chosen = dirty_template
+    elif info.ccount > 0:
+        log.log(INFO, "Using template from 'dev_template' option")
+        chosen = dev_template
+    else:
+        log.log(INFO, "Using template from 'template' option")
+        chosen = template
+
+    # When ref-names is absent or doesn't reveal a current branch, default
+    # to the literal "HEAD" so `{branch}` substitution mirrors what
+    # `git rev-parse --abbrev-ref HEAD` produces in detached-HEAD state.
+    branch = info.branch if info.branch is not None else "HEAD"
+
+    rendered = resolve_substitutions(
+        chosen,
+        sha=info.sha,
+        tag=info.tag,
+        ccount=info.ccount,
+        branch=branch,
+        full_sha=info.full_sha,
+    )
+    log.log(INFO, "Version number after resolving substitutions: %r", rendered)
+
+    # Deferred to avoid a top-level circular import:
+    # `version.py` imports `version_from_archival` from this module.
+    from setuptools_git_versioning.version import sanitize_version
+
+    return sanitize_version(rendered)
diff --git a/setuptools_git_versioning/version.py b/setuptools_git_versioning/version.py
@@ -11,6 +11,7 @@
 # where 'packaging' is not installed yet
 from packaging.version import Version
 
+from setuptools_git_versioning.archival import version_from_archival
 from setuptools_git_versioning.defaults import (
     DEFAULT_DEV_TEMPLATE,
     DEFAULT_DIRTY_TEMPLATE,
@@ -114,6 +115,16 @@ def version_from_git(  # noqa: PLR0915, PLR0912, PLR0913, C901
                 # running on sdist package, do not sanitize
                 return Version(version_str)
 
+    archival_version = version_from_archival(
+        project_root,
+        template=template,
+        dev_template=dev_template,
+        dirty_template=dirty_template,
+    )
+    if archival_version is not None:
+        log.log(INFO, "Resolved version from '.git_archival.txt': %s", archival_version)
+        return archival_version
+
     if version_callback is not None:
         if version_file is not None:
             msg = "Either 'version_file' or 'version_callback' can be passed, but not both at the same time"
diff --git a/tests/test_integration/test_archival.py b/tests/test_integration/test_archival.py
