Re: [PATCH 4/9] docs: improve ambiguous areas of pack format documentation

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

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

Show 8 quoted lines

> +=== Object encoding
> +
> +Unlike loose objects, packed objects do not have a prefix containing the type,
> +size, and a NUL byte. These are not necessary because they can be determined by
> +the n-byte type and length that prefixes the data and so they are omitted from
> +the compressed and deltified data.
> +
> +The computation of the object ID still uses this prefix, however.

Not wrong per-se, but I've always viewd that the in-pack object header with n-byte type and length was an optimized representation that stands in for the textual type+size+NUL, just like the payload part also uses object representation different from that is used for loose objects for performance.

And when you view the in-pack object header that way, "are not necessary" and everything follows in the above appear to somewhat miss the point. It is not just "type size<NUL>" that is recreated on the fly for computation of the same object name as in the loose object form, but the payload also is recreated on the fly to match what loose object would have had, e.g., a deltified representation would be reconstituted into non-deltified form, etc.

IOW, I would have exprected the description to go more along this line intead.

    Packed objects use the n-byte type and length in-pack object
    header, with in-pack specific representation of the object data.
    In order to compute the same object name as if the object were
    loose, the object representation used in the loose object is
    virtually recreated by translating n-byte type and length to the
    textual type + size + NUL, concatenated with the undeltified and
    inflated object data and hashing the result.

Show 11 quoted lines

>  === Size encoding
>  
>  This document uses the following "size encoding" of non-negative
> @@ -92,6 +105,11 @@ values are more significant.
>  This size encoding should not be confused with the "offset encoding",
>  which is also used in this document.
>  
> +When encoding the size of an undeltified object in a pack, the size is that of
> +the uncompressed raw object. For deltified objects, it is the size of the
> +uncompressed delta.  The base object name or offset is not included in the size
> +computation.

This is an important point worth describing.  Very nice.

If we wanted to help the curious, we can say that these are used to both help us know beforehand how much memory to allocate, before we inflate and/or to run patch-delta on the payload.

Thanks.