@@ -6,6 +6,8 @@ __pycache__/
 .cache/
 .mypy_cache/
 .pytest_cache/
+tests/fixtures/generated-do-not-edit/
+tests/fixtures/generated-archives/*.tar
 
 # Transient editor files
 *.swp
 
@@ -0,0 +1,72 @@
+# Backend benchmark
+
+`bench_repository.py` uses `pyperf` to measure a complete read-only journey and
+eight named operations against an existing repository, plus separate direct
+opening and nested-directory discovery measurements. It keeps one `Repo`
+instance open per worker, but creates fresh commit/tree/index wrappers per
+invocation so their cached properties cannot turn the measurement into a no-op.
+The CLI's persistent `cat-file` processes and the filesystem cache are warmed.
+Repository creation, imports, preflight and result hashing are outside timing.
+Native repository reopening and compatibility checks remain inside timing.
+This exposes any future benefit of retaining a native Gix repository handle.
+`open_repository` and `discover_repository` instead create and close a new
+`Repo` in each timed invocation; they do not join the already-open journey.
+
+Use two installations with **the same existing CPython 3.11+ interpreter**.
+Both install GixPython for fixture tooling; `GIT_PYTHON_BACKEND` selects the
+backend in the manager and its workers. Install the benchmark dependencies in
+both environments:
+
+```sh
+uv pip install --python .tox/gix/bin/python -r test/performance/benchmark-requirements.txt
+uv pip install --python .venv/bin/python -r test/performance/benchmark-requirements.txt
+```
+
+Prepare the same fixed repository used by CI (GitPython 3.1.45) through
+`gix.testtools`, outside the measured operations. Its Bash script lives in
+`tests/fixtures/benchmark.sh`; no remote access is needed if that revision
+already exists locally:
+
+```sh
+BENCH_REPO=$(.venv/bin/python -c 'from pathlib import Path; from gix import testtools; print((testtools.scripted_fixture_read_only_with_args("benchmark.sh", [str(Path.cwd())]) / "repo").resolve())')
+```
+
+Run from the source root, sequentially to avoid competing for CPU and disk:
+
+```sh
+GIT_PYTHON_BACKEND=gix .tox/gix/bin/python -m test.performance.bench_repository \
+    --repo "$BENCH_REPO" --expect-backend gix -o /tmp/gix.json
+GIT_PYTHON_BACKEND=cli .venv/bin/python -m test.performance.bench_repository \
+    --repo "$BENCH_REPO" --expect-backend cli -o /tmp/cli.json
+.tox/gix/bin/python -m test.performance.compare_backends /tmp/cli.json /tmp/gix.json
+.tox/gix/bin/python -m pyperf compare_to /tmp/cli.json /tmp/gix.json --table --table-format md
+```
+
+The default uses six worker processes, three measured values per process and
+one warmup, with calibrated loop counts and a minimum value duration of 100 ms.
+Pass standard `pyperf` options such as `--rigorous` for more samples or
+`--debug-single-value` for a smoke check. Raw JSON retains sample distributions,
+environment details, fixture/source revisions, result digests, and one untimed
+invocation's native/fallback decisions. The comparison rejects differing
+results, revisions, Python/Git versions and storage formats. The harness also
+rejects the wrong backend rather than silently comparing CLI against itself.
+
+The journey inventories refs, reads metadata for 25 first-parent commits,
+browses the root tree and README blob, reads index entries, counts reachable
+commits and checks ancestry, inspects the latest diff/statistics and patch, and
+checks dirty/untracked/ignored paths. An alternative `--repo` must have `HEAD`,
+at least one parent, a root `README.md` and a `git/objects` directory for the
+nested discovery measurement. The harness never prepares or
+mutates that worktree, and ignores ambient Git environment/config overrides.
+
+Add a function returning JSON-compatible results to `MEASUREMENTS` in
+`bench_repository.py`. It automatically becomes a separate benchmark and part
+of the journey and parity checks. Include supported and fallback operations;
+the current patch measurement intentionally exercises fallback. Backend
+decisions are adapter events, not complete subprocess counts.
+
+Timing is observational: shared CI runners and local activity introduce noise.
+The CI job publishes all means, standard deviations and ratios, retains raw
+artifacts, and uses `pyperf compare_to` for significance reporting. It fails on
+execution/parity errors, without a noisy speed threshold. Compare like-for-like
+fixture and source revisions when tracking performance across backend changes.
@@ -0,0 +1,175 @@
+"""Read-only GitPython journeys, measured with pyperf against an existing checkout.
+
+Run as a module from the source root so pyperf workers import this checkout:
+    python -m test.performance.bench_repository --repo /path/to/repo --expect-backend gix -o gix.json
+"""
+
+from hashlib import sha256
+from importlib.metadata import version
+import json
+import os
+from pathlib import Path
+import subprocess
+
+import pyperf
+
+from git import Repo, _backend
+
+
+def inventory(repo):
+    return {
+        "head": repo.head.commit.hexsha if repo.head.is_detached else repo.head.reference.path,
+        "refs": sorted(ref.path for ref in repo.references),
+    }
+
+
+def history(repo):
+    return [
+        [commit.hexsha, str(commit.author), commit.authored_date, commit.message]
+        for commit in repo.iter_commits("HEAD", max_count=25, first_parent=True)
+    ]
+
+
+def browse(repo):
+    tree = repo.commit("HEAD").tree
+    blob = tree / "README.md"
+    content = blob.data_stream.read()
+    return {
+        "entries": [[entry.path, entry.mode, entry.hexsha] for entry in tree],
+        "readme": sha256(content).hexdigest(),
+    }
+
+
+def index(repo):
+    return sorted([path, stage, entry.mode, entry.hexsha] for (path, stage), entry in repo.index.entries.items())
+
+
+def graph(repo):
+    tip, parent = repo.commit("HEAD"), repo.commit("HEAD~1")
+    return {
+        "count": tip.count(),
+        "merge_base": [commit.hexsha for commit in repo.merge_base(parent, tip)],
+        "is_ancestor": repo.is_ancestor(parent, tip),
+    }
+
+
+def changes(repo):
+    tip = repo.commit("HEAD")
+    return {
+        "diff": [[diff.change_type, diff.a_path, diff.b_path] for diff in tip.parents[0].diff(tip)],
+        "stats": tip.stats.total,
+    }
+
+
+def patch(repo):
+    tip = repo.commit("HEAD")
+    return [sha256(diff.diff).hexdigest() for diff in tip.parents[0].diff(tip, create_patch=True)]
+
+
+def worktree(repo):
+    return {
+        "dirty": repo.is_dirty(untracked_files=True),
+        "untracked": sorted(repo.untracked_files),
+        "ignored": repo.ignored(".benchmark-cache/probe"),
+    }
+
+
+# Add a named public-API operation here: it is measured separately and joins the
+# complete journey automatically. Return JSON-compatible data for parity checks.
+MEASUREMENTS = {
+    "inventory": inventory,
+    "history_25": history,
+    "browse_tree_and_blob": browse,
+    "read_index": index,
+    "revision_graph": graph,
+    "diff_and_stats": changes,
+    "patch_diff": patch,
+    "worktree_status": worktree,
+}
+
+
+def journey(repo):
+    return {name: operation(repo) for name, operation in MEASUREMENTS.items()}
+
+
+def open_repository(path):
+    with Repo(path) as opened:
+        return [opened.bare, opened.object_format, opened.ref_format]
+
+
+def discover_repository(path):
+    with Repo(path, search_parent_directories=True) as opened:
+        return [opened.bare, opened.object_format, opened.ref_format]
+
+
+def worker_arguments(cmd, args):
+    cmd.extend(["--repo", str(args.repo), "--expect-backend", args.expect_backend])
+
+
+def main():
+    runner = pyperf.Runner(
+        processes=6,
+        values=3,
+        program_args=("-m", "test.performance.bench_repository"),
+        add_cmdline_args=worker_arguments,
+    )
+    runner.argparser.add_argument("--repo", type=Path, required=True, help="Existing worktree; never modified")
+    runner.argparser.add_argument("--expect-backend", choices=("cli", "gix"), required=True)
+    args = runner.parse_args()
+    args.repo = args.repo.resolve()
+    if _backend.name != args.expect_backend:
+        raise RuntimeError(f"Expected {args.expect_backend}, imported {_backend.name}; set GIT_PYTHON_BACKEND")
+    # The manager and every worker use the same isolated Git environment.
+    for key in list(os.environ):
+        if key.startswith("GIT_"):
+            del os.environ[key]
+    os.environ.update(
+        GIT_CONFIG_NOSYSTEM="1",
+        GIT_CONFIG_GLOBAL=os.devnull,
+        GIT_OPTIONAL_LOCKS="0",
+        GIT_PYTHON_BACKEND=args.expect_backend,
+    )
+    args.inherit_environ = [*(args.inherit_environ or []), "GIT_PYTHON_BACKEND"]
+
+    def git(*arguments, cwd=args.repo):
+        return subprocess.check_output(["git", *arguments], cwd=cwd, text=True).strip()
+
+    runner.metadata.update(
+        backend=_backend.name,
+        gixpython=version("GixPython"),
+        git_version=git("version"),
+        gitpython_revision=git("rev-parse", "HEAD", cwd=Path.cwd()),
+        fixture_revision=git("rev-parse", "HEAD"),
+        fixture_tree=git("rev-parse", "HEAD^{tree}"),
+        fixture_status=git("status", "--porcelain") or "clean",
+        fixture_object_format=git("rev-parse", "--show-object-format"),
+        fixture_ref_format=git("rev-parse", "--show-ref-format"),
+    )
+    with Repo(args.repo) as repo:
+        measurements = [("journey", journey, repo)]
+        measurements.extend((name, operation, repo) for name, operation in MEASUREMENTS.items())
+        measurements.extend(
+            [
+                ("open_repository", open_repository, args.repo),
+                ("discover_repository", discover_repository, args.repo / "git" / "objects"),
+            ]
+        )
+        for name, operation, target in measurements:
+            # Untimed preflight validates parity and records native/fallback
+            # decisions for ONE invocation, rather than calibrated loop counts.
+            before = _backend.statistics()
+            result = operation(target)
+            decisions = [
+                {"method": method, "outcome": outcome, "count": count - before.get((method, outcome), 0)}
+                for (method, outcome), count in sorted(_backend.statistics().items())
+                if count > before.get((method, outcome), 0)
+            ]
+            metadata = {
+                "result_digest": sha256(json.dumps(result, sort_keys=True).encode()).hexdigest(),
+                "backend_decisions": json.dumps(decisions, sort_keys=True),
+            }
+            runner.bench_func(name, operation, target, metadata=metadata)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,2 @@
+pyperf==2.10.0
+-r ../../gix-requirements.txt
@@ -0,0 +1,49 @@
+"""Validate benchmark parity and print every measurement, including slowdowns."""
+
+import json
+import sys
+
+import pyperf
+
+
+def compare(cli_path, gix_path):
+    cli, gix = pyperf.BenchmarkSuite.load(str(cli_path)), pyperf.BenchmarkSuite.load(str(gix_path))
+    if cli.get_benchmark_names() != gix.get_benchmark_names():
+        raise ValueError("The backends measured different journeys")
+    rows = []
+    for name in cli.get_benchmark_names():
+        left, right = cli.get_benchmark(name), gix.get_benchmark(name)
+        lm, rm = left.get_metadata(), right.get_metadata()
+        if (lm["backend"], rm["backend"]) != ("cli", "gix"):
+            raise ValueError("Expected CLI results followed by GixPython results")
+        for key in (
+            "gitpython_revision",
+            "fixture_revision",
+            "fixture_tree",
+            "fixture_status",
+            "fixture_object_format",
+            "fixture_ref_format",
+            "git_version",
+            "python_version",
+            "result_digest",
+        ):
+            if lm[key] != rm[key]:
+                raise ValueError(f"{name}: backends differ in {key}: {lm[key]!r} != {rm[key]!r}")
+        decisions = json.loads(rm["backend_decisions"])
+        native = sum(item["count"] for item in decisions if item["outcome"] == "native")
+        fallback = sum(item["count"] for item in decisions if item["outcome"].startswith("CLI:"))
+        rows.append(
+            f"| {name} | {left.mean() * 1000:.2f} ± {left.stdev() * 1000:.2f} "
+            f"| {right.mean() * 1000:.2f} ± {right.stdev() * 1000:.2f} "
+            f"| {left.mean() / right.mean():.2f}× | {native} / {fallback} |"
+        )
+    print("| Measurement | CLI mean ± stdev (ms) | GixPython mean ± stdev (ms) | CLI / Gix | Native / fallback |")
+    print("| --- | ---: | ---: | ---: | ---: |")
+    print("\n".join(rows))
+    print("\nRatios above 1 favor GixPython. Decisions are per invocation, not subprocess counts.")
+    print("\nWarm-cache, read-only measurements; checkout, imports and preflight are outside timing.")
+    print("The journey reuses one open Repo; opening and nested discovery are measured separately.")
+
+
+if __name__ == "__main__":
+    compare(*sys.argv[1:])
@@ -0,0 +1,37 @@
+"""The benchmark comparison must reject incompatible workloads and results."""
+
+import pytest
+
+pyperf = pytest.importorskip("pyperf")
+
+
+@pytest.mark.parametrize("changed", [None, "result_digest", "fixture_revision", "backend"])
+def test_comparison_requires_parity(tmp_path, capsys, changed):
+    from test.performance.compare_backends import compare
+
+    metadata = {
+        "gitpython_revision": "source",
+        "fixture_revision": "fixture",
+        "fixture_tree": "tree",
+        "fixture_status": "clean",
+        "fixture_object_format": "sha1",
+        "fixture_ref_format": "files",
+        "git_version": "git version 2.52.0",
+        "python_version": "3.12.14",
+        "result_digest": "equal",
+        "backend_decisions": "[]",
+        "name": "journey",
+    }
+    paths = [tmp_path / "cli.json", tmp_path / "gix.json"]
+    for backend, path in zip(("cli", "gix"), paths):
+        values = {**metadata, "backend": backend}
+        if backend == "gix" and changed:
+            values[changed] = "different"
+        run = pyperf.Run([0.1, 0.2], metadata=values, collect_metadata=False)
+        pyperf.BenchmarkSuite([pyperf.Benchmark([run])]).dump(str(path))
+    if changed:
+        with pytest.raises(ValueError, match="differ|Expected"):
+            compare(*paths)
+    else:
+        compare(*paths)
+        assert "journey | 150.00" in capsys.readouterr().out
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eu
+
+git init --object-format=sha1 --ref-format=files repo
+git -C repo fetch --no-tags "$1" 6ba2c0a2f9ee7feffd7e079621c4845820180c9a
+git -C repo checkout -b benchmark FETCH_HEAD
+git -C repo config core.excludesFile /dev/null
+git -C repo config core.attributesFile /dev/null
+git -C repo config core.fsmonitor false
+git -C repo config core.untrackedCache false
+git -C repo config gc.auto 0
+git -C repo config maintenance.auto false
+mkdir repo/.benchmark-cache
+touch repo/.benchmark-cache/probe repo/benchmark-untracked.txt
+echo '.benchmark-cache/' >> repo/.git/info/exclude
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+pyperf==2.10.0`
	`2`	`+-r ../../gix-requirements.txt`