]>
Commit | Line | Data |
---|---|---|
8cbace93 ÆAB |
1 | gitformat-commit-graph(5) |
2 | ========================= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitformat-commit-graph - Git commit graph format | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | $GIT_DIR/objects/info/commit-graph | |
12 | $GIT_DIR/objects/info/commit-graphs/* | |
13 | ||
14 | DESCRIPTION | |
15 | ----------- | |
b84f767c DS |
16 | |
17 | The Git commit graph stores a list of commit OIDs and some associated | |
18 | metadata, including: | |
19 | ||
5a3b130c | 20 | - The generation number of the commit. |
b84f767c DS |
21 | |
22 | - The root tree OID. | |
23 | ||
24 | - The commit date. | |
25 | ||
26 | - The parents of the commit, stored using positional references within | |
27 | the graph file. | |
28 | ||
76ffbca7 GS |
29 | - The Bloom filter of the commit carrying the paths that were changed between |
30 | the commit and its first parent, if requested. | |
31 | ||
b84f767c | 32 | These positional references are stored as unsigned 32-bit integers |
06994ae0 | 33 | corresponding to the array position within the list of commit OIDs. Due |
a9aa3c09 DS |
34 | to some special constants we use to track parents, we can store at most |
35 | (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits. | |
b84f767c DS |
36 | |
37 | == Commit graph files have the following format: | |
38 | ||
39 | In order to allow extensions that add extra data to the graph, we organize | |
40 | the body into "chunks" and provide a binary lookup table at the beginning | |
41 | of the body. The header includes certain values, such as number of chunks | |
42 | and hash type. | |
43 | ||
6141cdfd | 44 | All multi-byte numbers are in network byte order. |
b84f767c | 45 | |
8cbace93 | 46 | === HEADER: |
b84f767c DS |
47 | |
48 | 4-byte signature: | |
49 | The signature is: {'C', 'G', 'P', 'H'} | |
50 | ||
51 | 1-byte version number: | |
52 | Currently, the only valid version is 1. | |
53 | ||
665d70ad DS |
54 | 1-byte Hash Version |
55 | We infer the hash length (H) from this value: | |
56 | 1 => SHA-1 | |
57 | 2 => SHA-256 | |
58 | If the hash type does not match the repository's hash algorithm, the | |
59 | commit-graph file should be ignored with a warning presented to the | |
60 | user. | |
b84f767c DS |
61 | |
62 | 1-byte number (C) of "chunks" | |
63 | ||
118bd570 DS |
64 | 1-byte number (B) of base commit-graphs |
65 | We infer the length (H*B) of the Base Graphs chunk | |
66 | from this value. | |
b84f767c | 67 | |
8cbace93 | 68 | === CHUNK LOOKUP: |
b84f767c DS |
69 | |
70 | (C + 1) * 12 bytes listing the table of contents for the chunks: | |
71 | First 4 bytes describe the chunk id. Value 0 is a terminating label. | |
72 | Other 8 bytes provide the byte-offset in current file for chunk to | |
73 | start. (Chunks are ordered contiguously in the file, so you can infer | |
74 | the length using the next chunk position if necessary.) Each chunk | |
75 | ID appears at most once. | |
76 | ||
a43a2e6c | 77 | The CHUNK LOOKUP matches the table of contents from |
977c47b4 | 78 | the chunk-based file format, see linkgit:gitformat-chunk[5] |
a43a2e6c | 79 | |
b84f767c DS |
80 | The remaining data in the body is described one chunk at a time, and |
81 | these chunks may be given in any order. Chunks are required unless | |
82 | otherwise specified. | |
83 | ||
8cbace93 | 84 | === CHUNK DATA: |
b84f767c | 85 | |
8cbace93 | 86 | ==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) |
b84f767c DS |
87 | The ith entry, F[i], stores the number of OIDs with first |
88 | byte at most i. Thus F[255] stores the total | |
89 | number of commits (N). | |
90 | ||
8cbace93 | 91 | ==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) |
b84f767c DS |
92 | The OIDs for all commits in the graph, sorted in ascending order. |
93 | ||
8cbace93 | 94 | ==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) |
b84f767c DS |
95 | * The first H bytes are for the OID of the root tree. |
96 | * The next 8 bytes are for the positions of the first two parents | |
e40e9365 | 97 | of the ith commit. Stores value 0x70000000 if no parent in that |
b84f767c DS |
98 | position. If there are more than two parents, the second value |
99 | has its most-significant bit on and the other bits store an array | |
5af7417b | 100 | position into the Extra Edge List chunk. |
5a3b130c AK |
101 | * The next 8 bytes store the topological level (generation number v1) |
102 | of the commit and | |
b84f767c DS |
103 | the commit time in seconds since EPOCH. The generation number |
104 | uses the higher 30 bits of the first 4 bytes, while the commit | |
105 | time uses the 32 bits of the second 4 bytes, along with the lowest | |
106 | 2 bits of the lowest byte, storing the 33rd and 34th bit of the | |
107 | commit time. | |
108 | ||
8cbace93 | 109 | ==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] |
5a3b130c AK |
110 | * This list of 4-byte values store corrected commit date offsets for the |
111 | commits, arranged in the same order as commit data chunk. | |
112 | * If the corrected commit date offset cannot be stored within 31 bits, | |
113 | the value has its most-significant bit on and the other bits store | |
114 | the position of corrected commit date into the Generation Data Overflow | |
115 | chunk. | |
116 | * Generation Data chunk is present only when commit-graph file is written | |
117 | by compatible versions of Git and in case of split commit-graph chains, | |
118 | the topmost layer also has Generation Data chunk. | |
119 | ||
8cbace93 | 120 | ==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] |
5a3b130c AK |
121 | * This list of 8-byte values stores the corrected commit date offsets |
122 | for commits with corrected commit date offsets that cannot be | |
123 | stored within 31 bits. | |
124 | * Generation Data Overflow chunk is present only when Generation Data | |
125 | chunk is present and atleast one corrected commit date offset cannot | |
126 | be stored within 31 bits. | |
127 | ||
8cbace93 | 128 | ==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] |
b84f767c DS |
129 | This list of 4-byte values store the second through nth parents for |
130 | all octopus merges. The second parent value in the commit data stores | |
131 | an array position within this list along with the most-significant bit | |
132 | on. Starting at that array position, iterate through this list of commit | |
133 | positions for the parents until reaching a value with the most-significant | |
134 | bit on. The other bits correspond to the position of the last parent. | |
135 | ||
8cbace93 | 136 | ==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] |
88093289 DS |
137 | * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters |
138 | from commit 0 to commit i (inclusive) in lexicographic order. The Bloom | |
139 | filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header | |
140 | length), where BIDX[-1] is 0. | |
76ffbca7 GS |
141 | * The BIDX chunk is ignored if the BDAT chunk is not present. |
142 | ||
8cbace93 | 143 | ==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] |
76ffbca7 GS |
144 | * It starts with header consisting of three unsigned 32-bit integers: |
145 | - Version of the hash algorithm being used. We currently only support | |
146 | value 1 which corresponds to the 32-bit version of the murmur3 hash | |
147 | implemented exactly as described in | |
148 | https://en.wikipedia.org/wiki/MurmurHash#Algorithm and the double | |
149 | hashing technique using seed values 0x293ae76f and 0x7e646e2 as | |
150 | described in https://doi.org/10.1007/978-3-540-30494-4_26 "Bloom Filters | |
151 | in Probabilistic Verification" | |
152 | - The number of times a path is hashed and hence the number of bit positions | |
153 | that cumulatively determine whether a file is present in the commit. | |
154 | - The minimum number of bits 'b' per entry in the Bloom filter. If the filter | |
155 | contains 'n' entries, then the filter size is the minimum number of 64-bit | |
156 | words that contain n*b bits. | |
157 | * The rest of the chunk is the concatenation of all the computed Bloom | |
158 | filters for the commits in lexicographic order. | |
159 | * Note: Commits with no changes or more than 512 changes have Bloom filters | |
59f0d507 | 160 | of length one, with either all bits set to zero or one respectively. |
76ffbca7 GS |
161 | * The BDAT chunk is present if and only if BIDX is present. |
162 | ||
8cbace93 | 163 | ==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] |
118bd570 DS |
164 | This list of H-byte hashes describe a set of B commit-graph files that |
165 | form a commit-graph chain. The graph position for the ith commit in this | |
166 | file's OID Lookup chunk is equal to i plus the number of commits in all | |
167 | base graphs. If B is non-zero, this chunk must exist. | |
168 | ||
8cbace93 | 169 | === TRAILER: |
b84f767c DS |
170 | |
171 | H-byte HASH-checksum of all of the above. | |
6dbf4b81 DS |
172 | |
173 | == Historical Notes: | |
174 | ||
175 | The Generation Data (GDA2) and Generation Data Overflow (GDO2) chunks have | |
176 | the number '2' in their chunk IDs because a previous version of Git wrote | |
177 | possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By | |
178 | changing the IDs, newer versions of Git will silently ignore those older | |
179 | chunks and write the new information without trusting the incorrect data. | |
8cbace93 ÆAB |
180 | |
181 | GIT | |
182 | --- | |
183 | Part of the linkgit:git[1] suite |