| Message ID | cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | git doc + "git help": move "format" docs from technical/* | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > This series improves the discoverability of the technical/* > documentation covering those "formats" where we interact with users > (e.g. "gitattributes") by moving them to its own "git help" category. > > It then moves various technical documentation from technical/* to our > main documentation namespace, allowing us to cross-link e.g. from > "git-bundle(1)" to a new "gitformat-bundle(5)". This may be a good direction to go in in the longer term, but there are already topics in flight that change these documents. Luckily none in 'next' yet, but there are two that have been in 'seen' and need to coordinate with this change.
On Mon, Jul 18 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > >> This series improves the discoverability of the technical/* >> documentation covering those "formats" where we interact with users >> (e.g. "gitattributes") by moving them to its own "git help" category. >> >> It then moves various technical documentation from technical/* to our >> main documentation namespace, allowing us to cross-link e.g. from >> "git-bundle(1)" to a new "gitformat-bundle(5)". > > This may be a good direction to go in in the longer term, but there > are already topics in flight that change these documents. Luckily > none in 'next' yet, but there are two that have been in 'seen' and > need to coordinate with this change. The v4 merges cleanly for me, unless there's a semantic conflict you've spotted that I've missed. But I assume you mean a "seen" you haven't pushed out yet, which includes SZEDER's change here: https://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/ I sent out the v3 with a merge resolution for the only conflict at the time: https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/ But as noted in the v4 CL I thought I'd make even that trivial conflict go away in v4, but it looks like I'll need to roll a v5. I don't want to make it a hassle for you to carry this topic, and I have waited a few months to submit this, as there were always various Documentation/technical/ changes in-flight. Would you prefer to have this entirely conflict free, or to have me solve the (small) conflicts locally and note the resolution (per --remerge-diff) in the CLs?
On Mon, Jul 18 2022, Ævar Arnfjörð Bjarmason wrote: > On Mon, Jul 18 2022, Junio C Hamano wrote: > >> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> >>> This series improves the discoverability of the technical/* >>> documentation covering those "formats" where we interact with users >>> (e.g. "gitattributes") by moving them to its own "git help" category. >>> >>> It then moves various technical documentation from technical/* to our >>> main documentation namespace, allowing us to cross-link e.g. from >>> "git-bundle(1)" to a new "gitformat-bundle(5)". >> >> This may be a good direction to go in in the longer term, but there >> are already topics in flight that change these documents. Luckily >> none in 'next' yet, but there are two that have been in 'seen' and >> need to coordinate with this change. > > The v4 merges cleanly for me, unless there's a semantic conflict you've > spotted that I've missed. > > But I assume you mean a "seen" you haven't pushed out yet, which > includes SZEDER's change here: > https://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/ > > I sent out the v3 with a merge resolution for the only conflict at the > time: > https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/ > > But as noted in the v4 CL I thought I'd make even that trivial conflict > go away in v4, but it looks like I'll need to roll a v5. > > I don't want to make it a hassle for you to carry this topic, and I have > waited a few months to submit this, as there were always various > Documentation/technical/ changes in-flight. > > Would you prefer to have this entirely conflict free, or to have me > solve the (small) conflicts locally and note the resolution (per > --remerge-diff) in the CLs? FWIW this merges cleanly with "seen" due to the magic of "git merge", i.e. even with the rename we resolve the conflict with SZEDER's work smoothly. But there's other reasons to re-roll, just say'n for when you eventually (hopefully) pick up such a re-roll ...
This series improves the discoverability of the technical/* documentation covering those "formats" where we interact with users (e.g. "gitattributes") by moving them to its own "git help" category. It then moves various technical documentation from technical/* to our main documentation namespace, allowing us to cross-link e.g. from "git-bundle(1)" to a new "gitformat-bundle(5)". See the v3 CL[1] for more details. Changes since v3: * Made a condition that never happened but which -fanalyzer complained about a BUG() (required knowing about the nature of command-list.txt). * Ejected the conflict with ac/bitmap-lookup-table by punting on gitformat-pack-bitmap(5). We can migrate that later, but this way there's no conflicts with "seen". 1. https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/ Ævar Arnfjörð Bjarmason (8): help.c: BUG() out if "help --guides" can't remove "git" prefixes git docs: split "User-facing file formats" off from "Guides" git docs: create a "Git file formats and protocols" section docs: move commit-graph format docs to man section 5 docs: move protocol-related docs to man section 5 docs: move pack format docs to man section 5 docs: move http-protocol docs to man section 5 docs: move multi-pack-index docs to man section 5 Documentation/Makefile | 26 +++++----- Documentation/config/lsrefs.txt | 2 +- Documentation/config/pack.txt | 2 +- Documentation/config/protocol.txt | 2 +- Documentation/git-bundle.txt | 11 +++-- Documentation/git-commit-graph.txt | 5 ++ Documentation/git-help.txt | 14 ++++-- Documentation/git-multi-pack-index.txt | 7 +-- Documentation/git-upload-pack.txt | 7 ++- Documentation/git.txt | 15 ++++++ ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++--- .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++-- ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------ .../index-format.txt => gitformat-index.txt} | 22 ++++++++- ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++- ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++- ...otocol.txt => gitformat-pack-protocol.txt} | 26 ++++++++-- .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++-- ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++--- ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++- ...otocol.txt => gitformat-protocol-http.txt} | 35 ++++++++++--- ...tocol-v2.txt => gitformat-protocol-v2.txt} | 26 ++++++++-- ...ure-format.txt => gitformat-signature.txt} | 21 ++++++-- .../howto/recover-corrupted-object-harder.txt | 2 +- Documentation/lint-man-section-order.perl | 3 ++ Documentation/technical/api-simple-ipc.txt | 2 +- .../technical/hash-function-transition.txt | 2 +- .../long-running-process-protocol.txt | 2 +- Documentation/technical/partial-clone.txt | 2 +- Documentation/user-manual.txt | 2 +- Makefile | 1 + builtin/help.c | 18 ++++++- cache.h | 3 +- command-list.txt | 33 ++++++++++--- help.c | 32 +++++++++++- help.h | 2 + pack-revindex.h | 2 +- t/t0012-help.sh | 14 +++++- t/t5551-http-fetch-smart.sh | 4 +- 39 files changed, 482 insertions(+), 115 deletions(-) rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%) rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%) rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%) rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%) rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%) rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%) rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%) rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%) rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%) rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%) rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (97%) rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (97%) rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%) Range-diff against v3: -: ----------- > 1: 4428f0a6fb1 help.c: BUG() out if "help --guides" can't remove "git" prefixes 1: 929d9192828 ! 2: 883c483d4e7 git docs: split "User-facing file formats" off from "Guides" @@ help.c: static struct category_description main_categories[] = { }; @@ help.c: static const char *drop_prefix(const char *name, uint32_t category) - - if (skip_prefix(name, "git-", &new_name)) - return new_name; -- if (category == CAT_guide && skip_prefix(name, "git", &new_name)) -+ switch (category) { -+ case CAT_guide: + switch (category) + { + case CAT_guide: + case CAT_userformats: -+ skip_prefix(name, "git", &new_name); + if (!skip_prefix(name, "git", &new_name)) + BUG("category #%d but no 'git' prefix?", category); return new_name; -+ } - return name; - - } @@ help.c: void list_guides_help(void) putchar('\n'); } 2: 1fd57d5caf4 ! 3: d196bcd1db0 git docs: create a "Git file formats and protocols" section @@ help.c: static struct category_description main_categories[] = { }; @@ help.c: static const char *drop_prefix(const char *name, uint32_t category) - switch (category) { + { case CAT_guide: case CAT_userformats: + case CAT_gitformats: - skip_prefix(name, "git", &new_name); + if (!skip_prefix(name, "git", &new_name)) + BUG("category #%d but no 'git' prefix?", category); return new_name; - } @@ help.c: void list_user_formats_help(void) putchar('\n'); } 3: d548c6aaba7 = 4: b59e001a4ca docs: move commit-graph format docs to man section 5 4: f404987f94d = 5: 968aa977b67 docs: move protocol-related docs to man section 5 5: 6c46b4dccea ! 6: 858ce9c6999 docs: move pack format docs to man section 5 @@ Commit message gitformat-commit-graph do to a gitformat-chunk-format manpage we build by default. + Creating a "gitformat-pack-bitmap" from + "Documentation/technical/bitmap-format" might logically be part of + this change, but it's left out for now due to a conflict with the + in-flight ac/bitmap-lookup-table series. + Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> ## Documentation/Makefile ## @@ Documentation/Makefile: MAN1_TXT += gitweb.txt +MAN5_TXT += gitformat-chunk.txt MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-index.txt -+MAN5_TXT += gitformat-pack-bitmap.txt +MAN5_TXT += gitformat-pack-cruft.txt MAN5_TXT += gitformat-pack-protocol.txt +MAN5_TXT += gitformat-pack.txt @@ Documentation/Makefile: MAN1_TXT += gitweb.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt -@@ Documentation/Makefile: TECH_DOCS += MyFirstContribution - TECH_DOCS += MyFirstObjectWalk +@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit --TECH_DOCS += technical/bitmap-format + TECH_DOCS += technical/bitmap-format -TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol @@ Documentation/gitformat-index.txt: The remaining data of each directory block is + +GIT +--- -+Part of the linkgit:git[1] suite - - ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-pack-bitmap.txt ## -@@ --GIT bitmap v1 format --==================== -+gitformat-pack-bitmap(5) -+======================== - --== Pack and multi-pack bitmaps -+NAME -+---- -+gitformat-pack-bitmap - The bitmap file format -+ -+SYNOPSIS -+-------- -+[verse] -+$GIT_DIR/objects/pack/pack-*.bitmap -+ -+DESCRIPTION -+----------- -+ -+Bitmaps are a file format associated with .pack files. See -+the pack format documentation in linkgit:gitformat-pack[5] and -+linkgit:git-pack-objects[1]. -+ -+== GIT bitmap v1 format -+ -+=== Pack and multi-pack bitmaps - - Bitmaps store reachability information about the set of objects in a packfile, - or a multi-pack index (MIDX). The former is defined obviously, and the latter is -@@ Documentation/gitformat-pack-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are - required for bitmaps corresponding to packfiles. For bitmaps that correspond to - MIDXs, both the bit-cache and rev-cache extensions are required. - --== On-disk format -+=== On-disk format - - * A header appears at the beginning: - -@@ Documentation/gitformat-pack-bitmap.txt: in the index. - TRAILER: :: - Trailing checksum of the preceding contents. - --== Appendix A: Serialization format for an EWAH bitmap -+Appendix A - Serialization format for an EWAH bitmap -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Ewah bitmaps are serialized in the same protocol as the JAVAEWAH - library, making them backwards compatible with the JGit -@@ Documentation/gitformat-pack-bitmap.txt: chunk. For efficient appending to the bitstream, the EWAH stores a - pointer to the last RLW in the stream. - - --== Appendix B: Optional Bitmap Sections -+Appendix B - Optional Bitmap Sections -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - These sections may or may not be present in the `.bitmap` file; their - presence is indicated by the header flags section described above. - - Name-hash cache ----------------- -+~~~~~~~~~~~~~~~ - - If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains - a cache of 32-bit values, one per object in the pack/MIDX. The value at -@@ Documentation/gitformat-pack-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag. - If implementations want to choose a different hashing scheme, they are - free to do so, but MUST allocate a new header flag (because comparing - hashes made under two different schemes would be pointless). -+ -+GIT -+--- +Part of the linkgit:git[1] suite ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ## @@ command-list.txt: gitdiffcore guide gitformat-commit-graph gitformats +gitformat-index gitformats +gitformat-pack gitformats -+gitformat-pack-bitmap gitformats +gitformat-pack-cruft gitformats gitformat-pack-protocol gitformats gitformat-protocol-capabilities gitformats 6: 5cf8b526bff ! 7: 499ee582644 docs: move http-protocol docs to man section 5 @@ Documentation/Makefile: MAN5_TXT += gitformat-pack-protocol.txt MAN5_TXT += gitformat-protocol-v2.txt MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk - TECH_DOCS += SubmittingPatches +@@ Documentation/Makefile: TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit + TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/http-protocol TECH_DOCS += technical/long-running-process-protocol 7: aabdc4a4151 ! 8: f186950e673 docs: move multi-pack-index docs to man section 5 @@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-multi-pack-index.txt - MAN5_TXT += gitformat-pack-bitmap.txt MAN5_TXT += gitformat-pack-cruft.txt MAN5_TXT += gitformat-pack-protocol.txt -@@ Documentation/Makefile: TECH_DOCS += SubmittingPatches - TECH_DOCS += ToolsForGit + MAN5_TXT += gitformat-pack.txt +@@ Documentation/Makefile: TECH_DOCS += ToolsForGit + TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/long-running-process-protocol -TECH_DOCS += technical/multi-pack-index @@ command-list.txt: gitformat-bundle gitformats gitformat-index gitformats +gitformat-multi-pack-index gitformats gitformat-pack gitformats - gitformat-pack-bitmap gitformats gitformat-pack-cruft gitformats + gitformat-pack-protocol gitformats