format-commit-graph Git Command Guide

The git format-commit-graph format stores a list of commit OIDs and associated metadata to enable fast commit graph operations. The commit-graph format includes generation numbers, root tree OIDs, commit dates, parent references, and optionally Bloom filters for changed paths.

Commit-Graph Format Specification

Header Format:

• 4-byte signature: ‘C’, ‘G’, ‘P’, ‘H’
• 1-byte version number: Currently version 1
• 1-byte hash version: 1 = SHA-1, 2 = SHA-256
• 1-byte number of chunks (C): Number of data chunks
• 1-byte number of base graphs (B): Number of base commit-graphs

Stored Data:

Data	Description
Generation number	Commit’s topological generation number
Root tree OID	SHA-1/SHA-256 hash of the root tree object
Commit date	Author date of the commit
Parent references	32-bit indices into the commit-graph array
Bloom filter	Optional filter of changed paths vs first parent

Features:

Version History:

Version	Features
1	Basic commit metadata storage

Chunk Types:

Chunk	Description
OIDF	Base commit-graph OIDs
OIDL	OID lookup table
CDAT	Commit data (dates, generations)
BIDX	Base graphs chunk indices
PIDX	Parent indices
GIDX	Generation data index

Caution

Commit-graph files must match the repository’s hash algorithm (SHA-1 vs SHA-256). Corrupted graphs should be regenerated using git commit-graph write --reachable.

Examples of git commit-graph usage:

Write commit graph for current branch

git commit-graph write --reachable

Creates commit-graph file for reachable commits from all refs.

Check if commit graph exists

ls -la .git/objects/info/commit-graph

Verify commit-graph file exists in repository.

Read commit graph statistics

git commit-graph verify

Verify commit-graph integrity and show statistics.

Write graph for specific references

git commit-graph write --stdin-commits < commits.txt

Create commit-graph for commits listed in file.

Split commit graph for large repos

git commit-graph write --split --reachable

Write incremental commit-graph allowing future updates.

Verify graph supports SHA-256

git commit-graph write --reachable --hash-version=2

Create SHA-256 compatible commit-graph (Git 2.29+).

Tip

Commit-graph speeds up operations like git log --graph and ancestor walks by ~30-50%. Use git gc --auto to create it automatically.

How does commit-graph improve performance?

The commit-graph stores commit metadata (dates, generations, parents) in a contiguous format, reducing I/O when traversing commit history.

What operations benefit from commit-graph?

Operations like git log --oneline, git branch --contains, and merge-base calculations see significant speedups.

How do I check commit-graph status?

Run git commit-graph verify to check integrity or git log --oneline -500 | tail -10 to test if it’s automatically loaded.

Can I convert from SHA-1 to SHA-256?

Yes, use newer Git versions with git commit-graph write --reachable --hash-version=2 for SHA-256 support.

What happens if commit-graph is corrupted?

If corrupted, Git falls back to original object traversal. Regenerate with git commit-graph write --reachable --force.

How does generation numbering work?

Generation numbers represent topological order, enabling efficient ancestor queries and avoiding redundant recursive traversals.

Applications of the commit-graph format

1. Repository Performance: Speeds up git operations in large repositories
2. Scalability: Enables efficient operations on repositories with millions of commits
3. Memory Efficiency: Reduces memory usage during commit graph traversals
4. CI/CD Optimization: Limits ancestor walk overhead in build pipelines
5. Large Projects: Essential for enterprises repos with complex merge histories
6. Network Efficiency: Optimizes fetch and clone operations in distributed workflows