refactor(gix): centralize retained repository access on Repo

Native operations already retain a `gix.Repository`, but the choice to reuse
or recreate it was hidden inside backend dispatch. Route bound access through
`Repo._get_gix_repository()` and provide `recreate=True` as the control point
for a future configurable policy. Preserve individual command options and the
existing refresh, locking, pickling and resource-release behavior.

Document retained native caches as an intentional deviation from a fresh Git
process per command. Configuration queries still use a separate fresh handle
so the execution handle's safety overrides do not affect queried values.

CLI-call reduction: 0. The fixed probe of ten native metadata queries starts
0 CLI processes before and after this ownership refactor. Explicit recreation
also starts none; later commits can use this accessor for their conversions.

Validation: Gix first, 304 tests and 14 subtests passed (3 skipped), then CLI,
264 tests and 14 subtests passed (4 skipped). Four targeted Gix cases also
passed after checking preservation of a separate bound command's options.
Ruff lint/format, mypy and basedpyright passed.

Author: codex

doc/gix-backend.md

@@ -284,12 +284,25 @@ count: raw `repo.git` calls and subprocesses started by Git are not all counted.
 
 ### Retain native repository state (implemented)
 
-Each `git.Repo` owns a native `gix.Repository`. Managed operations reuse it;
+Each `git.Repo` owns a native `gix.Repository`. Managed operations access it through
+`Repo._get_gix_repository()`, which reuses the instance by default.
+`Repo._get_gix_repository(recreate=True)` replaces it explicitly; this method is
+the control point for a future configurable reuse policy. Managed operations reuse it;
 `close()` releases it, and a later operation can reopen it. Pickling excludes
 native resources and restores the command's weak owner reference. Gix provides
 thread-safe handle access and automatic index/ODB snapshot refresh. A per-Repo
 lock serializes handle refresh, without serializing read operations.
 
+Retaining native state is an intentional deviation from Git's fresh process per
+command. Configuration/environment and observed CLI changes trigger best-effort
+refresh, but this is not a promise that every external filesystem change is
+immediately visible in every native cache. Explicit recreation or closing and
+reopening the `Repo` provides fresh native state. Configuration queries currently
+use a separate fresh handle because the retained execution handle overrides
+hooks, fsmonitor and automatic maintenance; those overrides must not leak into
+configuration results. The accessor itself removes no CLI calls: ten supported
+metadata queries launch zero processes before and after this refactor.
+
 Configuration and storage metadata changes, environment changes and raw CLI
 launches cause `reload()` before reuse. Configuration queries use a separate
 fresh handle so synthetic safety settings never appear as user settings.
@@ -458,8 +471,10 @@ unclear capabilities here and retain the CLI path until Gix provides them.
 Decide whether to fall back before mutating anything. Read/preparation failures
 can use Git to preserve its public diagnostics. Once `_write()` begins, native
 errors become `GitCommandError` and must never trigger a second CLI mutation.
-Open a fresh native repository for each operation so CLI fallback cannot leave
-a cached native view stale. Close native iterators when partially consumed.
+Access native repository state through `Repo._get_gix_repository()` for bound
+commands. Reuse is the default, with explicit recreation available; keep the
+snapshot deviation and refresh behavior above documented. Close native iterators
+when partially consumed.
 
 Add each conversion with a no-subprocess check and a Git parity check where
 practical, in its own commit. Update this ledger when a limitation changes;

git/_backend.py

@@ -102,8 +102,7 @@ def discover_repository(path: str, environment: Dict[str, Any]) -> Any:
 def _repository(command: Any, env: Dict[str, Any], *, query_config: bool = False) -> Any:
     owner = command._repo() if command._repo is not None else None
     if owner is not None:
-        with owner._gix_lock:
-            return _open_repository(command, env, query_config=query_config)
+        return owner._get_gix_repository(command=command, env=env, query_config=query_config)
     return _open_repository(command, env, query_config=query_config)
 
 

git/repo/base.py

@@ -475,6 +475,28 @@ def __init__(
                 )
             self.odb = odbt(rootpath)
 
+    def _get_gix_repository(
+        self,
+        *,
+        command: Optional[Git] = None,
+        env: Optional[Dict[str, Any]] = None,
+        query_config: bool = False,
+        recreate: bool = False,
+    ) -> Any:
+        """Access native state, reusing the repository unless recreation is requested.
+
+        This method owns the reuse policy so it can later become configurable.
+        Configuration queries currently open a separate handle without the execution
+        restrictions applied to the retained handle. Other operations retain the
+        existing best-effort refresh of configuration, environment and CLI changes.
+        """
+        with self._gix_lock:
+            if recreate:
+                self._gix_repository = self._gix_state = None
+            return _backend._open_repository(
+                command if command is not None else self.git, env or {}, query_config=query_config
+            )
+
     def __getstate__(self) -> Dict[str, Any]:
         return {
             key: value

test/test_gix_backend.py

@@ -59,7 +59,7 @@ def test_native_worktree_inventory_includes_bare_main(repo, tmp_path):
 
 
 def test_native_repository_lifetime_and_refresh(repo, tmp_path):
-    handle = repo._gix_repository
+    handle = repo._get_gix_repository()
     assert isinstance(handle, gix.Repository)
     with patch.object(gix, "open_opts", side_effect=AssertionError("unexpected reopen")):
         assert repo.git._call_process_safe("rev_parse", "--show-object-format") == repo.object_format
@@ -91,6 +91,14 @@ def test_native_repository_lifetime_and_refresh(repo, tmp_path):
     include.write_text("[test]\nvalue = second\n")
     assert _backend._repository(repo.git, {}).config_snapshot().string("test.value") == b"second"
 
+    count = _backend.statistics().get(("Git.execute", "CLI process"), 0)
+    with patch.object(gix, "open_opts", wraps=gix.open_opts) as opened:
+        replacement = repo._get_gix_repository(recreate=True)
+        assert replacement is not handle
+        assert repo._get_gix_repository() is replacement
+        opened.assert_called_once()
+    assert _backend.statistics().get(("Git.execute", "CLI process"), 0) == count
+
     with pickle.loads(pickle.dumps(repo)) as restored:
         assert restored._gix_repository is None
         assert restored.commit().hexsha == repo.commit().hexsha
@@ -212,6 +220,13 @@ def test_unknown_command_and_storage_environment_use_cli(repo):
         assert repo.git._call_process_safe("rev_parse", "--show-ref-format") == "fallback"
         assert cli.call_count == 3
 
+    command = Git(repo.working_dir)
+    command._repo = repo.git._repo
+    command._environment.update(repo.git.environment())
+    command._persistent_git_options = ["--no-replace-objects"]
+    with pytest.raises(_backend._Unsupported, match="global command options"):
+        _backend._repository(command, {})
+
 
 def test_compatibility_object_format_uses_cli_before_writing(repo):
     repo.git.config("core.repositoryFormatVersion", "1")