Re: [PATCH] Update, and clear up the pack format documentation a bit

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

"Peter Eriksen" <s022018@student.dtu.dk> writes:

> The current documentation does not mention the ofs_delta pack
> object type. This patch is also supposed to make the text a bit
> more readable, since it moves the object entry header
> description earlier.
>
> I fixes one error in these lines:
>
>         If it is DELTA, then
>           20-byte base object name SHA1 (the size above is the
>                 size of the delta data that follows).
>
> The size given in the object header is actually the inflated size
> of the delta data that follows,...

Your understanding is correct.  Throughout the pack-objects program,
delta_size is always expressed in uncompressed number of bytes.  The
original description you quoted above does not even say "the size of the
delta data (compressed)", so in that sense I do not think the original
description is really an error; if the update makes the description
clearer that would be good.

>     - The header is followed by number of object entries, each of
>       which looks like this:
> +     
> +     An n-byte header encoding the
> +         type of the object

Hmm.

This is just terminology, but I think calling ref-delta and ofs-delta
"type of object", is confusing.  This "type" field is about object
representation in the pack.

There are "undeltified" representations (4 object types), "ref-delta" and
"ofs-delta" representations.

> +         length of the object before compression

And this is the length of the representation specific data.

 - for undeltified representations of the four object types, this
   size is the size of the _object_;

 - for deltified representations, this is _NOT_ the size of the _object_
   (i.e. final object data after applying the delta).  This is the size of
   the delta data to be applied to the delta base, and does not include
   the base object name (for ref-delta) nor size to represent the offset
   (for ofs-delta).
> +          
> +     The format of the header:
> +	1-byte size extension bit (MSB)
> +	       type (next 3 bit)
> +	       size0 (lower 4-bit)
> +        n-byte sizeN (as long as MSB is set, each 7-bit)
> +		size0..sizeN form 4+7+7+..+7 bit integer, size0
> +		is the least significant part, and sizeN is the
> +		most significant part.
> +
>  
> +     The header is followed by:
> +
> +     (for object types: commit, tree, blob, and tag)
>       compressed data

Correct.

> +     (for object type ref_delta)
>       20-byte base object name
>       compressed delta data
> + 
> +     (for object type ofs_delta)
> +     n-byte offset (n*7-bit as above, but with size0 being 7 bit)     
> +     compressed delta data

Correct.