fix(cmd): honor global -C checkout selection

Mistral Vibe 3.0.1 creates linked worktrees with `--no-checkout` and then
uses `repo.git(C=target).checkout(..., as_process=True)` to populate them.
This branch automatically exports the original `GIT_DIR` and `GIT_WORK_TREE`
on `repo.git`, so Git ignores the requested checkout for repository discovery.
The result leaves the new worktree empty and can overwrite uncommitted files
in the original checkout. Released GitPython 3.2.1 populates the linked
worktree and preserves those original files.

Track automatically supplied repository environment values separately from
caller overrides. Drop only those values when `_call_process` supplies a
global `-C` option; ordinary calls retain their bound repository. Explicit
`update_environment`, temporary `custom_environment` and per-call overrides
continue to take precedence. Keep the override bookkeeping after temporary
contexts so later calls select their checkout correctly. Repository selection
remains Git CLI behavior, including asynchronous and persistent-option calls.

Add scripted regressions for linked checkout population, preservation of dirty
original files and the published index, different-repository selection,
persistent global options and explicit environment precedence. All five new
regressions failed before the fix. The adjacent command, repository and guard
suites passed 383 tests, three skips and 14 subtests on each backend, CLI
first, with Python 3.12.15, Git 2.53.0 and GixPython 0.2.0. Ruff, ShellCheck
and mypy passed; basedpyright reported no errors and one existing unresolved
`typing_extensions` source warning. The downstream rerun confirms 22 related
Mistral Vibe failures are fixed; separate-directory metadata and its
GC-dependent cleanup assertion are being investigated separately.

Author: codex

doc/source/changes.rst

@@ -38,6 +38,9 @@ Git executable and safety
   suppresses configured signing by default; signing, verification, and editor
   options require the same opt-in.
 * The raw ``repo.git`` interface remains available for direct Git commands.
+  Global ``-C`` options select the requested checkout without the repository
+  locations automatically supplied by ``Repo`` overriding it. Explicit
+  environment overrides retain Git's precedence over ``-C``.
   Existing explicit unsafe-option and unsafe-protocol opt-ins remain independent.
   They do not permit argument or stdin-record injection, or reordering command
   options past the library's safety flags.

git/cmd.py

@@ -616,6 +616,7 @@ class Git:
         "_git_options",
         "_persistent_git_options",
         "_environment",
+        "_repository_environment",
         "_repo",
     )
 
@@ -1164,6 +1165,7 @@ def __init__(self, working_dir: Union[None, PathLike] = None) -> None:
 
         # Extra environment variables to pass to git commands
         self._environment: Dict[str, Optional[str]] = {}
+        self._repository_environment: Dict[str, Optional[str]] = {}
         self._repo: Any = None  # Weak reference; the Repo owns native resources.
 
         # Cached version slots
@@ -1535,7 +1537,11 @@ def execute(
         # just to be sure.
         environment["LANGUAGE"] = "C"
         environment["LC_ALL"] = "C"
-        environment.update(self._environment)
+        redirected = subprocess_kwargs.pop("_repository_redirected", False)
+        automatic = self._repository_environment if redirected else {}
+        environment.update(
+            {key: value for key, value in self._environment.items() if key not in automatic or value != automatic[key]}
+        )
         if inline_env is not None:
             environment.update(inline_env)
         # Internal or per-call None overrides remove inherited variables.
@@ -1725,6 +1731,7 @@ def update_environment(self, **kwargs: Any) -> Dict[str, Union[str, None]]:
         """
         old_env = {}
         for key, value in kwargs.items():
+            self._repository_environment.pop(key, None)
             # Set value if it is None.
             if value is not None:
                 old_env[key] = self._environment.get(key)
@@ -1748,11 +1755,13 @@ def custom_environment(self, **kwargs: Any) -> Iterator[None]:
         :param kwargs:
             See :meth:`update_environment`.
         """
+        automatic = {key: self._repository_environment[key] for key in kwargs if key in self._repository_environment}
         old_env = self.update_environment(**kwargs)
         try:
             yield
         finally:
             self.update_environment(**old_env)
+            self._repository_environment.update(automatic)
 
     def transform_kwarg(self, name: str, value: Any, split_single_char_options: bool) -> List[str]:
         if len(name) == 1:
@@ -1907,6 +1916,11 @@ def _call_process(
         call.extend(self._git_options)
         self._git_options = ()
 
+        # Only global options redirect discovery. A subcommand operand named
+        # -C must not drop the repository locations supplied by Repo.
+        if any(option == "-C" for option in call[1:]):
+            exec_kwargs["_repository_redirected"] = True
+
         call.extend(safe_git_options)
 
         call.append(dashify(method))

git/repo/base.py

@@ -446,8 +446,12 @@ def __init__(
         self.git = self.GitCommandWrapperType(self.working_dir)
         self.git._repo = weakref.ref(self)
         self.git._environment.update(GIT_DIR=git_dir, **environment)
+        if git_dir_env is None:
+            self.git._repository_environment["GIT_DIR"] = git_dir
         if self._working_tree_dir is not None:
             self.git.update_environment(GIT_WORK_TREE=os.fspath(self._working_tree_dir))
+            if "GIT_WORK_TREE" not in environment:
+                self.git._repository_environment["GIT_WORK_TREE"] = os.fspath(self._working_tree_dir)
         if native is not NotImplemented:
             self._gix_repository = native
             self._empty_tree_hexsha = str(native.empty_tree().id)

test/test_downstream_compatibility.py

@@ -31,3 +31,35 @@ def test_index_entries_readers_retain_pending_and_published_snapshots(object_for
         index.write()
         assert repo.index.entries == pending
         assert entries[("tracked", 0)].binsha == repo.head.commit.tree["tracked"].binsha
+
+
+@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:
+        root = Path(repo.working_tree_dir).parent
+        linked = root / "linked"
+        original_index = Path(repo.index.path).read_bytes()
+        assert not (linked / "tracked").exists()
+        process = repo.git(C=str(linked)).checkout("--force", as_process=True)
+        process.wait()
+        assert (linked / "tracked").read_text() == "original"
+        assert Path(repo.working_tree_dir, "tracked").read_text() == "unchanged"
+        assert Path(repo.index.path).read_bytes() == original_index
+        assert repo.git(C=str(linked)).rev_parse("--show-toplevel") == str(linked)
+        assert repo.git(C=str(root / "other")).show("HEAD:tracked") == "other"
+        repo.git.set_persistent_git_options(C=str(linked))
+        assert repo.git.rev_parse("--show-toplevel") == str(linked)
+        repo.git.set_persistent_git_options()
+        assert repo.git.rev_parse("--show-toplevel") == repo.working_tree_dir
+
+
+def test_git_directory_option_retains_explicit_environment():
+    with fixture_repo("downstream-worktree.sh", "sha1", "files", write=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"
+

tests/fixtures/downstream-worktree.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -eu
+git init -q --object-format="$1" --ref-format="$2" repo
+cd repo
+printf original > tracked
+git add tracked
+git commit -qm initial
+git worktree add -q --no-checkout -b linked ../linked HEAD
+printf unchanged > tracked
+git init -q ../other
+cd ../other
+printf other > tracked
+git add tracked
+git commit -qm other