# Benchmarks
Benchmarks are evidence, not a permanent ranking. Storage, antivirus, CPU
power state, pack shape, and Git build affect results.
## Rules
Each harness:
1. executes the same logical operation;
2. materializes the result;
3. proves exact identifier, order, path, or status parity;
4. warms both implementations;
5. reports p50 and p95 from a release build.
`warm` reuses an opened `Repository`. `reopen` repeats discovery and index
loading while retaining normal operating-system caches. `git.exe` includes
process creation because avoiding that cost is the production purpose of this
crate. No comparison with an in-process library is claimed without an
equivalent measured contract.
## Direct in-process competitors
The separate, non-published `tools/competitor-bench` crate pins
[`gix` 0.86.0](https://docs.rs/gix/0.86.0) and
[`git2` 0.21.0](https://docs.rs/git2/0.21.0). Those dependencies are excluded
from the `weavatrix-git` package.
Before single-repository timing, the harness proves:
1. exact first-parent history identifier order;
2. exact raw commit-object bytes;
3. exact byte-sorted index path sets.
Each operation gets three warmups. Engine order rotates on every measured
iteration to reduce CPU and operating-system cache order bias. `gix` uses
`max-performance-safe`, SHA-1, revision support, and a 32 MiB object cache.
Weavatrix uses its default 32 MiB object and 16 MiB delta caches. `git2` links
the vendored libgit2.
Reproduce:
```powershell
.\scripts\benchmark-competitors.ps1 `
-Repository target\benchmark-fixture-2000 `
-MaxCount 1000 -Iterations 300
.\scripts\create-competitor-index-fixture.ps1 `
-Repository target\benchmark-index-10000 -Files 10000
.\scripts\benchmark-competitors.ps1 `
-Repository target\benchmark-index-10000 `
-MaxCount 1 -Iterations 300
```
Windows, Rust 1.88 MSVC, release builds, 2026-07-27:
| history warm, 1,000 | 0.355/0.635 ms | 0.884/1.444 ms | 1.552/2.184 ms |
| history reopen, 1,000 | 2.521/3.443 ms | 3.940/5.212 ms | 10.483/12.165 ms |
| cached object, 1,000 reads | 0.082/0.121 ms | 0.068/0.101 ms | 5.640/9.184 ms |
| history + raw objects, 1,000 | 0.494/0.725 ms | 0.992/1.606 ms | 1.375/1.941 ms |
| warm canonical paths | 1.160/1.778 ms | 1.100/1.702 ms | 1.489/2.150 ms |
| reopen + canonical paths | 5.225/8.738 ms | 7.745/11.755 ms | 11.251/16.942 ms |
The remaining narrow losses are cached-object access (about 17%) and warm
10,000-path index access (about 5%) versus `gix`. Weavatrix checks index
metadata on every `index_shared()` call so a
rewritten index invalidates the cached snapshot; callers can retain the
returned `Arc<Index>` when they explicitly want a stable zero-check snapshot.
## Direct cross-repository competitors
The same harness accepts `--cross-repo` and opens one persistent handle per
repository in each engine. Before timing it proves exact ordered histories,
shared commit locations, canonical manifest paths, and object identifiers.
Parallel operations use one scoped worker per repository for all engines.
```powershell
.\scripts\benchmark-competitors-cross-repo.ps1 `
-Repositories C:\repo-0,C:\repo-1,C:\repo-2 `
-MaxCount 1000 -Iterations 300
```
Eight independent `--no-hardlinks` clones of the packed 2,000-commit fixture,
Windows, Rust 1.88 MSVC, release builds, 2026-07-27:
| history serial | 5.667/9.818 ms | 10.928/18.119 ms | 16.685/26.907 ms |
| history parallel | 4.080/9.280 ms | 4.325/10.981 ms | 5.561/14.878 ms |
| reopen + parallel history | 11.810/44.020 ms | 16.174/43.364 ms | 30.943/67.009 ms |
| shared commit correlation | 4.148/8.739 ms | 7.357/12.923 ms | 8.767/16.817 ms |
| immutable manifests | 1.736/4.872 ms | 2.077/5.560 ms | 1.920/6.732 ms |
Weavatrix wins all five p50 contracts. The reopen p95 difference from `gix`
is 0.656 ms and is dominated by Windows worker/filesystem scheduling; the
round-robin p50 is the stable ranking used here.
## Reproduce history
```powershell
cargo run --release --example create_fixture -- `
target\benchmark-fixture-2000 2000
cargo run --release --example benchmark -- `
target\benchmark-fixture-2000 1000 100
```
Existing repository:
```powershell
.\scripts\benchmark.ps1 -Repository C:\path\to\repository `
-MaxCount 500 -Iterations 100
```
Cross-repository:
```powershell
cargo run --release --example benchmark_cross_repo -- `
1000 50 C:\repo-a C:\repo-b
```
## Reproduce storage acceleration
The repository must have a clean tracked worktree, index, and bitmap:
```powershell
git -C target\benchmark-fixture-2000 multi-pack-index write --bitmap
.\scripts\benchmark-storage.ps1 `
-Repository target\benchmark-fixture-2000 -Iterations 50
```
The storage harness verifies bitmap reachability against
`git rev-list --objects`, index paths against `git ls-files -z`, and clean
tracked status against `git status --porcelain=v1 -uno`.
## Baseline
Measured on Windows on 2026-07-27 using Rust 1.88 and Git 2.54:
| 1,000/2,000 commits | Weavatrix warm | 0.086 ms | 0.118 ms | yes |
| 1,000/2,000 commits | Weavatrix reopen | 2.273 ms | 4.071 ms | yes |
| 1,000/2,000 commits | `git.exe rev-list` | 66.961 ms | 116.128 ms | reference |
The same 2,000-commit packed fixture without a commit-graph previously measured
19.710 ms warm and 22.750 ms reopen, versus 68.613 ms for `git.exe`.
## Cross-repository baseline
Two repositories with 1,000 commits each:
| Weavatrix serial | 1.679 ms | 2.027 ms | yes |
| Weavatrix parallel | 1.356 ms | 1.702 ms | yes |
| Weavatrix reopen + parallel | 4.388 ms | 5.103 ms | yes |
| two sequential `git.exe` processes | 137.451 ms | 182.361 ms | reference |
## Storage baseline
One packed repository with a classic MIDX and MIDX bitmap:
| reachability | Weavatrix | 0.431 ms | 0.489 ms | 6,000 |
| reachability | `git.exe` | 72.656 ms | 108.678 ms | 6,000 |
| index | Weavatrix | 0.033 ms | 0.049 ms | 1 |
| index | `git.exe` | 60.758 ms | 81.199 ms | 1 |
| tracked status | Weavatrix | 0.186 ms | 0.345 ms | 0 changes |
| tracked status | `git.exe` | 72.735 ms | 104.977 ms | 0 changes |
| cached commit | Weavatrix | 0.001 ms | 0.001 ms | 1 |
| cached commit | `git.exe` | 65.267 ms | 94.163 ms | 1 |
These figures demonstrate the process-elimination contract. They do not rank
the crate against in-process `gix` or `libgit2`.