pack-format.txt: more details on pack file format
The current document mentions OBJ_* constants without their actual values. A git developer would know these are from cache.h but that's not very friendly to a person who wants to read this file to implement a pack file parser. Similarly, the deltified representation is not documented at all (the "document" is basically patch-delta.c). Translate that C code to English with a bit more about what ofs-delta and ref-delta mean. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Nguyễn Thái Ngọc Duy committed
May 11, 2018 at 08:55 UTC
011b648646fcf1f467336ac6bbf46145501c0f12
2 files changed
+97
Documentation/technical/pack-format.txt
+92
@@ -36,6 +36,98 @@ Git pack format
36
37
- The trailer records 20-byte SHA-1 checksum of all of the above.
38
39
+=== Object types
40
+
41
+Valid object types are:
42
+
43
+- OBJ_COMMIT (1)
44
+- OBJ_TREE (2)
45
+- OBJ_BLOB (3)
46
+- OBJ_TAG (4)
47
+- OBJ_OFS_DELTA (6)
48
+- OBJ_REF_DELTA (7)
49
+
50
+Type 5 is reserved for future expansion. Type 0 is invalid.
51
+
52
+=== Deltified representation
53
+
54
+Conceptually there are only four object types: commit, tree, tag and
55
+blob. However to save space, an object could be stored as a "delta" of
56
+another "base" object. These representations are assigned new types
57
+ofs-delta and ref-delta, which is only valid in a pack file.
58
+
59
+Both ofs-delta and ref-delta store the "delta" to be applied to
60
+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
63
+the offset of the base object in the pack instead.
64
+
65
+The base object could also be deltified if it's in the same pack.
66
+Ref-delta can also refer to an object outside the pack (i.e. the
67
+so-called "thin pack"). When stored on disk however, the pack should
68
+be self contained to avoid cyclic dependency.
69
+
70
+The delta data is a sequence of instructions to reconstruct an object
71
+from the base object. If the base object is deltified, it must be
72
+converted to canonical form first. Each instruction appends more and
73
+more data to the target object until it's complete. There are two
74
+supported instructions so far: one for copy a byte range from the
75
+source object and one for inserting new data embedded in the
76
+instruction itself.
77
+
78
+Each instruction has variable length. Instruction type is determined
79
+by the seventh bit of the first octet. The following diagrams follow
80
+the convention in RFC 1951 (Deflate compressed data format).
81
+
82
+==== Instruction to copy from base object
83
+
84
+ +----------+---------+---------+---------+---------+-------+-------+-------+
85
+ | 1xxxxxxx | offset1 | offset2 | offset3 | offset4 | size1 | size2 | size3 |
86
+ +----------+---------+---------+---------+---------+-------+-------+-------+
87
+
88
+This is the instruction format to copy a byte range from the source
89
+object. It encodes the offset to copy from and the number of bytes to
90
+copy. Offset and size are in little-endian order.
91
+
92
+All offset and size bytes are optional. This is to reduce the
93
+instruction size when encoding small offsets or sizes. The first seven
94
+bits in the first octet determines which of the next seven octets is
95
+present. If bit zero is set, offset1 is present. If bit one is set
96
+offset2 is present and so on.
97
+
98
+Note that a more compact instruction does not change offset and size
99
+encoding. For example, if only offset2 is omitted like below, offset3
100
+still contains bits 16-23. It does not become offset2 and contains
101
+bits 8-15 even if it's right next to offset1.
102
+
103
+ +----------+---------+---------+
104
+ | 10000101 | offset1 | offset3 |
105
+ +----------+---------+---------+
106
+
107
+In its most compact form, this instruction only takes up one byte
108
+(0x80) with both offset and size omitted, which will have default
109
+values zero. There is another exception: size zero is automatically
110
+converted to 0x10000.
111
+
112
+==== Instruction to add new data
113
+
114
+ +----------+============+
115
+ | 0xxxxxxx | data |
116
+ +----------+============+
117
+
118
+This is the instruction to construct target object without the base
119
+object. The following data is appended to the target object. The first
120
+seven bits of the first octet determines the size of data in
121
+bytes. The size must be non-zero.
122
+
123
+==== Reserved instruction
124
+
125
+ +----------+============
126
+ | 00000000 |
127
+ +----------+============
128
+
129
+This is the instruction reserved for future expansion.
130
+
131
== Original (version 1) pack-*.idx files have the following format:
132
133
- The header consists of 256 4-byte network byte order
cache.h
+5
@@ -373,6 +373,11 @@ extern void free_name_hash(struct index_state *istate);
373
#define read_blob_data_from_cache(path, sz) read_blob_data_from_index(&the_index, (path), (sz))
374
#endif
375
376
+/*
377
+ * Values in this enum (except those outside the 3 bit range) are part
378
+ * of pack file format. See Documentation/technical/pack-format.txt
379
+ * for more information.
380
+ */
381
enum object_type {
382
OBJ_BAD = -1,
383
OBJ_NONE = 0,