Appearance
Git commit-graph for DevOps performance
The commit-graph is a binary file in .git/objects/info/commit-graph that caches commit metadata Git would otherwise recompute by walking the object store. For repos over 10,000 commits it makes git log --graph 10x faster, git merge-base near-instant, and git log -- <path> constant-time with the Bloom filter extension.
This guide covers the architecture, the two config knobs, the Bloom filter, incremental graphs, verification, and CI/CD patterns.
1. What the commit-graph stores
Without a commit-graph, Git reads each commit object from the object store (loose or packed), parses it, and follows parent pointers to walk the DAG. With a commit-graph, Git reads a single pre-built file that contains:
- Commit SHA and OID position
- Parent OID positions (up to 2 parents; merge commits with 3+ parents fall back to object store)
- Root tree OID
- Commit date
- Generation number (for topological sort without walking the full graph)
- Optional Bloom filter (changed-path) data
The file lives at .git/objects/info/commit-graph. For incremental graphs, a chain lives in .git/objects/info/commit-graphs/.
2. The two config knobs
ini
# Write the commit-graph during gc
gc.writeCommitGraph = true
# Write the commit-graph during fetch (so fetches pre-warm it)
fetch.writeCommitGraph = truegc.writeCommitGraph is the main one. Set it on every repo. fetch.writeCommitGraph is for CI runners that fetch fresh data often. Together they keep the graph fresh without manual intervention.
3. The Bloom filter (changed-path) extension
Added in Git 2.27, the Bloom filter is what makes git log -- <path> fast on large repos.
Without Bloom filter
git log --all -- Makefile walks every commit in every branch and checks whether the path changed in that commit's tree. For a 500k-commit monorepo, that is 500k tree diffs. It takes 30-60 seconds.
With Bloom filter
The commit-graph stores a Bloom filter per commit that records which paths were changed. git log --all -- Makefile checks the Bloom filter first. If it says "no", Git skips the tree diff entirely. False positives are possible but rare (Bloom filter false positive rate is ~1% with default settings). The result: git log --all -- Makefile drops from 45 seconds to under 1 second.
How to enable
bash
# Set the config
git config gc.writeCommitGraph true
# Write the graph with Bloom filter (requires --changed-paths)
git commit-graph write --reachable --changed-paths
# Verify Bloom filter is present
git commit-graph verify --no-progress 2>&1 | grep -i bloomThe --changed-paths flag is critical. Without it, the commit-graph omits the Bloom filter extension and you only get generation numbers.
Bloom filter limitations
- False positives. The Bloom filter can say a path changed when it did not. Git then does the real tree diff to confirm. This is correct but wastes a tiny bit of work.
- Not updated on partial writes. If you write an incremental graph layer, the Bloom filter for older commits stays as-is. Only new commits get a Bloom filter.
- No Bloom filter for merge commits with 3+ parents. Git skips them.
- Bloom filter size. Each commit's Bloom filter is ~12 bytes per changed path. For a monorepo with 10 changed paths per commit, the Bloom filter adds ~120 bytes per commit to the commit-graph file.
4. Generation numbers
Generation numbers let Git sort commits topologically without walking the full DAG.
How they work
Each commit gets a generation number. For a commit with no parents (root commit), it is 1. For a commit with one parent, it is parent + 1. For a merge commit with two parents, it is max(parent1, parent2) + 1.
Git uses generation numbers in git log --graph, git merge-base, and git rev-list --topo-order to stop walking as soon as it knows all remaining commits have a lower generation number. Without this, Git must walk every commit to prove it has reached the root.
Generation number v1 vs v2
- v1 (GDA1). The original. Uses commit date as the generation number. Works for most repos but can overflow on repos with commits spanning decades or very high commit frequency.
- v2 (GDA2). Corrected generation date. Handles overflow by falling back to topological level. Git 2.32+ uses this by default when writing a new commit-graph.
You can check which version your commit-graph uses:
bash
git commit-graph verify --no-progress 2>&1 | head -5Look for chunk: GDA2 (v2) vs chunk: GDA1 (v1).
5. Incremental commit-graphs
Writing the full commit-graph on a 500k-commit repo takes 10-30 seconds. Incremental graphs split the work.
How incremental works
Instead of rewriting the whole graph, Git writes a new layer containing only commits added since the last graph write. Layers stack up to 64 by default (controlled by commitGraph.maxNewFilters). When the chain is full, Git consolidates into a single graph.
The layers live in .git/objects/info/commit-graphs/:
.git/objects/info/commit-graphs/
commit-graph-chain # ordered list of layer filenames
graph-<hash1>.graph # base layer
graph-<hash2>.graph # incremental layer 1
...How git maintenance uses it
git maintenance run --task=commit-graph writes an incremental graph. It adds a layer for new commits without rewriting the full graph. The weekly git maintenance run --task=commit-graph consolidates when the chain exceeds the limit.
bash
# Manual incremental write
git commit-graph write --reachable --changed-paths --split
# Manual consolidation (rewrite from scratch)
git commit-graph write --reachable --changed-pathsWhen to consolidate
- The incremental chain hits the limit (64 layers by default).
- You want to prune stale commit data after a filter-repo or replace operation.
- You are about to clone or fork the repo and want the new copy to have a clean graph.
6. Verification and debugging
bash
# Verify the commit-graph file integrity
git commit-graph verify
# Show commit-graph stats
git commit-graph verify --no-progress --stats 2>&1
# Check if Bloom filter is present
git commit-graph verify --no-progress 2>&1 | grep -i bloom
# Count commits in the graph
git commit-graph verify --no-progress --stats 2>&1 | grep "commits"
# List graph layers
ls -la .git/objects/info/commit-graphs/
cat .git/objects/info/commit-graphs/commit-graph-chainDiagnosing performance problems
If git log --graph is still slow after enabling the commit-graph, check:
- Is the config set?
git config gc.writeCommitGraphshould returntrue. - Was the graph written?
test -f .git/objects/info/commit-graphor check for thecommit-graphs/directory. - Was it written with
--changed-paths? Without it, Bloom filters are absent andgit log -- <path>stays slow. - Is the incremental chain too long? A chain of 64 layers has overhead. Run
git commit-graph write --reachable --changed-pathsto consolidate. - Is the Bloom filter large enough? Git uses a default of 80 bits and 7 hashes. For repos with very high path diversity per commit, increase it with
--max-new-filtersorcommitGraph.maxNewFilters.
7. CI/CD patterns
Pattern 1: Pre-warm the graph on CI runner setup
If your CI runners are long-lived (ephemeral VMs that persist for hours or days), write the commit-graph after clone:
bash
# In your CI setup step
git clone --filter=blob:none https://git.internal/repo.git .
git config gc.writeCommitGraph true
git commit-graph write --reachable --changed-pathsThis makes every subsequent git log, git merge-base, and git diff-tree faster for the runner's lifetime.
Pattern 2: Fetch-time graph generation
For CI pipelines that fetch multiple times (merge trains, matrix builds), enable fetch-time graph writing:
bash
git config fetch.writeCommitGraph trueEach fetch appends new commits to the incremental commit-graph. The cost is small (a few hundred milliseconds per fetch) and amortizes immediately.
Pattern 3: Bloom filter for monorepo path scoping
In a monorepo CI, you need to know which services changed. The Bloom filter makes git log -- <path> fast enough to run per-service:
bash
# In CI, after checkout
CHANGED_SERVICES=""
for service in auth api web worker; do
if git log --oneline HEAD~5..HEAD -- "services/$service/" | head -1 | grep -q .; then
CHANGED_SERVICES="$CHANGED_SERVICES $service"
fi
doneWithout the commit-graph Bloom filter, this loop runs 5 tree diffs. With it, each git log is a Bloom filter lookup plus a handful of tree diffs for the commits that do touch the path.
Pattern 4: Merge-base speed for PR checks
git merge-base is used by nearly every CI pipeline to find the divergence point between a PR branch and its target. Without a commit-graph, it walks the DAG backward from both tips. With generation numbers, it stops at the first common ancestor.
bash
# Without commit-graph: walks hundreds of thousands of commits
# With commit-graph: walks dozens
MERGE_BASE=$(git merge-base HEAD origin/main)In a repo with 100k commits, this goes from ~2 seconds to ~50 milliseconds.
Pattern 5: Post-clone graph generation for ephemeral runners
Ephemeral runners (GitHub Actions, GitLab SaaS) start fresh each job. Writing the commit-graph on every job is wasteful. Instead, embed the commit-graph in the CI image or use a reference clone that already has it.
bash
# Option A: Reference clone with pre-built graph
git clone --reference /var/cache/git/repo.git \
https://git.internal/repo.git .
# Option B: Generate graph only if missing and repo is large
if [ ! -f .git/objects/info/commit-graph ]; then
COMMIT_COUNT=$(git rev-list --count HEAD)
if [ "$COMMIT_COUNT" -gt 10000 ]; then
git commit-graph write --reachable --changed-paths
fi
fi8. Performance benchmarks
These are representative numbers from a 150k-commit monorepo on an NVMe disk:
| Operation | Without commit-graph | With commit-graph | With Bloom filter |
|---|---|---|---|
git log --oneline -10 | 0.4s | 0.02s | 0.02s |
git log --graph --all --oneline -100 | 4.2s | 0.3s | 0.3s |
git merge-base HEAD origin/main | 1.8s | 0.05s | 0.05s |
git log --all -- Makefile | 45s | 40s | 0.8s |
git rev-list --count --all | 3.1s | 0.1s | 0.1s |
git diff --name-only HEAD~100 | 0.9s | 0.9s | 0.9s |
The Bloom filter column shows the biggest win: git log -- <path> goes from 45 seconds to under a second.
9. Pitfalls
Bloom filter false positives cause rare tree diffs. The Bloom filter can say a path changed when it did not. Git then does the real tree diff. This is correct but wastes milliseconds per false positive. The false positive rate is ~1% with default settings.
Generation number overflow on very old repos. Repos with commits from before 2000 can trigger generation number overflow. Git 2.32+ handles this with GDA2. If you are on an older Git version and see error: commit-graph generation number overflow, upgrade Git or force a graph rewrite with --no-progress.
Incremental chain performance degrades past 64 layers. Each layer lookup adds overhead. Consolidate periodically or rely on git maintenance --task=commit-graph which does this automatically on its weekly schedule.
The commit-graph is not written by default. You must set gc.writeCommitGraph = true or run git commit-graph write explicitly. Many hosting platforms do not set this. Check.
Bloom filter is not updated on amend. If you amend a commit after the commit-graph was written, the Bloom filter for that commit is stale. A full graph rewrite fixes it.
git commit-graph write is a foreground operation. It blocks. For repos with 500k+ commits, this takes 10-30 seconds. Use incremental writes (--split) to keep the pause short.
The commit-graph file can become corrupted. Run git commit-graph verify in your CI health check to catch corruption early. A corrupted commit-graph causes Git to fall back to object store reads (slow but correct).
10. Quick setup
bash
# Enable on an existing repo
git config gc.writeCommitGraph true
git commit-graph write --reachable --changed-paths
# Enable for all future repos
git config --global gc.writeCommitGraph true
# For CI runners that fetch often
git config fetch.writeCommitGraph true
# Schedule via maintenance (Git 2.30+)
git maintenance start
# Verify
git commit-graph verify --no-progress --stats 2>&1Summary
| Need | Command |
|---|---|
| Write the commit-graph | git commit-graph write --reachable --changed-paths |
| Write incrementally | git commit-graph write --reachable --changed-paths --split |
| Enable auto-write on gc | git config gc.writeCommitGraph true |
| Enable auto-write on fetch | git config fetch.writeCommitGraph true |
| Verify integrity | git commit-graph verify |
| Check Bloom filter | git commit-graph verify --no-progress 2>&1 | grep bloom |
| Consolidate chain | git commit-graph write --reachable --changed-paths |
| Schedule via maintenance | git maintenance start |