@matheusbsbs / matheus-bagliano / commits / 9760662f1a
Fork 0

Add Documentation/technical/pack-format.txt

... along with the previous one, pack-heuristics, by popular demand. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Apr 7, 2006 at 02:07 UTC 9760662f1a7a06516ca249a73e5c1a6fb6c0e26e
1 file changed +111
Documentation/technical/pack-format.txt new
+111
@@ -0,0 +1,111 @@
1 +GIT pack format
2 +===============
3 +
4 += pack-*.pack file has the following format:
5 +
6 + - The header appears at the beginning and consists of the following:
7 +
8 + 4-byte signature
9 + 4-byte version number (network byte order)
10 + 4-byte number of objects contained in the pack (network byte order)
11 +
12 + Observation: we cannot have more than 4G versions ;-) and
13 + more than 4G objects in a pack.
14 +
15 + - The header is followed by number of object entries, each of
16 + which looks like this:
17 +
18 + (undeltified representation)
19 + n-byte type and length (4-bit type, (n-1)*7+4-bit length)
20 + compressed data
21 +
22 + (deltified representation)
23 + n-byte type and length (4-bit type, (n-1)*7+4-bit length)
24 + 20-byte base object name
25 + compressed delta data
26 +
27 + Observation: length of each object is encoded in a variable
28 + length format and is not constrained to 32-bit or anything.
29 +
30 + - The trailer records 20-byte SHA1 checksum of all of the above.
31 +
32 += pack-*.idx file has the following format:
33 +
34 + - The header consists of 256 4-byte network byte order
35 + integers. N-th entry of this table records the number of
36 + objects in the corresponding pack, the first byte of whose
37 + object name are smaller than N. This is called the
38 + 'first-level fan-out' table.
39 +
40 + Observation: we would need to extend this to an array of
41 + 8-byte integers to go beyond 4G objects per pack, but it is
42 + not strictly necessary.
43 +
44 + - The header is followed by sorted 28-byte entries, one entry
45 + per object in the pack. Each entry is:
46 +
47 + 4-byte network byte order integer, recording where the
48 + object is stored in the packfile as the offset from the
49 + beginning.
50 +
51 + 20-byte object name.
52 +
53 + Observation: we would definitely need to extend this to
54 + 8-byte integer plus 20-byte object name to handle a packfile
55 + that is larger than 4GB.
56 +
57 + - The file is concluded with a trailer:
58 +
59 + A copy of the 20-byte SHA1 checksum at the end of
60 + corresponding packfile.
61 +
62 + 20-byte SHA1-checksum of all of the above.
63 +
64 +Pack Idx file:
65 +
66 + idx
67 + +--------------------------------+
68 + | fanout[0] = 2 |-.
69 + +--------------------------------+ |
70 + | fanout[1] | |
71 + +--------------------------------+ |
72 + | fanout[2] | |
73 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
74 + | fanout[255] | |
75 + +--------------------------------+ |
76 +main | offset | |
77 +index | object name 00XXXXXXXXXXXXXXXX | |
78 +table +--------------------------------+ |
79 + | offset | |
80 + | object name 00XXXXXXXXXXXXXXXX | |
81 + +--------------------------------+ |
82 + .-| offset |<+
83 + | | object name 01XXXXXXXXXXXXXXXX |
84 + | +--------------------------------+
85 + | | offset |
86 + | | object name 01XXXXXXXXXXXXXXXX |
87 + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88 + | | offset |
89 + | | object name FFXXXXXXXXXXXXXXXX |
90 + | +--------------------------------+
91 +trailer | | packfile checksum |
92 + | +--------------------------------+
93 + | | idxfile checksum |
94 + | +--------------------------------+
95 + .-------.
96 + |
97 +Pack file entry: <+
98 +
99 + packed object header:
100 + 1-byte type (upper 4-bit)
101 + size0 (lower 4-bit)
102 + n-byte sizeN (as long as MSB is set, each 7-bit)
103 + size0..sizeN form 4+7+7+..+7 bit integer, size0
104 + is the most significant part.
105 + packed object data:
106 + If it is not DELTA, then deflated bytes (the size above
107 + is the size before compression).
108 + If it is DELTA, then
109 + 20-byte base object name SHA1 (the size above is the
110 + size of the delta data that follows).
111 + delta data, deflated.