docs: document SHA-256 pack and indices
Now that we have SHA-256 support for packs and indices, let's document that in SHA-256 repositories, we use SHA-256 instead of SHA-1 for object names and checksums. Instead of duplicating this information throughout the document, let's just document that in SHA-1 repositories, we use SHA-1 for these purposes, and in SHA-256 repositories, we use SHA-256. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson committed
Aug 13, 2020 at 22:49 UTC
17420eafa9e2b7d69ff17dbf4d12088a2152fd9d
1 file changed
+21
-15
Documentation/technical/pack-format.txt
+21
-15
@@ -1,6 +1,12 @@
1
Git pack format
2
===============
3
4
+== Checksums and object IDs
5
+
6
+In a repository using the traditional SHA-1, pack checksums, index checksums,
7
+and object IDs (object names) mentioned below are all computed using SHA-1.
8
+Similarly, in SHA-256 repositories, these values are computed using SHA-256.
9
+
10
== pack-*.pack files have the following format:
11
12
- A header appears at the beginning and consists of the following:
@@ -26,7 +32,7 @@ Git pack format
32
33
(deltified representation)
34
n-byte type and length (3-bit type, (n-1)*7+4-bit length)
29
- 20-byte base object name if OBJ_REF_DELTA or a negative relative
35
+ base object name if OBJ_REF_DELTA or a negative relative
36
offset from the delta object's position in the pack if this
37
is an OBJ_OFS_DELTA object
38
compressed delta data
@@ -34,7 +40,7 @@ Git pack format
40
Observation: length of each object is encoded in a variable
41
length format and is not constrained to 32-bit or anything.
42
37
- - The trailer records 20-byte SHA-1 checksum of all of the above.
43
+ - The trailer records a pack checksum of all of the above.
44
45
=== Object types
46
@@ -58,8 +64,8 @@ ofs-delta and ref-delta, which is only valid in a pack file.
64
65
Both ofs-delta and ref-delta store the "delta" to be applied to
66
another object (called 'base object') to reconstruct the object. The
61
-difference between them is, ref-delta directly encodes 20-byte base
62
-object name. If the base object is in the same pack, ofs-delta encodes
67
+difference between them is, ref-delta directly encodes base object
68
+name. If the base object is in the same pack, ofs-delta encodes
69
the offset of the base object in the pack instead.
70
71
The base object could also be deltified if it's in the same pack.
@@ -143,14 +149,14 @@ This is the instruction reserved for future expansion.
149
object is stored in the packfile as the offset from the
150
beginning.
151
146
- 20-byte object name.
152
+ one object name of the appropriate size.
153
154
- The file is concluded with a trailer:
155
150
- A copy of the 20-byte SHA-1 checksum at the end of
151
- corresponding packfile.
156
+ A copy of the pack checksum at the end of the corresponding
157
+ packfile.
158
153
- 20-byte SHA-1-checksum of all of the above.
159
+ Index checksum of all of the above.
160
161
Pack Idx file:
162
@@ -198,7 +204,7 @@ Pack file entry: <+
204
If it is not DELTA, then deflated bytes (the size above
205
is the size before compression).
206
If it is REF_DELTA, then
201
- 20-byte base object name SHA-1 (the size above is the
207
+ base object name (the size above is the
208
size of the delta data that follows).
209
delta data, deflated.
210
If it is OFS_DELTA, then
@@ -227,9 +233,9 @@ Pack file entry: <+
233
234
- A 256-entry fan-out table just like v1.
235
230
- - A table of sorted 20-byte SHA-1 object names. These are
231
- packed together without offset values to reduce the cache
232
- footprint of the binary search for a specific object name.
236
+ - A table of sorted object names. These are packed together
237
+ without offset values to reduce the cache footprint of the
238
+ binary search for a specific object name.
239
240
- A table of 4-byte CRC32 values of the packed object data.
241
This is new in v2 so compressed data can be copied directly
@@ -248,10 +254,10 @@ Pack file entry: <+
254
255
- The same trailer as a v1 pack file:
256
251
- A copy of the 20-byte SHA-1 checksum at the end of
257
+ A copy of the pack checksum at the end of
258
corresponding packfile.
259
254
- 20-byte SHA-1-checksum of all of the above.
260
+ Index checksum of all of the above.
261
262
== multi-pack-index (MIDX) files have the following format:
263
@@ -329,4 +335,4 @@ CHUNK DATA:
335
336
TRAILER:
337
332
- 20-byte SHA1-checksum of the above contents.
338
+ Index checksum of the above contents.