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

[Junio C Hamano <gitster@pobox.com>]

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

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

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