Skip to content

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 = true

gc.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 bloom

The --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 -5

Look 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-paths

When 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-chain

Diagnosing performance problems ​

If git log --graph is still slow after enabling the commit-graph, check:

  1. Is the config set? git config gc.writeCommitGraph should return true.
  2. Was the graph written? test -f .git/objects/info/commit-graph or check for the commit-graphs/ directory.
  3. Was it written with --changed-paths? Without it, Bloom filters are absent and git log -- <path> stays slow.
  4. Is the incremental chain too long? A chain of 64 layers has overhead. Run git commit-graph write --reachable --changed-paths to consolidate.
  5. 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-filters or commitGraph.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-paths

This 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 true

Each 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
done

Without 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
fi

8. Performance benchmarks ​

These are representative numbers from a 150k-commit monorepo on an NVMe disk:

OperationWithout commit-graphWith commit-graphWith Bloom filter
git log --oneline -100.4s0.02s0.02s
git log --graph --all --oneline -1004.2s0.3s0.3s
git merge-base HEAD origin/main1.8s0.05s0.05s
git log --all -- Makefile45s40s0.8s
git rev-list --count --all3.1s0.1s0.1s
git diff --name-only HEAD~1000.9s0.9s0.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>&1

Summary ​

NeedCommand
Write the commit-graphgit commit-graph write --reachable --changed-paths
Write incrementallygit commit-graph write --reachable --changed-paths --split
Enable auto-write on gcgit config gc.writeCommitGraph true
Enable auto-write on fetchgit config fetch.writeCommitGraph true
Verify integritygit commit-graph verify
Check Bloom filtergit commit-graph verify --no-progress 2>&1 | grep bloom
Consolidate chaingit commit-graph write --reachable --changed-paths
Schedule via maintenancegit maintenance start

Git Master — Git Reference for Every Skill Level