Git Commit-Graph: Accelerating Commit History Walks

Advanced

The commit graph and the commit-graph file are different things

Every Git commit already participates in a logical graph because a commit records its parent commit IDs. A commit-graph file is an additional, derived data structure that accelerates graph walks. Removing or disabling the commit-graph file does not remove commits or their ancestry; Git can fall back to the object database.

git log --oneline --graph --all
git commit-graph verify

?

Write a commit-graph for reachable commits

The `write` subcommand creates or updates a commit-graph. With `--reachable`, Git starts from all refs and walks reachable commits. This makes the ownership explicit: the graph is derived from commits that the repository can currently reach through refs.

git commit-graph write --reachable
git commit-graph verify

For the normal non-split layout, Git stores the commit-graph at `.git/objects/info/commit-graph`. The file is derived state; it can be regenerated from repository objects.

?

Verify the derived graph

`git commit-graph verify` checks the commit-graph data structure. It answers a different question from `git fsck`: commit-graph verification checks the auxiliary graph file, while `git fsck` checks object integrity and connectivity in the repository object database.

git commit-graph verify
git fsck --full

?

Changed-path Bloom filters

A commit-graph can optionally include Bloom filters for paths changed between a commit and its first parent. These filters support path-oriented history queries without replacing the commit history or becoming a general-purpose file index.

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

The local Git 2.47.3 verifier supports this command form, and the official current documentation describes `--changed-paths` as writing changed-path Bloom filters. Because the feature is an optimization, omitting the filters does not make the commit history invalid.

?

Split commit-graph chains

For repositories that grow continuously, Git can maintain a chain of commit-graph files instead of rewriting one monolithic graph every time new commit data is added. The chain lives under `.git/objects/info/commit-graphs/`, with a `commit-graph-chain` file describing the graph layers.

git commit-graph write --reachable --split --changed-paths
git commit-graph verify
ls .git/objects/info/commit-graphs

A split chain changes how the derived graph is stored, not what the repository's commits mean. The logical parent relationships remain in commit objects.

?

Configuration and safe boundaries

The `core.commitGraph` configuration controls whether Git consumes commit-graph files. If it is disabled, the object database remains sufficient for history operations, although the optimization is not consumed. The write command also honors this setting and warns rather than writing when the feature is disabled.

git config --get core.commitGraph
git -c core.commitGraph=false commit-graph write --reachable

Do not confuse a commit-graph with a multi-pack-index. A MIDX indexes objects across packfiles; a commit-graph indexes commit ancestry and related metadata. V479 owns MIDX administration, while this lesson owns the commit-graph subsystem.

?

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.