docs: move commit-graph format docs to man section 5
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the documentation for the commit-graph format into man section 5 and the new "developerinterfaces" category. This change is split from subsequent commits due to the relatively large amount of ASCIIDOC formatting changes that are required. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Aug 4, 2022 at 18:28 UTC
8cbace93d270dc49f007a2c1922769240a22eca5
5 files changed
+41
-17
Documentation/Makefile
+1
@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt
25
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
26
MAN5_TXT += gitattributes.txt
27
MAN5_TXT += gitformat-bundle.txt
28
+MAN5_TXT += gitformat-commit-graph.txt
29
MAN5_TXT += githooks.txt
30
MAN5_TXT += gitignore.txt
31
MAN5_TXT += gitmailmap.txt
Documentation/git-commit-graph.txt
+5
@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
143
------------------------------------------------
144
145
146
+FILE FORMAT
147
+-----------
148
+
149
+see linkgit:gitformat-commit-graph[5].
150
+
151
GIT
152
---
153
Part of the linkgit:git[1] suite
Documentation/gitformat-commit-graph.txt
renamed
+32
-15
@@ -1,5 +1,18 @@
1
-Git commit graph format
2
-=======================
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
+-----------
16
17
The Git commit graph stores a list of commit OIDs and some associated
18
metadata, including:
@@ -30,7 +43,7 @@ and hash type.
43
44
All multi-byte numbers are in network byte order.
45
33
-HEADER:
46
+=== HEADER:
47
48
4-byte signature:
49
The signature is: {'C', 'G', 'P', 'H'}
@@ -52,7 +65,7 @@ HEADER:
65
We infer the length (H*B) of the Base Graphs chunk
66
from this value.
67
55
-CHUNK LOOKUP:
68
+=== CHUNK LOOKUP:
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.
@@ -68,17 +81,17 @@ CHUNK LOOKUP:
81
these chunks may be given in any order. Chunks are required unless
82
otherwise specified.
83
71
-CHUNK DATA:
84
+=== CHUNK DATA:
85
73
- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
86
+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
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
78
- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
91
+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
92
The OIDs for all commits in the graph, sorted in ascending order.
93
81
- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
94
+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
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
97
of the ith commit. Stores value 0x70000000 if no parent in that
@@ -93,7 +106,7 @@ CHUNK DATA:
106
2 bits of the lowest byte, storing the 33rd and 34th bit of the
107
commit time.
108
96
- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
109
+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
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,
@@ -104,7 +117,7 @@ CHUNK DATA:
117
by compatible versions of Git and in case of split commit-graph chains,
118
the topmost layer also has Generation Data chunk.
119
107
- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
120
+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
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.
@@ -112,7 +125,7 @@ CHUNK DATA:
125
chunk is present and atleast one corrected commit date offset cannot
126
be stored within 31 bits.
127
115
- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
128
+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
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
@@ -120,14 +133,14 @@ CHUNK DATA:
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
123
- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
136
+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
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.
141
* The BIDX chunk is ignored if the BDAT chunk is not present.
142
130
- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
143
+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
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,13 +160,13 @@ CHUNK DATA:
160
of length one, with either all bits set to zero or one respectively.
161
* The BDAT chunk is present if and only if BIDX is present.
162
150
- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
163
+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
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
156
-TRAILER:
169
+=== TRAILER:
170
171
H-byte HASH-checksum of all of the above.
172
@@ -164,3 +177,7 @@ 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.
180
+
181
+GIT
182
+---
183
+Part of the linkgit:git[1] suite
Documentation/technical/chunk-format.txt
+2
-2
@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by
6
scanning a small "table of contents" for the remaining data. This common
7
format is used by the `commit-graph` and `multi-pack-index` files. See
8
link:technical/pack-format.html[the `multi-pack-index` format] and
9
-link:technical/commit-graph-format.html[the `commit-graph` format] for
9
+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
10
how they use the chunks to describe structured data.
11
12
A chunk-based file format begins with some header information custom to
@@ -108,7 +108,7 @@ for future formats:
108
* *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`
109
in `commit-graph.c` for how the chunk-format API is used to write and
110
parse the commit-graph file format documented in
111
- link:technical/commit-graph-format.html[the commit-graph file format].
111
+ the commit-graph file format in linkgit:gitformat-commit-graph[5].
112
113
* *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
114
in `midx.c` for how the chunk-format API is used to write and
command-list.txt
+1
@@ -210,6 +210,7 @@ gitdiffcore guide
210
giteveryday guide
211
gitfaq guide
212
gitformat-bundle developerinterfaces
213
+gitformat-commit-graph developerinterfaces
214
gitglossary guide
215
githooks userinterfaces
216
gitignore userinterfaces