git commit-graph

Massive log/walk speedup. Modern repos all want this.

🎯 What & why

git commit-graph builds and maintains the commit-graph file — an auxiliary index of commit metadata that makes git log, --graph, reachability queries, and ancestry checks dramatically faster on large repos.

🧠 Mental model

A cache file at .git/objects/info/commit-graph (or under commit-graphs/ when split). It stores parent pointers, commit times, generation numbers, and optionally changed-path Bloom filters — all derived from existing commit objects. Refs and the object DB are unchanged; this is pure read-side acceleration. Auto-written by git maintenance and gc.writeCommitGraph=true.

🛠️ Synopsis

git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]
git commit-graph write  [--object-dir <dir>] [--append|--split[=<strategy>]]
                        [--reachable | --stdin-packs | --stdin-commits]
                        [--changed-paths] [--max-new-filters=<n>] [--[no-]progress]

🎚️ Switches & options

Flag	What it does
`--reachable`	Walk every ref to discover commits. Most common; produces a full graph.
`--stdin-packs`	Read pack-index filenames from stdin and include only commits in those packs.
`--stdin-commits`	Read commit OIDs from stdin and include only those (and optionally their ancestors).
`--changed-paths`	Also compute Bloom filters of changed file paths — speeds up `git log -- <path>` enormously.
`--split[=<strategy>]`	Write an incremental layered graph instead of one monolithic file. Strategies: `no-merge`, `replace`.
`--append`	Append new commits to the existing graph rather than rewriting from scratch.
`--object-dir <dir>`	Operate on the graph in <dir>/info/ instead of the default object directory.

📦 Subcommands

verify — Sanity-check an existing commit-graph file; exits non-zero on corruption.

git commit-graph verify

write — Build or update the commit-graph file from reachable commits or supplied input.

git commit-graph write --reachable --changed-paths

read — (Debug) Dump the parsed contents of the current commit-graph file.

git commit-graph read

💡 Use cases

Speed up git log --graph --oneline on repos with hundreds of thousands of commits.
Make path-filtered history (git log -- some/file) usable on monorepos via --changed-paths.
Detect graph corruption after a crash or disk error with verify.
Keep the graph cheap to maintain on huge repos using --split so writes stay incremental.

🧪 Examples

Build a full graph from all refs

git commit-graph write --reachable

Add Bloom filters for path queries

git commit-graph write --reachable --changed-paths

Incremental split write

git commit-graph write --reachable --split

Verify integrity

git commit-graph verify

🎓 Recommendations

Enable git config --global maintenance.commit-graph.enabled true and run git maintenance start — let Git keep the graph current for you.
Always pass --changed-paths when your workflow involves heavy git log -- <path> queries.
Use --split on very large repos so daily updates do not rewrite a multi-hundred-MB file each time.

🪤 Common pitfalls

A stale or corrupt commit-graph yields wrong reachability answers and bizarre git log results — verify is your friend after crashes.
Bloom filters from --changed-paths only accelerate queries when the graph was written with them; mixing graphs with/without them is a common puzzle.
Manually rewriting refs (e.g., aggressive history surgery) without re-running write leaves the graph referencing dropped commits until next refresh.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.