@leroysheep / BookAlchemy
Code Commits Pulls CI/CD 81,972
jch
bisect jch maint master next seen test todo
adoc 131 lines 5.41 KB
Raw
1 gitformat-loose(5)
2 ==================
3
4 NAME
5 ----
6 gitformat-loose - Git loose object format
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 $GIT_DIR/objects/[0-9a-f][0-9a-f]/*
13 $GIT_DIR/objects/object-map/map-*.map
14
15 DESCRIPTION
16 -----------
17
18 Loose objects are how Git stores individual objects, where every object is
19 written as a separate file.
20
21 Over the lifetime of a repository, objects are usually written as loose objects
22 initially. Eventually, these loose objects will be compacted into packfiles
23 via repository maintenance to improve disk space usage and speed up the lookup
24 of these objects.
25
26 == Loose objects
27
28 Each loose object contains a prefix, followed immediately by the data of the
29 object. The prefix contains `<type> <size>\0`. `<type>` is one of `blob`,
30 `tree`, `commit`, or `tag` and `size` is the size of the data (without the
31 prefix) as a decimal integer expressed in ASCII.
32
33 The entire contents, prefix and data concatenated, is then compressed with zlib
34 and the compressed data is stored in the file. The object ID of the object is
35 the SHA-1 or SHA-256 (as appropriate) hash of the uncompressed data.
36
37 The file for the loose object is stored under the `objects` directory, with the
38 first two hex characters of the object ID being the directory and the remaining
39 characters being the file name. This is done to shard the data and avoid too
40 many files being in one directory, since some file systems perform poorly with
41 many items in a directory.
42
43 As an example, the empty tree contains the data (when uncompressed) `tree 0\0`
44 and, in a SHA-256 repository, would have the object ID
45 `6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321` and would be
46 stored under
47 `$GIT_DIR/objects/6e/f19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321`.
48
49 Similarly, a blob containing the contents `abc` would have the uncompressed
50 data of `blob 3\0abc`.
51
52 == Loose object mapping
53
54 When the `compatObjectFormat` option is used, Git needs to store a mapping
55 between the repository's main algorithm and the compatibility algorithm for
56 loose objects as well as some auxiliary information.
57
58 The mapping consists of a set of files under `$GIT_DIR/objects/object-map`
59 ending in `.map`. The portion of the filename before the extension is that of
60 the main hash checksum (that is, the one specified in
61 `extensions.objectformat`) in hex format.
62
63 `git gc` will repack existing entries into one file, removing any unnecessary
64 objects, such as obsolete shallow entries or loose objects that have been
65 packed.
66
67 The file format is as follows. All values are in network byte order and all
68 4-byte and 8-byte values must be 4-byte aligned in the file, so the NUL padding
69 may be required in some cases. Git always uses the smallest number of NUL
70 bytes (including zero) that is required for the padding in order to make
71 writing files deterministic.
72
73 - A header appears at the beginning and consists of the following:
74 * A 4-byte mapping signature: `LMAP`
75 * 4-byte version number: 1
76 * 4-byte length of the header section (including reserved entries but
77 excluding any NUL padding).
78 * 4-byte number of objects declared in this map file.
79 * 4-byte number of object formats declared in this map file.
80 * For each object format:
81 ** 4-byte format identifier (e.g., `sha1` for SHA-1)
82 ** 4-byte length in bytes of shortened object names (that is, prefixes of
83 the full object names). This is the shortest possible length needed to
84 make names in the shortened object name table unambiguous.
85 ** 8-byte integer, recording where tables relating to this format
86 are stored in this index file, as an offset from the beginning.
87 * 8-byte offset to the trailer from the beginning of this file.
88 * The remainder of the header section is reserved for future use.
89 Readers must ignore unrecognized data here.
90 - Zero or more NUL bytes. These are used to improve the alignment of the
91 4-byte quantities below.
92 - Tables for the first object format:
93 * A sorted table of shortened object names. These are prefixes of the names
94 of all objects in this file, packed together to reduce the cache footprint
95 of the binary search for a specific object name.
96 * A sorted table of full object names.
97 * A table of 4-byte metadata values.
98 - Zero or more NUL bytes.
99 - Tables for subsequent object formats:
100 * A sorted table of shortened object names. These are prefixes of the names
101 of all objects in this file, packed together without offset values to
102 reduce the cache footprint of the binary search for a specific object name.
103 * A table of full object names in the order specified by the first object format.
104 * A table of 4-byte values mapping object name order to the order of the
105 first object format. For an object in the table of sorted shortened object
106 names, the value at the corresponding index in this table is the index in
107 the previous table for that same object.
108 * Zero or more NUL bytes.
109 - The trailer consists of the following:
110 * Hash checksum of all of the above using the main hash.
111
112 The lower six bits of each metadata table contain a type field indicating the
113 reason that this object is stored:
114
115 0::
116 Reserved.
117 1::
118 This object is stored as a loose object in the repository.
119 2::
120 This object is a shallow entry. The mapping refers to a shallow value
121 returned by a remote server.
122 3::
123 This object is a submodule entry. The mapping refers to the commit stored
124 representing a submodule.
125
126 Other data may be stored in this field in the future. Bits that are not used
127 must be zero.
128
129 GIT
130 ---
131 Part of the linkgit:git[1] suite