Merge branch 'po/rerere-doc-fmt'
[gitweb.git] / Documentation / technical / pack-format.txt
index 70a99fd1423894255f5e0e8cdbb345276620ffde..cab5bdd2ff0f887cb991e2dc9ba3cccec34f8a0a 100644 (file)
@@ -252,3 +252,80 @@ Pack file entry: <+
     corresponding packfile.
 
     20-byte SHA-1-checksum of all of the above.
+
+== multi-pack-index (MIDX) files have the following format:
+
+The multi-pack-index files refer to multiple pack-files and loose objects.
+
+In order to allow extensions that add extra data to the MIDX, we organize
+the body into "chunks" and provide a lookup table at the beginning of the
+body. The header includes certain length values, such as the number of packs,
+the number of base MIDX files, hash lengths and types.
+
+All 4-byte numbers are in network order.
+
+HEADER:
+
+       4-byte signature:
+           The signature is: {'M', 'I', 'D', 'X'}
+
+       1-byte version number:
+           Git only writes or recognizes version 1.
+
+       1-byte Object Id Version
+           Git only writes or recognizes version 1 (SHA1).
+
+       1-byte number of "chunks"
+
+       1-byte number of base multi-pack-index files:
+           This value is currently always zero.
+
+       4-byte number of pack files
+
+CHUNK LOOKUP:
+
+       (C + 1) * 12 bytes providing the chunk offsets:
+           First 4 bytes describe chunk id. Value 0 is a terminating label.
+           Other 8 bytes provide offset in current file for chunk to start.
+           (Chunks are provided in file-order, so you can infer the length
+           using the next chunk position if necessary.)
+
+       The remaining data in the body is described one chunk at a time, and
+       these chunks may be given in any order. Chunks are required unless
+       otherwise specified.
+
+CHUNK DATA:
+
+       Packfile Names (ID: {'P', 'N', 'A', 'M'})
+           Stores the packfile names as concatenated, null-terminated strings.
+           Packfiles must be listed in lexicographic order for fast lookups by
+           name. This is the only chunk not guaranteed to be a multiple of four
+           bytes in length, so should be the last chunk for alignment reasons.
+
+       OID Fanout (ID: {'O', 'I', 'D', 'F'})
+           The ith entry, F[i], stores the number of OIDs with first
+           byte at most i. Thus F[255] stores the total
+           number of objects.
+
+       OID Lookup (ID: {'O', 'I', 'D', 'L'})
+           The OIDs for all objects in the MIDX are stored in lexicographic
+           order in this chunk.
+
+       Object Offsets (ID: {'O', 'O', 'F', 'F'})
+           Stores two 4-byte values for every object.
+           1: The pack-int-id for the pack storing this object.
+           2: The offset within the pack.
+               If all offsets are less than 2^31, then the large offset chunk
+               will not exist and offsets are stored as in IDX v1.
+               If there is at least one offset value larger than 2^32-1, then
+               the large offset chunk must exist. If the large offset chunk
+               exists and the 31st bit is on, then removing that bit reveals
+               the row in the large offsets containing the 8-byte offset of
+               this object.
+
+       [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'})
+           8-byte offsets into large packfiles.
+
+TRAILER:
+
+       20-byte SHA1-checksum of the above contents.