Skip to content

Documentation/gitformat-pack.txt: correct a few issues/typos

Taylor Blau git 2 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest2 patches 1 replyIn review
  2. v12 patches 3 repliesSuperseded

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/2Documentation/gitformat-pack.txt: fix typoDocumentation/gitformat-pack.txt+1 -10 replies
2/2Documentation/gitformat-pack.txt: fix incorrect MIDX documentationDocumentation/gitformat-pack.txt+5 -41 reply

Reviews trailers per patch

None of the 2 patches has a Reviewed-by or Acked-by.

PatchJunio C Hamano
1/2
2/2Helped-by

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v2 thread

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

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 protected]>

## 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

Signature · 1 line
2.42.0.527.ge89c67d052