feat!: delegate repository storage to Git and Gix

GitPython's Python implementations of repository discovery, configuration,
references, object storage and indexes assume storage details that do not hold
for SHA-256 objects or reftable references. Delegate these operations to Git
2.52+ and offer GixPython 0.2.0 for supported operations, using the Git CLI as
the behavioral baseline.

Keep library-managed commands behind argument and stdin validation, suppress
implicit hooks, external diff programs, maintenance and lazy fetches where
appropriate, and preserve explicit unsafe-operation opt-ins. Support SHA-1 and
SHA-256 with files or reftable reference storage. Close owned repository handles
before filesystem cleanup and account for Windows and Cygwin path restrictions.

The optional `gix` extra selects Gitoxide through supported GixPython APIs.
`GIT_PYTHON_BACKEND=cli|gix` makes selection explicit even when both backends are
installed. Retain native repository handles and adapt native object, reference,
index, graph, configuration, diff and status results where they match Git.
Keep CLI fallbacks for missing capabilities and incompatible behavior; record
reproductions, affected adapters and upstream requirements in the compatibility
ledger in `doc/gix-backend.md`. Native execution never means reimplementing Git
semantics in Python.

Read declared commit encodings according to Git's first-header and whole-commit
conversion behavior, including conversion failure and signature headers. Keep
UTF-8 metadata native; use Git's text projection for other encodings and the
open Gix header-order compatibility bug. Validate these cases with read-only
Bash fixtures and direct Git comparisons. Configuration failure regressions
exercise Git's per-mutation locks rather than the removed constructor lock.

Breaking API changes follow the storage migration. Remove the Python `GitDB`
backend and binary index/tree and raw reflog mutation interfaces. Replace
`IndexFile.entries` with immutable `iter_entries()`/`entry()` queries and explicit
edits; publish deferred index bytes only after Git validates them. Configuration
uses Git's syntax and locking, reflogs expose Git's commit-reflog view, and
repository object IDs have format-dependent widths. Remove deprecated exports
and implicit environment-variable path expansion. Document the affected APIs,
exceptions, hook behavior and replacements in `doc/source/changes.rst`.

Move generated repository and filesystem initial states into Bash scripts run
through `gix.testtools`. Read-only tests share prepared fixtures; mutation tests
copy them by default, with explicit execution only for fixtures that cannot be
relocated. Keep generated caches and archives out of version control. Tests
require GixPython with either backend: CI runs fixture suites on Python 3.11+
and retains installation/import smoke checks on Python 3.8-3.10. Update the
normal, minimum-Git, Alpine and Cygwin environments and the source packaging.

Add downstream release checks for Bandit, MLflow, LangChain, SWE-bench and
DataHub with both backends. Add a read-only repository benchmark that compares
result digests, records native/fallback decisions and actual Git launches, and
enforces CLI-process ceilings. Preserve historical measurements and their
original revision references as evidence, including superseded results.

Make scripted tests portable to Git for Windows. Define literal submodule
names inside Bash from simple scenario identifiers, because MSYS expands
metacharacters in native arguments and disabling that expansion breaks
GixPython's quoted script launcher. Retain Windows directory-symlink types
for dangling targets and build trailing-space filenames with Git's `mktree`
instead of the Windows-restricted index. Compare escaped log paths and
native fixture locations correctly. Keep exact Git-recorded submodule URLs
while separately checking path identity, including a portable `/./` regression.
Use Git's actual text projection for platform-dependent `iconv` declarations.

Alpine's musl recognizes `utf-16-be` while macOS rejects that spelling.
Keep Git as the text baseline; independently assert the first codec, raw
dates/timezones, and native/fallback decisions. Keep malformed UTF-16 fixtures
odd-sized, including the portable `UTF-16BE` spelling, so conversion fails
without erasing Git's header delimiters. Assert the raw object size to prevent
fixture edits from reintroducing unstable pretty output. Record these
platform limitations in `doc/gix-backend.md`.

Before the Windows fixture repairs, macOS validation used CPython
3.12.14, Git 2.54.0 and GixPython 0.2.0. The full CLI suite passed 1,745 tests with 151 skips, and the full Gix suite
passed 1,845 tests with 51 skips. Both passed 58 subtests and retained one
expected failure. CLI ran first. All 14 benchmark result digests and the
existing CLI-process ceilings matched; the two-sample smoke run establishes
no timing conclusion. Ruff lint/format, mypy, basedpyright, ShellCheck and
Sphinx with warnings fatal passed. Hosted CI, other platforms and older
interpreters were not run locally.

The first Windows fixture repair passed 471 tests and 20 subtests on each
backend locally but exposed a native Windows launcher failure in CI. The
follow-up removes the `MSYS=noglob` override and preserves all literal-name
assertions through scripted initial states. It also fixes Alpine's encoding
expectation rather than changing production Git behavior. The focused
commit, cleanup, fixture-health and literal-name tests passed 70 tests and
21 subtests per backend locally, CLI first, with one Windows-only skip.
Repository pre-commit hooks passed. On `13202ce`, 63 of 64 hosted checks
passed, including Alpine and Windows Gix. Windows CLI on Python 3.12 exposed
one remaining fixture expectation: direct Git returned `x` instead of an
empty message after successful UTF-16 recoding removed every newline. The
failure preceded the backend comparison. Force conversion failure for those
malformed fixtures and remove the unsupported empty-output assertion while
retaining exact Git comparisons. No production behavior changes for this
repair. The final commit module passed 40 tests and 21 subtests per backend
locally, CLI first, and all hooks for the changed files passed. Hosted
verification of that final fixture correction is left to the next CI run.

Co-authored-by: GPT-6 Astra <codex@openai.com>
Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Byron <sebastian.thiel@icloud.com>

Author: codex

.basedpyright/baseline.json

@@ -8,75 +8,9 @@
           "endColumn": 45,
           "lineCount": 1
         }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 41,
-          "endColumn": 48,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 32,
-          "endColumn": 39,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportCallIssue",
-        "range": {
-          "startColumn": 25,
-          "endColumn": 46,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 30,
-          "endColumn": 39,
-          "lineCount": 1
-        }
-      }
-    ],
-    "./git/db.py": [
-      {
-        "code": "reportIncompatibleMethodOverride",
-        "range": {
-          "startColumn": 8,
-          "endColumn": 12,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportIncompatibleMethodOverride",
-        "range": {
-          "startColumn": 8,
-          "endColumn": 14,
-          "lineCount": 1
-        }
       }
     ],
     "./git/index/base.py": [
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 30,
-          "endColumn": 36,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 28,
-          "endColumn": 34,
-          "lineCount": 1
-        }
-      },
       {
         "code": "reportArgumentType",
         "range": {
@@ -186,14 +120,6 @@
           "endColumn": 25,
           "lineCount": 1
         }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 52,
-          "endColumn": 84,
-          "lineCount": 1
-        }
       }
     ],
     "./git/objects/tag.py": [
@@ -274,32 +200,6 @@
         }
       }
     ],
-    "./git/refs/log.py": [
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 30,
-          "endColumn": 34,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 17,
-          "endColumn": 22,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportArgumentType",
-        "range": {
-          "startColumn": 28,
-          "endColumn": 30,
-          "lineCount": 1
-        }
-      }
-    ],
     "./git/refs/reference.py": [
       {
         "code": "reportIncompatibleVariableOverride",
@@ -310,16 +210,6 @@
         }
       }
     ],
-    "./git/refs/symbolic.py": [
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 15,
-          "endColumn": 20,
-          "lineCount": 1
-        }
-      }
-    ],
     "./git/refs/tag.py": [
       {
         "code": "reportIncompatibleMethodOverride",
@@ -338,49 +228,7 @@
         }
       }
     ],
-    "./git/remote.py": [
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      }
-    ],
     "./git/repo/base.py": [
-      {
-        "code": "reportReturnType",
-        "range": {
-          "startColumn": 15,
-          "endColumn": 28,
-          "lineCount": 1
-        }
-      },
       {
         "code": "reportTypedDictNotRequiredAccess",
         "range": {
@@ -445,26 +293,6 @@
           "lineCount": 1
         }
       }
-    ],
-    "./git/repo/fun.py": [
-      {
-        "code": "reportReturnType",
-        "range": {
-          "startColumn": 11,
-          "endColumn": 20,
-          "lineCount": 1
-        }
-      }
-    ],
-    "./test/deprecation/test_basic.py": [
-      {
-        "code": "reportUnusedExpression",
-        "range": {
-          "startColumn": 12,
-          "endColumn": 62,
-          "lineCount": 1
-        }
-      }
     ]
   }
 }

.github/workflows/alpine-test.yml

@@ -12,6 +12,8 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    env:
+      GIT_PYTHON_BACKEND: cli
 
     container:
       image: alpine:latest
@@ -23,8 +25,8 @@ jobs:
     steps:
     - name: Prepare Alpine Linux
       run: |
-        apk add sudo git git-daemon python3 py3-pip py3-virtualenv
-        echo 'Defaults env_keep += "CI GITHUB_* RUNNER_*"' >/etc/sudoers.d/ci_env
+        apk add sudo git git-daemon bash rust cargo build-base python3 python3-dev py3-pip py3-virtualenv
+        echo 'Defaults env_keep += "CI GITHUB_* RUNNER_* GIT_PYTHON_BACKEND"' >/etc/sudoers.d/ci_env
         addgroup -g 127 docker
         adduser -D -u 1001 runner  # TODO: Check if this still works on GHA as intended.
         adduser runner docker
@@ -64,6 +66,7 @@ jobs:
       run: |
         . .venv/bin/activate
         pip install ./smmap ./gitdb '.[test]'
+        python -c 'from gix import testtools'
 
     - name: Show POSIX file ownership
       run: |

.github/workflows/backend-benchmark.yml

@@ -0,0 +1,81 @@
+name: Backend benchmark
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  compare-backends:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Ensure Git 2.52 or newer
+        run: |
+          if ! dpkg --compare-versions "$(git version | awk '{print $3}')" ge 2.52; then
+            sudo add-apt-repository --yes ppa:git-core/ppa
+            sudo apt-get update
+            sudo apt-get install --yes git
+          fi
+      - name: Prepare Rust for GixPython
+        run: |
+          rustup update stable
+          rustup default stable
+          echo "CARGO_TARGET_DIR=$RUNNER_TEMP/gix-target" >> "$GITHUB_ENV"
+      - name: Cache GixPython builds
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            ${{ runner.temp }}/gix-target
+            ~/.cache/pip
+          key: benchmark-gix-${{ runner.os }}-${{ hashFiles('gix-requirements.txt') }}
+      - name: Install separate backends with the same interpreter
+        run: |
+          python -m venv .bench-cli
+          python -m venv .bench-gix
+          .bench-cli/bin/python -m pip install . -r test/performance/benchmark-requirements.txt
+          .bench-gix/bin/python -m pip install '.[gix]' -r test/performance/benchmark-requirements.txt
+      - name: Prepare the shared read-only benchmark fixture
+        run: |
+          .bench-cli/bin/python -c 'from pathlib import Path; from gix import testtools; print("BENCH_REPO=" + str((testtools.scripted_fixture_read_only_with_args("benchmark.sh", [str(Path.cwd())]) / "repo").resolve()))' >> "$GITHUB_ENV"
+          mkdir benchmark-results
+      - name: Measure GixPython operations, opening and discovery first
+        env:
+          GIT_PYTHON_BACKEND: gix
+        run: |
+          .bench-gix/bin/python -m test.performance.bench_repository \
+            --repo "$BENCH_REPO" --expect-backend gix -o benchmark-results/gix.json
+      - name: Measure CLI operations, opening and discovery
+        env:
+          GIT_PYTHON_BACKEND: cli
+        run: |
+          .bench-cli/bin/python -m test.performance.bench_repository \
+            --repo "$BENCH_REPO" --expect-backend cli -o benchmark-results/cli.json
+      - name: Check parity and publish comparison
+        run: |
+          .bench-gix/bin/python -m test.performance.compare_backends \
+            benchmark-results/cli.json benchmark-results/gix.json \
+            --cli-budget test/performance/cli-budget.json > benchmark-results/comparison.md
+          cat benchmark-results/comparison.md >> "$GITHUB_STEP_SUMMARY"
+          .bench-gix/bin/python -m pyperf compare_to \
+            benchmark-results/cli.json benchmark-results/gix.json --table --table-format md \
+            >> "$GITHUB_STEP_SUMMARY"
+      - name: Retain raw timings and comparison
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: backend-benchmark
+          path: benchmark-results/