python-subprocess-env-git-index-leak

Answer

Root cause chain. When git runs a pre-commit hook it exports GIT_INDEX_FILE (plus GIT_DIR, GIT_WORK_TREE, GIT_OBJECT_DIRECTORY, etc.) into the hook's environment. guard_manager spawns its worker subprocess with shell=True and no env=, so the child inherits GIT_INDEX_FILE pointing at the outer repo's index. When a guard runs git inside a tmp/nested repo, git reads the wrong index → 3 test_cli.py tests fail, blocking commits.

Fix 1 — strip the GIT_* namespace from the subprocess env (Go's testGitEnv pattern ported to Python):

# guard_manager/_proc.py
import os
import subprocess

def clean_env() -> dict[str, str]:
    """os.environ copy minus git's GIT_* namespace.

    Pre-commit hooks inherit GIT_INDEX_FILE/GIT_DIR/GIT_WORK_TREE from git.
    A nested guard that spawns git in a tmp repo would otherwise read the
    OUTER repo's index. Strip the whole namespace (not just GIT_INDEX_FILE)
    so nested git invocations are hermetic; PATH~ survive.
    """
    return {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}

def run_guard(cmd: str, cwd: str) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        cmd,
        shell=True,
        cwd=cwd,
        env=clean_env(),          # <-- the fix
        capture_output=True,
        text=True,
    )

Use the same env= on every subprocess.Popen/run in guard_manager (or wrap it in one _popen helper). Don't special-case only GIT_INDEX_FILE — GIT_DIR, GIT_WORK_TREE, GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES, GIT_COMMON_DIR can each redirect a nested git command too.

Fix 2 — tomllib backport for Python 3.10 (DF-009). tomllib is stdlib only on 3.11+; the bare try: import tomllib / except ImportError: pass silently skips pyproject detection on 3.10. Use tomli as a runtime dependency with an env marker, and make the fallback loud:

try:                                    # Python >= 3.11
    import tomllib
except ModuleNotFoundError:             # Python 3.10 and older
    try:
        import tomli as tomllib  # type: ignore[no-redef]
    except ModuleNotFoundError as exc:  # pragma: no cover
        raise RuntimeError(
            "DF-009 pyproject.toml detection needs tomli on Python < 3.11; "
            "install 'tomli>=2.0; python_version < \"3.11\"'"
        ) from exc

pyproject.toml — runtime dep, not dev-dep, so the CI 3.10 job gets it via pip install -e .:

[project]
dependencies = [
    "tomli>=2.0; python_version < '3.11'",
]

[project.optional-dependencies]
dev = [...]   # tomli intentionally NOT here