fix(repo): accept the explicit literal-path constructor option

sbxloop 2.1.36 explicitly opens its metadata repositories with
`Repo(..., expand_vars=False)` to keep repository paths literal. Removing the
constructor option during the storage migration breaks 91 unchanged upstream
cases before their Git queries run. Released GitPython 3.2.1 accepts the option.

Restore the `False` constructor argument, including its fourth positional
location, while retaining the branch's default literal environment-variable
behavior. Reject `True` with a clear `ValueError` directing callers to expand
inputs themselves. Initial tilde expansion and Git/Gix discovery remain as
before; this input compatibility does not restore automatic environment
expansion or introduce Python Git behavior. Document the limited restored
contract and the remaining breaking path/API behavior.

Add a fixture containing both a literal `$DOWNSTREAM_REPOSITORY` repository
and an expansion target. Four SHA-1/SHA-256 and files/reftable regressions fail
before the correction and verify literal contents, keyword/positional use,
the unchanged default, and rejected expansion afterwards. Repository, CLI
safety and downstream suites pass 189 tests, two skips and 14 subtests on each
backend. Ruff lint/format, ShellCheck for the fixture, mypy for
`git/repo/base.py` and `git diff --check` pass with Python 3.12.15,
Git 2.53.0 and GixPython 0.2.0.

Author: codex

doc/gix-backend.md

@@ -45,6 +45,12 @@ fallbacks.
 
 ## Index and object metadata lifecycle
 
+`Repo(..., expand_vars=False)` remains accepted for callers such as sbxloop
+2.1.36 that explicitly require literal paths. The default also keeps environment
+variables literal; `expand_vars=True` is unsupported. Callers wanting expansion
+must perform it before passing the path. Discovery still uses Gix/Git after
+ordinary input-path canonicalization.
+
 `git.GitDB` and `git.db.GitDB` remain compatibility aliases for
 `GitCmdObjectDB`, so legacy `Repo(..., odbt=GitDB)` selectors use the same
 managed backend. Aider 0.86.2 uses that selector for every repository open.

doc/source/changes.rst

@@ -156,8 +156,10 @@ API changes
   are removed; import from ``typing`` or the owning module. ``git.util`` now
   exposes the actual utility module. Abstract ``Traversable.traverse`` and
   ``list_traverse`` raise ``NotImplementedError``; use concrete implementations.
-* Paths and URLs no longer expand ``$VAR``/``%VAR%`` automatically. Removed
-  ``expand_vars`` switches from ``Repo``, ``Repo.init``, ``expand_path``,
+* Paths and URLs no longer expand ``$VAR``/``%VAR%`` automatically. ``Repo``
+  still accepts ``expand_vars=False`` for callers that explicitly select literal
+  paths; ``True`` raises ``ValueError``. Removed ``expand_vars`` switches from
+  ``Repo.init``, ``expand_path``,
   ``cygpath`` and ``Git.polish_url``. Expand explicitly with
   ``os.path.expandvars`` if wanted; initial ``~`` expansion remains.
   ``HIDE_WINDOWS_KNOWN_ERRORS`` and ``HIDE_WINDOWS_FREEZE_ERRORS`` are removed.

git/repo/base.py

@@ -237,6 +237,7 @@ def __init__(
         path: Optional[PathLike] = None,
         odbt: Type[GitCmdObjectDB] = GitCmdObjectDB,
         search_parent_directories: bool = False,
+        expand_vars: bool = False,
         *,
         _env: Optional[Mapping[str, Optional[str]]] = None,
     ) -> None:
@@ -273,6 +274,11 @@ def __init__(
             Please note that this was the default behaviour in older versions of
             GitPython, which is considered a bug though.
 
+        :param expand_vars:
+            The legacy ``False`` option remains accepted to select literal paths.
+            ``True`` is unsupported; expand environment variables explicitly
+            before opening a repository. Initial ``~`` expansion remains enabled.
+
         :raise git.exc.InvalidGitRepositoryError:
 
         :raise git.exc.NoSuchPathError:
@@ -285,6 +291,8 @@ def __init__(
         # process environment. Apply these overrides to discovery and later calls.
         if not isinstance(odbt, type) or not issubclass(odbt, GitCmdObjectDB):
             raise ValueError("odbt must be GitCmdObjectDB or a subclass")
+        if expand_vars:
+            raise ValueError("Environment variable expansion is unsupported; expand the path explicitly")
         environment = dict(_env or {})
         git_dir_env = environment.pop("GIT_DIR", os.getenv("GIT_DIR"))
         object_dir_env = environment.get("GIT_OBJECT_DIRECTORY", os.getenv("GIT_OBJECT_DIRECTORY"))

test/test_downstream_compatibility.py

@@ -7,7 +7,22 @@
 import git
 import git.db
 
-from test.lib.fixtures import fixture_repo
+from test.lib.fixtures import fixture_repo, read_only_fixture
+
+
+@pytest.mark.parametrize("object_format", ["sha1", "sha256"])
+@pytest.mark.parametrize("ref_format", ["files", "reftable"])
+def test_repo_accepts_explicit_literal_path_selection(object_format, ref_format, monkeypatch):
+    root = read_only_fixture("downstream-literal-repo.sh", object_format, ref_format)
+    monkeypatch.setenv("DOWNSTREAM_REPOSITORY", str(root / "expanded"))
+    literal = root / "$DOWNSTREAM_REPOSITORY"
+    for kwargs in ({}, {"expand_vars": False}):
+        with git.Repo(literal, **kwargs) as repo:
+            assert repo.head.commit.tree["tracked"].data_stream.read() == b"$DOWNSTREAM_REPOSITORY"
+    with git.Repo(literal, git.GitCmdObjectDB, False, False) as repo:
+        assert Path(repo.working_tree_dir) == literal
+    with pytest.raises(ValueError, match="Environment variable expansion is unsupported"):
+        git.Repo(literal, expand_vars=True)
 
 
 @pytest.mark.parametrize("object_format", ["sha1", "sha256"])

tests/fixtures/downstream-literal-repo.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -eu
+# Preserve the literal variable spelling to detect accidental expansion.
+# shellcheck disable=SC2016
+for path in '$DOWNSTREAM_REPOSITORY' expanded; do
+    git init -q --object-format="$1" --ref-format="$2" "$path"
+    printf '%s' "$path" > "$path/tracked"
+    git -C "$path" add tracked
+    git -C "$path" commit -qm initial
+done