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

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

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

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

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