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.

Validation on macOS with 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.

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/