Re: [PATCH 5/9] docs: add documentation for loose objects

From: Patrick Steinhardt <ps@pks.im>
Date: Sep 24, 2025, 07:55 UTC
Message-ID: <aNOkBuigxCODIcVN@pks.im>
In-Reply-To: <20250919010911.649831-6-sandals@crustytoothpaste.net>

On Fri, Sep 19, 2025 at 01:09:07AM +0000, brian m. carlson wrote:

> 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

Nit: s/its/it is/

Show 5 quoted lines

> 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

Do we maybe want to call this "gitformat-loose-objects(5)"? "loose" feels rather generic.

> @@ -0,0 +1,49 @@
> +gitformat-loose(5)
> +==================

Makes me wonder whether we should also have gitformat-reffiles(5) and gitformat-reftables(5). Obviously nothing you have to do, but rather an action item for myself or others interested in the ref backends.

Show 11 quoted lines

> +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

It's a bit weird to list the mapping files here without explaining them. Should we maybe drop them for now and only add them once we also add a section explaining their format?

On the other hand, maybe it's better to list those files and not explain them compared to not mentioning them at all. Not quite sure.

Show 6 quoted lines

> +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.

I feel that "most of its primary repository data" is a bit misleading, as one can expect that most of the data should be in packfiles instead. How about the following instead:

    Loose objects are how Git stores individual objects, where every
    object is written as a separate file.

    Over the lifetime of a repository, new objects are typically written
    as loose objects initially. Eventually, these loose objects will be
    compacted into packfiles via repository maintenance to improve disk
    space usage and speed up the lookup of those objects.

Show 14 quoted lines

> +== Loose objects
> +
> +Each loose object contains a prefix, followed immediately by the data of the
> +object.  The prefix contains `<type> <size>\0`.  `<type>` 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.

Should we maybe give a hint why we have these sharding directories?

Patrick