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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 19, 2025, 23:16 UTC
Message-ID: <xmqqms6qyqw9.fsf@gitster.g>
In-Reply-To: <20250919010911.649831-6-sandals@crustytoothpaste.net>

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Show 35 quoted lines

> 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 <sandals@crustytoothpaste.net>
> ---
>  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.

"most of" is a bit misleading, I would think. Those who start (what eventuall becomes) a large project from scratch are only minority of the users, and all others start with "git clone" from elsewhere, and in the resulting repository, Git initially stores most of its data in a packfile (or two).

I think it may become a bit clearer if we drop "initially", and end the sentence with "data that are created locally", perhaps?

> +Over the lifetime of a repository, objects are usually written as loose objects
> +initially and then converted into packs.

This one is good.

Show 9 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 glossary calls this "object name", not "ID".

> +the SHA-1 or SHA-256 (as appropriate) hash of the uncompressed data.

We should clarify "data" in uncompressed "data", as we earlier said "prefix and data concatenated", it can be misread as the payload alone. You have "The entire contents" that stands for "prefix and data concatenated" above, so "has of the entire contents" may work.

Also "uncompressed <whatever you rewrite 'data' with>" at the end of this sentence should be followed by "in hexadecimal". The "first two hex characters are used for fan-out" etc., depends on that you do not use binary result of the hash as the object name.

Thanks.