pack-format.txt: document sizes at start of delta data
We document the delta data as a set of instructions, but forget to document the two sizes that precede those instructions: the size of the base object and the size of the object to be reconstructed. Fix this omission. Rather than cramming all the details about the encoding into the running text, introduce a separate section detailing our "size encoding" and refer to it. Reported-by: Ross Light <ross@zombiezen.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Martin Ågren committed
Dec 29, 2020 at 23:43 UTC
7b77f5a13effd01c40b3b354d93749ece79e0acc
1 file changed
+16
-1
Documentation/technical/pack-format.txt
+16
-1
@@ -55,6 +55,18 @@ Valid object types are:
55
56
Type 5 is reserved for future expansion. Type 0 is invalid.
57
58
+=== Size encoding
59
+
60
+This document uses the following "size encoding" of non-negative
61
+integers: From each byte, the seven least significant bits are
62
+used to form the resulting integer. As long as the most significant
63
+bit is 1, this process continues; the byte with MSB 0 provides the
64
+last seven bits. The seven-bit chunks are concatenated. Later
65
+values are more significant.
66
+
67
+This size encoding should not be confused with the "offset encoding",
68
+which is also used in this document.
69
+
70
=== Deltified representation
71
72
Conceptually there are only four object types: commit, tree, tag and
@@ -73,7 +85,10 @@ Ref-delta can also refer to an object outside the pack (i.e. the
85
so-called "thin pack"). When stored on disk however, the pack should
86
be self contained to avoid cyclic dependency.
87
76
-The delta data is a sequence of instructions to reconstruct an object
88
+The delta data starts with the size of the base object and the
89
+size of the object to be reconstructed. These sizes are
90
+encoded using the size encoding from above. The remainder of
91
+the delta data is a sequence of instructions to reconstruct the object
92
from the base object. If the base object is deltified, it must be
93
converted to canonical form first. Each instruction appends more and
94
more data to the target object until it's complete. There are two