There are some issues in the bitmap-format html page. For example, some nested lists are shown as top-level lists (e.g. [1]- Here BITMAP_OPT_FULL_DAG (0x1) and BITMAP_OPT_HASH_CACHE (0x4) are shown as top-level list). There is also a need of adding info about trailing checksum in the docs. Changes since v1: * a new commit addressing bitmap-format.txt html page generation is added * Remove extra indentation from the previous change * elaborate more about the trailing checksum (as suggested by Kaartic) initial version: * first commit fixes some formatting issues * information about trailing checksum in the bitmap file is added in the bitmap-format doc. [1] https://git-scm.com/docs/bitmap-format#_on_disk_format Abhradeep Chakraborty (3): bitmap-format.txt: feed the file to asciidoc to generate html bitmap-format.txt: fix some formatting issues bitmap-format.txt: add information for trailing checksum Documentation/Makefile | 1 + Documentation/technical/bitmap-format.txt | 24 +++++++++++------------ 2 files changed, 12 insertions(+), 13 deletions(-) base-commit: 2668e3608e47494f2f10ef2b6e69f08a84816bcb Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1246%2FAbhra303%2Ffix-doc-formatting-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1246/Abhra303/fix-doc-formatting-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1246 Range-diff vs v1: -: ----------- > 1: a1b9bd9af90 bitmap-format.txt: feed the file to asciidoc to generate html 1: 976361e624a ! 2: cb919513c14 bitmap-format.txt: fix some formatting issues @@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cac - The following flags are supported: - -- - BITMAP_OPT_FULL_DAG (0x1) REQUIRED -- This flag must always be present. It implies that the -- bitmap index has been generated for a packfile or -- multi-pack index (MIDX) with full closure (i.e. where -- every single object in the packfile/MIDX can find its -- parent links inside the same packfile/MIDX). This is a -- requirement for the bitmap index format, also present in -- JGit, that greatly reduces the complexity of the -- implementation. + - BITMAP_OPT_FULL_DAG (0x1) REQUIRED + This flag must always be present. It implies that the + bitmap index has been generated for a packfile or +@@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cache extensions are required. + requirement for the bitmap index format, also present in + JGit, that greatly reduces the complexity of the + implementation. - -- - BITMAP_OPT_HASH_CACHE (0x4) -- If present, the end of the bitmap file contains -- `N` 32-bit name-hash values, one per object in the -- pack/MIDX. The format and meaning of the name-hash is -- described below. -+ - BITMAP_OPT_FULL_DAG (0x1) REQUIRED -+ This flag must always be present. It implies that the -+ bitmap index has been generated for a packfile or -+ multi-pack index (MIDX) with full closure (i.e. where -+ every single object in the packfile/MIDX can find its -+ parent links inside the same packfile/MIDX). This is a -+ requirement for the bitmap index format, also present in -+ JGit, that greatly reduces the complexity of the -+ implementation. -+ - BITMAP_OPT_HASH_CACHE (0x4) -+ If present, the end of the bitmap file contains -+ `N` 32-bit name-hash values, one per object in the -+ pack/MIDX. The format and meaning of the name-hash is -+ described below. + - BITMAP_OPT_HASH_CACHE (0x4) + If present, the end of the bitmap file contains + `N` 32-bit name-hash values, one per object in the +@@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cache extensions are required. + described below. 4-byte entry count (network byte order) - @@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cac Each entry contains the following: - - 4-byte object position (network byte order) -- The position **in the index for the packfile or -- multi-pack index** where the bitmap for this commit is -- found. -- ++ ** 4-byte object position (network byte order) + The position **in the index for the packfile or + multi-pack index** where the bitmap for this commit is + found. + - - 1-byte XOR-offset -- The xor offset used to compress this bitmap. For an entry -- in position `x`, a XOR offset of `y` means that the actual -- bitmap representing this commit is composed by XORing the -- bitmap for this entry with the bitmap in entry `x-y` (i.e. -- the bitmap `y` entries before this one). -- -- Note that this compression can be recursive. In order to -- XOR this entry with a previous one, the previous entry needs -- to be decompressed first, and so on. -- -- The hard-limit for this offset is 160 (an entry can only be -- xor'ed against one of the 160 entries preceding it). This -- number is always positive, and hence entries are always xor'ed -- with **previous** bitmaps, not bitmaps that will come afterwards -- in the index. -- ++ ** 1-byte XOR-offset + The xor offset used to compress this bitmap. For an entry + in position `x`, a XOR offset of `y` means that the actual + bitmap representing this commit is composed by XORing the +@@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cache extensions are required. + with **previous** bitmaps, not bitmaps that will come afterwards + in the index. + - - 1-byte flags for this bitmap -- At the moment the only available flag is `0x1`, which hints -- that this bitmap can be re-used when rebuilding bitmap indexes -- for the repository. -- ++ ** 1-byte flags for this bitmap + At the moment the only available flag is `0x1`, which hints + that this bitmap can be re-used when rebuilding bitmap indexes + for the repository. + - - The compressed bitmap itself, see Appendix A. -+ ** 4-byte object position (network byte order) -+ The position **in the index for the packfile or -+ multi-pack index** where the bitmap for this commit is -+ found. -+ -+ ** 1-byte XOR-offset -+ The xor offset used to compress this bitmap. For an entry -+ in position `x`, a XOR offset of `y` means that the actual -+ bitmap representing this commit is composed by XORing the -+ bitmap for this entry with the bitmap in entry `x-y` (i.e. -+ the bitmap `y` entries before this one). -+ -+ Note that this compression can be recursive. In order to -+ XOR this entry with a previous one, the previous entry needs -+ to be decompressed first, and so on. -+ -+ The hard-limit for this offset is 160 (an entry can only be -+ xor'ed against one of the 160 entries preceding it). This -+ number is always positive, and hence entries are always xor'ed -+ with **previous** bitmaps, not bitmaps that will come afterwards -+ in the index. -+ -+ ** 1-byte flags for this bitmap -+ At the moment the only available flag is `0x1`, which hints -+ that this bitmap can be re-used when rebuilding bitmap indexes -+ for the repository. -+ -+ ** The compressed bitmap itself, see Appendix A. ++ ** The compressed bitmap itself, see Appendix A. == Appendix A: Serialization format for an EWAH bitmap 2: ba534b5d486 ! 3: 2171d31fb2b bitmap-format.txt: add information for trailing checksum @@ Commit message ## Documentation/technical/bitmap-format.txt ## @@ Documentation/technical/bitmap-format.txt: MIDXs, both the bit-cache and rev-cache extensions are required. - ** The compressed bitmap itself, see Appendix A. + ** The compressed bitmap itself, see Appendix A. + * TRAILER: + -+ Index checksum of the above contents. ++ Index checksum of the above contents. It is a 20-byte SHA1 checksum. + == Appendix A: Serialization format for an EWAH bitmap -- gitgitgadget
