perf(cmd): share minimum Git version checks across wrappers

Reuse successful minimum-version checks for equivalent `Git` wrappers, keyed
by the resolved executable and its metadata, working directory, effective
environment and `Git.refresh()` generation. Keep public `version_info` caching
per instance and reject unsupported versions before repository creation.
Executable replacement and newly preferred PATH candidates trigger new probes;
ambiguous Windows search and global options retain the existing behavior.

This is shared CLI housekeeping for both backends: it caches actual Git answers
and records no native success. It does not implement a missing Gix capability.
The cache is bounded to 128 contexts; external launcher state still requires
an explicit `Git.refresh()` when executable/environment metadata is unchanged.

The fixed pair of extra warm version checks drops from two CLI launches to
zero. With the Gix-only fallbacks restored, warm opening/discovery launch counts
fall from 2/4 to 1/3 for Gix and 11/13 to 9/11 for CLI. Update the benchmark
ceilings accordingly while retaining real reference-format and negative-path
queries. Cold contexts can still add a version probe.

Validation: 68 affected version, refresh, guard, counter and ceiling tests passed
with Gix first (1.50s), then CLI (1.74s). All 11 benchmark result digests match
and the adjusted ceilings pass; `git diff --check` passed.

Author: codex

doc/gix-backend.md

@@ -105,7 +105,7 @@ the call phase, so that column can still include their fixture work. Counts
 cover the current Python process; they are not aggregated across xdist workers.
 For a stable CI assertion, the pinned repository benchmark uses per-measurement
 ceilings in `test/performance/cli-budget.json`: the warm Gix journey launches
-one CLI process, opening launches two, and nested discovery launches four.
+one CLI process, opening launches one, and nested discovery launches three.
 Reduce these ceilings as conversions land. The other operation rows have zero
 ceilings except the one-process patch diff.
 
@@ -119,8 +119,9 @@ accounting. The same run recorded 21,409 fallback decisions. These totals
 include explicit CLI tests and fixture commands, including non-Git commands
 passed directly to `Git.execute`; they are a local baseline, not a count of
 only fallback calls. The fixed warm benchmark instead isolates a user journey:
-23 CLI launches versus one Gix launch, opening 11 versus two, and nested
-discovery 13 versus four after restoring the reference-format fallback.
+23 CLI launches versus one Gix launch, opening nine versus one, and nested
+discovery eleven versus three after restoring the reference-format fallback
+and sharing successful version checks.
 The historical full-suite counts above predate this correction. A constant
 `files` answer was not a Gix query; `GIX-1` records the missing binding.
 
@@ -169,6 +170,27 @@ an import error; only an absent top-level `gix` selects CLI mode.
 
 ## Performance work
 
+### Shared minimum-version checks
+
+Both installations reuse successful minimum-Git-version checks across fresh
+`Git` wrappers with the same resolved executable, executable metadata, working
+directory, effective environment and `Git.refresh()` generation. Two extra
+checks in the fixed warm probe now launch zero processes instead of two;
+two equivalent cold wrappers launch one probe. Public `version_info` caching
+remains per instance, and old versions still fail before repository creation.
+
+This is shared CLI housekeeping: it caches an actual Git answer and records
+no native success. It is not a Gix implementation of a missing capability.
+The pinned warm Gix opening/discovery ceilings fall from 2/4 to 1/3 here;
+the reference-format query and rejected-candidate diagnostics remain real CLI
+calls. Cold contexts can still require a version probe.
+
+Global Git options and ambiguous Windows executable search retain per-instance
+probes; explicit absolute executables can share checks on Windows. The shared
+cache is bounded to 128 contexts. Call `Git.refresh()` if a launcher's reported
+version changes through external state without changing its executable or
+environment metadata.
+
 ### Existing-repository benchmark
 
 [`test/performance/README.md`](../test/performance/README.md) describes the

git/cmd.py

@@ -13,6 +13,7 @@
 import logging
 import os
 import re
+import shutil
 import signal
 import subprocess
 import sys
@@ -699,6 +700,9 @@ class Git(metaclass=_GitMeta):
         "_repo",
     )
 
+    _version_info: Optional[Tuple[int, ...]]
+    _version_info_token: object
+
     # Match Git's leading transport selector, including an empty helper name.
     # Git also selects the command-executing ext helper for an ext:// URL.
     re_unsafe_protocol = re.compile(r"([A-Za-z0-9][A-Za-z0-9+.-]*|)::|ext://")
@@ -791,6 +795,7 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
     """
 
     _refresh_token = object()  # Since None would match an initial _version_info_token.
+    _version_check_cache: Dict[Tuple[Any, ...], Tuple[int, ...]] = {}
 
     @classmethod
     def refresh(cls, path: Union[None, PathLike] = None) -> bool:
@@ -1145,8 +1150,61 @@ def _check_operand(value: Any, label: str = "operand") -> str:
         return value
 
     def _require_version(self) -> None:
-        if self.version_info < (2, 52):
+        key = None
+        if self._version_info_token is not self._refresh_token:
+            key = self._version_check_key()
+            if key is not None:
+                version = self._version_check_cache.get(key)
+                if version is not None:
+                    self._version_info = version
+                    self._version_info_token = key[0]
+        version = self.version_info
+        if version < (2, 52):
             raise UnsupportedOperation("GitPython requires Git 2.52 or newer for repository operations")
+        if key is not None and key not in self._version_check_cache:
+            # ponytail: clear at 128 contexts; use LRU if diverse environments churn.
+            if len(self._version_check_cache) >= 128:
+                self._version_check_cache.clear()
+            self._version_check_cache[key] = version
+
+    def _version_check_key(self) -> Optional[Tuple[Any, ...]]:
+        """Identify the executable and context of a minimum-version probe."""
+        executable = self.GIT_PYTHON_GIT_EXECUTABLE
+        if not executable or self._git_options or self._persistent_git_options:
+            return None
+        environment = {**os.environ, "LANGUAGE": "C", "LC_ALL": "C", **self._environment}
+        try:
+            cwd = os.path.realpath(self._working_dir or os.getcwd())
+            if not os.access(cwd, os.X_OK):
+                return None
+            resolved: Optional[str]
+            if os.path.isabs(executable):
+                resolved = executable
+            elif sys.platform == "win32":
+                # CreateProcess searches in the parent context, unlike execvpe.
+                return None
+            elif os.path.dirname(executable):
+                resolved = os.path.join(cwd, executable)
+            else:
+                path = environment.get("PATH")
+                path = os.defpath if path is None else path
+                resolved = shutil.which(
+                    executable, path=os.pathsep.join(os.path.join(cwd, p) for p in path.split(os.pathsep))
+                )
+                if resolved is None:
+                    return None
+            info = os.stat(resolved)
+        except OSError:
+            return None
+        return (
+            self._refresh_token,
+            type(self),
+            executable,
+            resolved,
+            cwd,
+            tuple(sorted(environment.items())),
+            (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns),
+        )
 
     def _call_process_safe(
         self,
@@ -1235,8 +1293,8 @@ def __init__(self, working_dir: Union[None, PathLike] = None) -> None:
         self._repo: Any = None  # Weak reference; the Repo owns native resources.
 
         # Cached version slots
-        self._version_info: Union[Tuple[int, ...], None] = None
-        self._version_info_token: object = None
+        self._version_info = None
+        self._version_info_token = None
 
         # Cached command slots
         self.cat_file_header: Union[None, TBD] = None

test/performance/README.md

@@ -88,15 +88,16 @@ Direct subprocesses in the harness and Git's own child processes are excluded.
 The checked-in `cli-budget.json` sets maximum Gix launch counts for this pinned
 fixture. CI enforces the ceilings: reductions pass, increases fail with the
 measurement and counts. Lower ceilings when an optimization lands to retain
-the gain. Warm ceilings are journey/patch 1, opening 2, discovery 4,
+the gain. Warm ceilings are journey/patch 1, opening 1, discovery 3,
 and zero for the other operations. New measurements need an explicit ceiling;
 do not automatically raise an existing ceiling to accept a regression.
 
 The opening/discovery ceilings include a real CLI reference-format query
-(`GIX-1`) and version validation. Nested candidates rejected by Gix also use
+(`GIX-1`). Nested candidates rejected by Gix also use
 Git for compatible discovery diagnostics (`GIX-14`). GixPython must expose
 the missing capabilities before those calls can disappear; Python inference
 does not count as a native implementation.
+Warm version checks reuse real CLI answers; cold contexts can add a version probe.
 
 Timing is observational: shared CI runners and local activity introduce noise.
 The CI job publishes all means, standard deviations and ratios, retains raw

test/performance/cli-budget.json

@@ -10,7 +10,7 @@
     "diff_and_stats": 0,
     "patch_diff": 1,
     "worktree_status": 0,
-    "open_repository": 2,
-    "discover_repository": 4
+    "open_repository": 1,
+    "discover_repository": 3
   }
 }

test/test_git.py

@@ -24,8 +24,8 @@
 
 import ddt
 
-from git import Git, GitCommandError, GitCommandNotFound, Repo, cmd, refresh
-from git.exc import UnsafeOptionError
+from git import Git, GitCommandError, GitCommandNotFound, Repo, _backend, cmd, refresh
+from git.exc import UnsafeOptionError, UnsupportedOperation
 from git.util import cwd, finalize_process
 
 from test.lib import TestBase, fixture_path, with_rw_directory
@@ -825,6 +825,43 @@ def test_version_info_cache_is_per_instance(self):
                     git2.version_info
                 git1.version_info
 
+    def test_minimum_version_shares_context_and_detects_replacement(self):
+        def calls():
+            return _backend.statistics().get(("Git.execute", "CLI process"), 0)
+
+        with _rollback_refresh(), _fake_git(2, 54, 0) as path:
+            refresh(path)
+            count = calls()
+            Git()._require_version()
+            Git()._require_version()
+            self.assertEqual(calls() - count, 1)
+            custom = Git()
+            custom.update_environment(GITPYTHON_VERSION_CONTEXT="different")
+            for command in (Git(Path(path).parent), custom):
+                count = calls()
+                command._require_version()
+                self.assertEqual(calls() - count, 1)
+            with _fake_git(2, 51, 0) as older:
+                shutil.copy(older, path)
+                with self.assertRaises(UnsupportedOperation):
+                    Git()._require_version()
+
+    def test_minimum_version_detects_new_executable_earlier_in_path(self):
+        with contextlib.ExitStack() as stack:
+            stack.enter_context(_rollback_refresh())
+            older = Path(stack.enter_context(_fake_git(2, 51, 0)))
+            newer = Path(stack.enter_context(_fake_git(2, 54, 0)))
+            stack.enter_context(mock.patch.dict(os.environ, {"PATH": f"{older.parent}{os.pathsep}{newer.parent}"}))
+            stack.enter_context(_patch_out_env("GIT_PYTHON_GIT_EXECUTABLE"))
+            if sys.platform == "win32":
+                stack.enter_context(mock.patch.object(Git, "git_exec_name", "git.cmd"))
+            _rename_with_stem(newer, "git")
+            refresh()
+            Git()._require_version()
+            _rename_with_stem(older, "git")
+            with self.assertRaises(UnsupportedOperation):
+                Git()._require_version()
+
     def test_version_info_cache_is_not_pickled(self):
         with _rollback_refresh():
             with _fake_git(123, 456, 789) as path: