Subject: [PATCH v2 0/2] Documentation/gitformat-pack.txt: correct a few issues/typos

From: Taylor Blau <[email-masked]>
Date: Tue, 31 Oct 2023 15:24:05 -0400

A minor reroll to adjust the text of the second patch to read more
clearly, thanks to input from Junio.

This has been rebased onto 692be87cbb (Merge branch
'jm/bisect-run-synopsis-fix', 2023-10-31). Thanks in advance for your
review!

Taylor Blau (2):
  Documentation/gitformat-pack.txt: fix typo
  Documentation/gitformat-pack.txt: fix incorrect MIDX documentation

 Documentation/gitformat-pack.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Range-diff against v1:
1:  8c5fa1ff4f = 1:  92e9bee4ad Documentation/gitformat-pack.txt: fix typo
2:  af2742e05d ! 2:  c149be35a1 Documentation/gitformat-pack.txt: fix incorrect MIDX documentation
    @@ Metadata
      ## Commit message ##
         Documentation/gitformat-pack.txt: fix incorrect MIDX documentation
     
    -    Back in 32f3c541e3 (multi-pack-index: write pack names in chunk, 2018-07-12)
    -    the MIDX's "Packfile Names" (or "PNAM", for short) chunk was described
    -    as containing an array of string entries. e0d1bcf825 notes that this is
    -    the only chunk in the MIDX format's specification that is not guaranteed
    -    to be 4-byte aligned, and so should be placed last.
    +    Back in 32f3c541e3 (multi-pack-index: write pack names in chunk,
    +    2018-07-12) the MIDX's "Packfile Names" (or "PNAM", for short) chunk was
    +    described as containing an array of string entries. e0d1bcf825 notes
    +    that this is the only chunk in the MIDX format's specification that is
    +    not guaranteed to be 4-byte aligned, and so should be placed last.
     
         This isn't quite accurate: the entries within the PNAM chunk are not
    -    guaranteed to be aligned since they are arbitrary strings, but the
    -    chunk itself is aligned since the ending is padded with NUL bytes.
    +    guaranteed to be 4-byte aligned since they are arbitrary strings, but
    +    the chunk itself is 4-byte aligned since the ending is padded with NUL
    +    bytes.
     
    -    That external padding has always been there since 32f3c541e3 via
    +    That padding has always been there since 32f3c541e3 via
         midx.c::write_midx_pack_names(), which ended with:
     
             i = MIDX_CHUNK_ALIGNMENT - (written % MIDX_CHUNK_ALIGNMENT)
    @@ Commit message
         So these have always been externally aligned. Correct the corresponding
         part of our documentation to reflect that.
     
    +    Helped-by: Junio C Hamano <[email-masked]>
         Signed-off-by: Taylor Blau <[email-masked]>
     
      ## Documentation/gitformat-pack.txt ##
    -@@ Documentation/gitformat-pack.txt: CHUNK DATA:
    +@@ Documentation/gitformat-pack.txt: CHUNK LOOKUP:
    + 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
    +-	    Stores the packfile names as concatenated, NUL-terminated strings.
    +-	    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.
    ++	    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 between 0 and 3 NUL bytes to make the
    ++	    chunk size a multiple of 4 bytes.
      
      	OID Fanout (ID: {'O', 'I', 'D', 'F'})
      	    The ith entry, F[i], stores the number of OIDs with first

base-commit: 692be87cbba55e8488f805d236f2ad50483bd7d5
-- 
2.42.0.527.ge89c67d052