Git Reference ยท Objects, Refs and Internals
Commit-graph file
Reference for the commit-graph file: the CGPH header, chunk table, generation numbers, changed-path Bloom filters, split chains and how to write and verify it.
The commit-graph file is a compact, read-only cache of the commit history. Walking history normally means opening each commit object, decompressing it and parsing the parent lines. The commit-graph stores the same facts (parents, root tree, commit time, and more) in sorted arrays, so git log --graph, git merge-base, git branch --contains and git tag --contains can run without touching the object database for most commits.
It lives at .git/objects/info/commit-graph (or as a chain of files in .git/objects/info/commit-graphs/). It is purely an optimization: deleting it never changes results, only speed. git gc, git maintenance and git fetch (with fetch.writeCommitGraph) can keep it fresh.
git commit-graph write --reachable # write it git commit-graph write --reachable --changed-paths # add Bloom filters git commit-graph verify # check it against the objects
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Format
All numbers are big-endian. The file has four parts: header, chunk table, chunks and a trailing checksum.
| Part | Content |
|---|---|
| Header | CGPH, version (1), hash version (1 = SHA-1, 2 = SHA-256), number of chunks, number of base graphs (0 unless split). |
| Chunk table | One row per chunk: a four-character ID and the 8-byte file offset of that chunk, plus a final row marking the end. |
| Chunks | The data, see below. |
| Trailer | The checksum of everything before it. |
Chunks
| ID | Content |
|---|---|
OIDF |
OID fan-out: 256 counters, as in a pack index. |
OIDL |
All commit IDs in the graph, sorted. |
CDAT |
Per commit: root tree ID, the two parents as positions in OIDL, commit time, and the topological level (generation number v1). |
GDA2 |
Generation data v2: the corrected commit date offset (details below). |
GDO2 |
Overflow table for offsets that do not fit 32 bits. |
EDGE |
Extra parents for octopus merges (more than two parents). |
BIDX, BDAT |
Changed-path Bloom filters: an index with end positions, and the filter data with its settings (hash version, number of hashes, bits per entry). |
BASE |
In a split graph, the checksums of the base graph files. |
A parent is stored as a position, not an ID, so following history is plain array lookup. A commit whose parent is missing from the graph is marked and the object database is consulted for it.
Generation numbers
A generation number answers "can A possibly be an ancestor of B?" without walking. Topological level is 1 for a root and 1 + max(parent levels) otherwise: if A has a level greater than or equal to B's, A cannot be a proper ancestor of B. Corrected commit date (stored in GDA2 as an offset from the commit time) fixes the weakness of using raw time stamps when clocks were wrong, and is the default in recent Git versions. Commands such as git merge-base --is-ancestor, git branch --contains and git log A..B use them to stop walking early.
Changed-path Bloom filters
A Bloom filter is a small bit array that can say "this path was definitely not changed by this commit" or "maybe it was". With --changed-paths, each commit stores a filter of the paths it changed compared with its first parent. git log -- <path> and git blame then skip most commits without computing a diff. Filters are tuned by commitGraph.changedPathsVersion; a graph written with different settings than the ones in use is ignored for Bloom purposes.
Usage notes
- Split commit-graphs.
git commit-graph write --splitadds a new small layer instead of rewriting everything;commitGraph.maxNewFiltersand--max-commitscontrol merging of layers. Maintenance does this automatically. - Safe to delete. Removing the file or the chain directory only slows commands down.
git gc --autoandgit maintenance run --task=commit-graphrecreate it. - Grafts and replace refs. Git disables the commit-graph when it finds grafts or
refs/replaceentries that change parents, because the stored parents would be wrong. - Shallow repositories do not use a commit-graph, as the parents of cut-off commits are missing.
- Corruption.
git commit-graph verifycompares every field with the real objects. On mismatch, rewrite withgit commit-graph write --reachable. - Config.
core.commitGraph(default true) turns reading on,gc.writeCommitGraphandfetch.writeCommitGraphcontrol automatic writing.