Re: [PATCH 2/2] Documentation/gitformat-pack.txt: fix incorrect MIDX documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 31, 2023, 00:42 UTC
Message-ID: <xmqq8r7j7hby.fsf@gitster.g>
In-Reply-To: <ZUAmWWh1WHujiN05@nand.local>

Taylor Blau <me@ttaylorr.com> writes:

Show 27 quoted lines

>> >  	    Packfiles must be listed in lexicographic order for fast lookups by
>> > -	    name. This is the only chunk not guaranteed to be a multiple of four
>> > -	    bytes in length, so should be the last chunk for alignment reasons.
>> > +	    name. Individual entries in this chunk are not guarenteed to be
>> > +	    aligned. The chunk is externally padded with zeros to align
>> > +	    remaining chunks.
>>
>> I am not sure what "externally padded" means.
>
> How about something like this, instead?
>
> --- 8< ---
> diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
> index 0bc80f0d46..229490f82f 100644
> --- a/Documentation/gitformat-pack.txt
> +++ b/Documentation/gitformat-pack.txt
> @@ -392,9 +392,10 @@ CHUNK DATA:
>  	Packfile Names (ID: {'P', 'N', 'A', 'M'})
>  	    Stores the packfile names as concatenated, NUL-terminated strings.
>  	    Packfiles must be listed in lexicographic order for fast lookups by
> -	    name. Individual entries in this chunk are not guarenteed to be
> -	    aligned. The chunk is externally padded with zeros to align
> -	    remaining chunks.
> +	    name. Individual entries in this chunk are not guaranteed to be
> +	    aligned, since the packfile names can be of arbitrary length. The
> +	    chunk itself is padded at the end with NUL bytes in order to align
> +	    the remaining chunks.

There is no alignment requirement described, so "not guaranteed" and "in order to align" sound hollow. These are always byte-aligned ;-)

How about something along this line to simplify it a bit?

	Store the names of packfiles as a sequence of NUL-terminated
	strings.  There is no extra padding between the filenames,
	and they are listed in lexicographic order.  The chunk
	itself is padded at the end with NUL bytes to make the chunk
	size a multiple of 4 bytes.

I did not ccheck if the chunks need to be 4-byte aligned, so if the number is wrong, please adjust accordingly.