@@ -453,9 +453,9 @@ environment metadata.
453453operations and their complete journey on one already-open ` git.Repo ` , plus
454454separate direct opening and discovery from ` git/objects ` . Fresh high-level
455455wrappers preserve the cost of actual operations; imports, fixture preparation
456- and parity preflight are outside timing. Native repository refresh remains
457- inside operation timing, so these measurements include the cost of keeping
458- retained state current .
456+ and parity preflight are outside timing. Native repository opening remains inside
457+ operation timing. Historical retained-handle results below included refresh
458+ costs instead .
459459
460460Submodule inventory, revision path/mode lookup and raw commit/tree readback
461461extend the already-open journey, each with a zero-CLI ceiling. The readback
@@ -632,8 +632,8 @@ used Gix; CLI validation used the affected selections. Repository-wide Ruff
632632lint/format, mypy and basedpyright passed. The benchmark comparison independently
633633checked result parity, fixture/source identity and all process ceilings.
634634Generic configuration and standalone reference-name gaps remain documented
635- under GIX-12/20. ` Repo._get_gix_repository(recreate=True) ` still explicitly
636- recreates retained native state; its snapshot limitations are documented below.
635+ under GIX-12/20. That snapshot retained native repository state; the current
636+ accessor opens a fresh handle for each operation, as documented below.
637637
638638Raw benchmarks, comparison tables and logs from that snapshot are under
639639` .cache/gix-only-audit/benchmark-* ` and ` .cache/gix-only-audit/pyperf-comparison.md ` .
@@ -785,39 +785,34 @@ expected failure. Operation reporting counted 114,800 native operations and
78578539,002 CLI fallback decisions. Those decisions are not a complete subprocess
786786count: raw ` repo.git ` calls and subprocesses started by Git are not all counted.
787787
788- ### Retain native repository state (implemented)
789-
790- Each ` git.Repo ` owns a native ` gix.Repository ` . Managed operations access it through
791- ` Repo._get_gix_repository() ` , which reuses the instance by default.
792- ` Repo._get_gix_repository(recreate=True) ` replaces it explicitly; this method is
793- the control point for a future configurable reuse policy. Managed operations reuse it;
794- ` close() ` releases it, and a later operation can reopen it. Pickling excludes
795- native resources and restores the command's weak owner reference. Gix provides
796- thread-safe handle access and automatic index/ODB snapshot refresh. A per-Repo
797- lock serializes handle refresh, without serializing read operations.
798-
799- Retaining native state is an intentional deviation from Git's fresh process per
800- command. Configuration/environment and observed CLI changes trigger best-effort
801- refresh, but this is not a promise that every external filesystem change is
802- immediately visible in every native cache. Explicit recreation or closing and
803- reopening the ` Repo ` provides fresh native state. Configuration queries currently
804- use a separate fresh handle because the retained execution handle overrides
805- hooks, fsmonitor and automatic maintenance; those overrides must not leak into
806- configuration results. The accessor itself removes no CLI calls: ten supported
807- metadata queries launch zero processes before and after this refactor.
808-
809- Configuration and storage metadata changes, environment changes and raw CLI
810- launches cause ` reload() ` before reuse. Configuration queries use a separate
811- fresh handle so synthetic safety settings never appear as user settings.
812- Configurations with includes conservatively reload on each operation because
813- the binding does not expose all included source paths. Storage overrides,
814- reftable and compatibility object formats retain their existing CLI guards.
788+ ### Open fresh native repository state
789+
790+ Managed operations access Gix through ` Repo._get_gix_repository() ` , which opens
791+ a fresh ` gix.Repository ` for each call. Standalone commands use the same opening
792+ path. No native handle, environment/file fingerprint or refresh lock is cached
793+ on ` Repo ` ; configuration, includes and storage metadata are read by Gix again
794+ on each open. Concurrent operations therefore receive independent handles.
795+
796+ Execution handles override hooks, fsmonitor and automatic maintenance.
797+ Configuration queries omit those overrides so synthetic settings do not appear
798+ as user settings. Storage overrides, reftable and compatibility object formats
799+ retain their existing CLI guards. Reopening itself adds no Git CLI calls.
800+
801+ ` Repo.close() ` releases persistent CLI object readers. Native handles remain
802+ local to operations; callers holding separately opened handles or iterators
803+ must release them before deleting their repository, especially on Windows.
804+ Pickling restores the command's weak owner reference without native resources.
805+
806+ This replaces the retained-handle policy and its best-effort invalidation via
807+ file metadata, environment changes and CLI launches. Reopening repeats native
808+ initialization work but avoids fingerprint construction and unconditional
809+ reloads for configurations with includes.
815810
816811An earlier 1,000-call benchmark without coverage measured an object read using
817- one native handle at 0.046 ms per call, compared with 0.635 ms through the
818- fresh-open stream adapter. Opening and validating a native repository alone
819- took 0.418 ms per call. These small repeated-read measurements do not estimate
820- whole-suite speedup.
812+ one retained native handle at 0.046 ms per call, compared with 0.635 ms through
813+ the fresh-open stream adapter. Opening and validating a native repository alone
814+ took 0.418 ms per call. Those historical measurements do not describe the current
815+ accessor or estimate whole-suite speedup; rerun the backend harness to measure it .
821816
822817### Reuse prepared test fixtures (implemented)
823818
@@ -1230,8 +1225,7 @@ can use Git to preserve its public diagnostics. Once `_write()` begins,
12301225` gix.Error ` failures become ` GitCommandError ` ; other exceptions propagate.
12311226Neither may trigger a second CLI mutation.
12321227Access native repository state through ` Repo._get_gix_repository() ` for bound
1233- commands. Reuse is the default, with explicit recreation available; keep the
1234- snapshot deviation and refresh behavior above documented. Close native iterators
1228+ commands. Each access opens a fresh handle through Gix. Close native iterators
12351229when partially consumed.
12361230
12371231Add each conversion with a no-subprocess check and a Git parity check where
0 commit comments