From: brian m. carlson Date: Fri, 19 Sep 2025 01:09:07 GMT Subject: [PATCH 5/9] docs: add documentation for loose objects Message-ID: <20250919010911.649831-6-sandals@crustytoothpaste.net> In-Reply-To: <20250919010911.649831-1-sandals@crustytoothpaste.net> We currently have no documentation for how loose objects are stored. Let's add some here so its easy for people to understand how they work. Signed-off-by: brian m. carlson --- Documentation/gitformat-loose.adoc | 49 ++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 Documentation/gitformat-loose.adoc diff --git a/Documentation/gitformat-loose.adoc b/Documentation/gitformat-loose.adoc new file mode 100644 index 0000000000..c8bef606fb --- /dev/null +++ b/Documentation/gitformat-loose.adoc @@ -0,0 +1,49 @@ +gitformat-loose(5) +================== + +NAME +---- +gitformat-loose - Git loose object format + + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/[0-9a-f][0-9a-f]/* +$GIT_DIR/objects/loose-object-idx +$GIT_DIR/objects/loose-map/map-*.map + +DESCRIPTION +----------- + +Loose objects are how Git initially stores most of its primary repository data. +Over the lifetime of a repository, objects are usually written as loose objects +initially and then converted into packs. + +== Loose objects + +Each loose object contains a prefix, followed immediately by the data of the +object. The prefix contains ` \0`. `` is one of `blob`, +`tree`, `commit`, or `tag` and `size` is the size of the data (without the +prefix) as a decimal integer expressed in ASCII. + +The entire contents, prefix and data concatenated, is then compressed with zlib +and the compressed data is stored in the file. The object ID of the object is +the SHA-1 or SHA-256 (as appropriate) hash of the uncompressed data. + +The file for the loose object is stored under the `objects` directory, with the +first two hex characters of the object ID being the directory and the remaining +characters being the file name. + +As an example, the empty tree contains the data (when uncompressed) `tree 0\0` +and, in a SHA-256 repository, would have the object ID +`6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321` and would be +stored under +`$GIT_DIR/objects/6e/f19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321`. + +Similarly, a blob containing the contents `abc` would have the uncompressed +data of `blob 3\0abc`. + +GIT +--- +Part of the linkgit:git[1] suite