fix(repo): retain checkout context for separate Git directories

Mistral Vibe 3.0.1's two separate-directory worktree tests fail when
`Repo.init(..., separate_git_dir=...)` returns the administrative directory's
parent as `working_tree_dir`. Index staging then cannot find the files in the
requested checkout. Released GitPython 3.2.1 passes the same tests.

Distinguish a checkout's `.git` file from an arbitrary gitfile operand when
opening a discovery candidate. Reopen the canonical checkout gitfile through
`gix.open_opts()` and use its native `Repository.workdir()` result; reopening
only its administrative target discards the supplied checkout context. Keep
the existing canonical administrative reopen for standalone arbitrary-gitfile
helpers and their GIX-14 workaround. In the CLI path, ask Git for the top-level
directory from the supplied checkout instead of inferring it from metadata.
Document the adapter correction without closing upstream compatibility bugs.

Add a relocatable Bash fixture and staging/commit regression across SHA-1 and
SHA-256 with files and reftable references. All four regressions failed on
each backend before the change. Also execute linked-worktree regression
fixtures at their final location because their absolute registrations cannot
be safely copied between tests.

The repository and downstream regression suites passed 145 tests, two skips
and 14 subtests on CLI. Adding native/canonical gitfile tests passed 247 tests,
two skips and 14 subtests with Gix. Both original Mistral Vibe regressions
passed on each backend. Ruff lint/format, ShellCheck and mypy passed with
Python 3.12.15, Git 2.53.0 and GixPython 0.2.0. The remaining downstream bare
cleanup failure is a GC-timing assumption: both released and local GitPython
call `close()` from finalization, but at different times.

Author: codex

doc/gix-backend.md

@@ -50,6 +50,16 @@ The compatibility `entries` property projects those queries into a read-only
 snapshot keyed by path and stage, preserving readers in dlt and Renku. It uses
 the same Gix-backed default-index query or documented Git fallback as
 `iter_entries()`; snapshots do not become editable index state.
+
+Discovery distinguishes a checkout's `.git` file from an arbitrary gitfile
+operand. Gix reopens the canonical checkout gitfile through `gix.open_opts()`
+and returns `Repository.workdir()` for separate Git directories. Reopening only
+the administrative directory loses that checkout context. Standalone gitfile
+helpers still reopen the canonical native Git directory to avoid the known
+arbitrary-gitfile mismatch (GIX-14). The CLI path uses `rev-parse --show-toplevel`
+from the supplied checkout. Mistral Vibe 3.0.1 and scripted SHA-1/SHA-256,
+files/reftable regressions verify this adapter correction with Git 2.53.0 and
+GixPython 0.2.0; it does not close GIX-14's upstream compatibility bugs.
 Deferred/virtual state consists of opaque file bytes, materialized before Git
 operates and read back only after success. Private edits use Git because native
 bindings cannot load an arbitrary existing index (GIX-3) or validate a checked

git/_backend.py

@@ -57,7 +57,7 @@ def _fallback(method: str, reason: str) -> Any:
     return NotImplemented
 
 
-def discover_repository(path: str, environment: Dict[str, Any]) -> Any:
+def discover_repository(path: str, environment: Dict[str, Any], *, from_worktree: bool = False) -> Any:
     """Open one discovery candidate; the caller controls parent traversal."""
     if gix is None:
         return NotImplemented
@@ -73,7 +73,11 @@ def discover_repository(path: str, environment: Dict[str, Any]) -> Any:
     )
     try:
         repo = gix.open_opts(path, options)
-        if os.path.isfile(path):
+        if os.path.isfile(path) and from_worktree:
+            # Canonicalize the supplied checkout path and let Gix resolve both
+            # its Git directory and worktree from that .git file.
+            repo = gix.open_opts(os.path.realpath(path), options)
+        elif os.path.isfile(path):
             # Reopening also makes Gix derive the worktree from its Git directory,
             # rather than retaining an arbitrary gitfile's location as a worktree.
             repo = gix.open_opts(os.path.realpath(repo.git_dir()), options)

git/repo/base.py

@@ -326,7 +326,7 @@ def __init__(
             try:
                 # Git resolves relative gitfile targets using the last forward
                 # slash in this operand, including on Windows.
-                native = _backend.discover_repository(candidate, environment)
+                native = _backend.discover_repository(candidate, environment, from_worktree=candidate == dotgit)
                 git_dir = (
                     probe._call_process_safe("rev_parse", "--resolve-git-dir", to_native_path_linux(candidate))
                     if native is NotImplemented
@@ -357,6 +357,14 @@ def __init__(
         if git_dir is None:
             raise InvalidGitRepositoryError(epath)
 
+        checkout = None
+        if native is NotImplemented and candidate == dotgit and osp.isfile(candidate):
+            # Let Git select the checkout through the supplied .git file. Its
+            # administrative directory alone need not identify the worktree.
+            checkout_probe = self.GitCommandWrapperType(curpath)
+            checkout_probe._environment.update(GIT_DIR=None, **environment)
+            checkout = checkout_probe._call_process_safe("rev_parse", "--show-toplevel")
+
         self.git_dir = git_dir
         probe.update_environment(GIT_DIR=git_dir)
         try:
@@ -387,7 +395,7 @@ def __init__(
             # Gix's configured bare flag also applies to linked worktrees.
             self._bare = native.is_bare() and self._working_tree_dir is None
         else:
-            self._working_tree_dir = environment.get("GIT_WORK_TREE")
+            self._working_tree_dir = environment.get("GIT_WORK_TREE") or checkout
             if self._working_tree_dir is None and not self._bare and environment.get("GIT_COMMON_DIR") is None:
                 try:
                     probe._call_process_safe("config", "--get", "core.worktree")

test/test_downstream_compatibility.py

@@ -36,7 +36,8 @@ def test_index_entries_readers_retain_pending_and_published_snapshots(object_for
 @pytest.mark.parametrize("object_format", ["sha1", "sha256"])
 @pytest.mark.parametrize("ref_format", ["files", "reftable"])
 def test_git_directory_option_selects_the_requested_worktree(object_format, ref_format):
-    with fixture_repo("downstream-worktree.sh", object_format, ref_format, write=True) as repo:
+    # Linked-worktree registration contains absolute paths that cannot be copied.
+    with fixture_repo("downstream-worktree.sh", object_format, ref_format, write=True, execute=True) as repo:
         root = Path(repo.working_tree_dir).parent
         linked = root / "linked"
         original_index = Path(repo.index.path).read_bytes()
@@ -55,11 +56,24 @@ def test_git_directory_option_selects_the_requested_worktree(object_format, ref_
 
 
 def test_git_directory_option_retains_explicit_environment():
-    with fixture_repo("downstream-worktree.sh", "sha1", "files", write=True) as repo:
+    # Linked-worktree registration contains absolute paths that cannot be copied.
+    with fixture_repo("downstream-worktree.sh", "sha1", "files", write=True, execute=True) as repo:
         root = Path(repo.working_tree_dir).parent
         other = root / "other"
         with repo.git.custom_environment(GIT_DIR=repo.git_dir, GIT_WORK_TREE=repo.working_tree_dir):
             assert repo.git(C=str(other)).show("HEAD:tracked") == "original"
         assert repo.git(C=str(other)).show("HEAD:tracked") == "other"
         assert repo.git(C=str(other)).show("HEAD:tracked", env={"GIT_DIR": repo.git_dir}) == "original"
 
+
+@pytest.mark.parametrize("object_format", ["sha1", "sha256"])
+@pytest.mark.parametrize("ref_format", ["files", "reftable"])
+def test_separate_git_directory_retains_the_supplied_checkout(object_format, ref_format):
+    with fixture_repo("downstream-separate-git-dir.sh", object_format, ref_format, write=True) as repo:
+        assert Path(repo.working_tree_dir).name == "repo"
+        assert Path(repo.git_dir).name == "metadata"
+        assert repo.git.rev_parse("--show-toplevel") == repo.working_tree_dir
+        assert repo.index.entry("tracked").to_blob(repo).data_stream.read() == b"tracked"
+        Path(repo.working_tree_dir, "tracked").write_text("updated")
+        repo.index.add(["tracked"])
+        assert repo.index.commit("updated").tree["tracked"].data_stream.read() == b"updated"

tests/fixtures/downstream-separate-git-dir.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -eu
+git init -q --object-format="$1" --ref-format="$2" --separate-git-dir=metadata repo
+# Keep the fixture relocatable when copied into a writable test directory.
+printf 'gitdir: ../metadata\n' > repo/.git
+cd repo
+printf tracked > tracked
+git add tracked
+git commit -qm initial