See the v5 for a general overview: https://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@xxxxxxxxx/ Changes since v7: * Corrects the discussion of existing behavior in 1-2/12 (git-gitfoo v.s. git-foo). * Fixes a stray error in previous v7 rebasing in 6/12. * Splits out the "signature" and "index" format doc conversions into their own commits (previously part of the "pack" conversion). * The "gitformat-pack" now contains what was previously in "gitformat-cruft-pack", i.e. we discuss all of the pack files (*.pack, *.idx etc.) in the one file. (The *.bitmap bit is left out for now as before, due to in-flight conflicts) * Ejected the conversion of Documentation/technical/multi-pack-index.txt, we discuss the midx in the gitformat-pack already, that documentation is more in the "design notes" category. Perhaps we should have a gitdesign-* namespace for such things, but let's leave it aside for now. Ævar Arnfjörð Bjarmason (12): help.c: refactor drop_prefix() to use a "switch" statement" help.c: remove common category behavior from drop_prefix() behavior git help doc: use "<doc>" instead of "<guide>" git docs: add a category for user-facing file, repo and command UX git docs: add a category for file formats, protocols and interfaces docs: move commit-graph format docs to man section 5 docs: move protocol-related docs to man section 5 docs: move index format docs to man section 5 docs: move signature docs to man section 5 docs: move pack format docs to man section 5 docs: move cruft pack docs to gitformat-pack docs: move http-protocol docs to man section 5 Documentation/Makefile | 23 +-- Documentation/config/lsrefs.txt | 2 +- Documentation/config/pack.txt | 2 +- Documentation/config/protocol.txt | 2 +- Documentation/git-bundle.txt | 13 +- Documentation/git-commit-graph.txt | 5 + Documentation/git-help.txt | 27 ++- Documentation/git-multi-pack-index.txt | 4 +- Documentation/git-upload-pack.txt | 7 +- Documentation/git.txt | 17 ++ ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++- .../chunk-format.txt => gitformat-chunk.txt} | 29 +++- ...-format.txt => gitformat-commit-graph.txt} | 49 ++++-- .../index-format.txt => gitformat-index.txt} | 22 ++- .../pack-format.txt => gitformat-pack.txt} | 160 +++++++++++++++++- ...ure-format.txt => gitformat-signature.txt} | 21 ++- ...ities.txt => gitprotocol-capabilities.txt} | 28 ++- ...ocol-common.txt => gitprotocol-common.txt} | 23 ++- ...http-protocol.txt => gitprotocol-http.txt} | 35 +++- ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++- .../protocol-v2.txt => gitprotocol-v2.txt} | 27 ++- .../howto/recover-corrupted-object-harder.txt | 2 +- Documentation/lint-man-section-order.perl | 3 + Documentation/technical/api-simple-ipc.txt | 2 +- Documentation/technical/cruft-packs.txt | 123 -------------- .../technical/hash-function-transition.txt | 2 +- .../long-running-process-protocol.txt | 2 +- Documentation/technical/packfile-uri.txt | 2 +- Documentation/technical/partial-clone.txt | 2 +- Documentation/user-manual.txt | 2 +- Makefile | 1 + builtin/help.c | 20 ++- cache.h | 3 +- command-list.txt | 36 +++- help.c | 41 ++++- help.h | 2 + pack-revindex.h | 2 +- refspec.h | 2 +- t/t0012-help.sh | 14 +- t/t5551-http-fetch-smart.sh | 4 +- 40 files changed, 590 insertions(+), 243 deletions(-) rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%) rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%) 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/pack-format.txt => gitformat-pack.txt} (72%) rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%) rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%) rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%) rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%) rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%) rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%) delete mode 100644 Documentation/technical/cruft-packs.txt Range-diff against v7: 1: 2665148f45b ! 1: 8ae30ce2e80 help.c: refactor drop_prefix() to use a "switch" statement" @@ Commit message we'll return the stripped string. Then we'll strip "git" if the command is in "CAT_guide". - This means that we'd in principle strip "git-gitfoo" down to "foo" if + This means that we'd in principle strip "git-foo" down to "foo" if it's in CAT_guide. That doesn't make much sense, and we don't have such an entry in command-list.txt, but let's preserve that behavior for now. 2: 56429194634 ! 2: aebb56da6e9 help.c: remove common category behavior from drop_prefix() behavior @@ Commit message Before this we'd in principle strip a "git-" prefix from a "guide" in command-list.txt, in practice we have no such entry there. As we don't - have any entry that looks like "git-gitfoo" in command-list.txt this + have any entry that looks like "git-foo" in command-list.txt this changes nothing in practice, but it makes the intent of the code - clearer. + clearer. In that hypothetical case we'd now strip it down to "-foo", + not "foo". When this code was added in cfb22a02ab5 (help: use command-list.h for common command list, 2018-05-10) the only entries in command-list.txt 3: 2d6c00a51fa = 3: 6c3c072de6f git help doc: use "<doc>" instead of "<guide>" 4: 8e9384a92f2 = 4: d12db4a9540 git docs: add a category for user-facing file, repo and command UX 5: 4367c1e7f50 = 5: f76e775bfdd git docs: add a category for file formats, protocols and interfaces 6: 5adabbb3a26 ! 6: df3ef265d45 docs: move commit-graph format docs to man section 5 @@ command-list.txt: gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces -+gitformat-bundle developerinterfaces +gitformat-commit-graph developerinterfaces gitglossary guide githooks userinterfaces 7: cfd1b0afb53 ! 7: daafbf9ae90 docs: move protocol-related docs to man section 5 @@ Documentation/technical/partial-clone.txt: Design Details server to request filtering during packfile construction. ## command-list.txt ## -@@ command-list.txt: gitdiffcore guide - giteveryday guide - gitfaq guide - gitformat-bundle developerinterfaces --gitformat-bundle developerinterfaces - gitformat-commit-graph developerinterfaces - gitglossary guide - githooks userinterfaces @@ command-list.txt: gitk mainporcelain gitmailmap userinterfaces gitmodules userinterfaces 10: 8baf1db4d30 ! 8: ea98b37e41a docs: move multi-pack-index docs to man section 5 @@ Metadata Author: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> ## Commit message ## - docs: move multi-pack-index docs to man section 5 + docs: move index format docs to man section 5 Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving - the multi-pack-index documentation over. + the index format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> ## Documentation/Makefile ## -@@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt - MAN5_TXT += gitformat-chunk.txt +@@ Documentation/Makefile: MAN1_TXT += gitweb.txt + MAN5_TXT += gitattributes.txt + 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-cruft.txt - MAN5_TXT += gitformat-pack.txt - MAN5_TXT += gitformat-signature.txt -@@ Documentation/Makefile: TECH_DOCS += ToolsForGit - TECH_DOCS += technical/bitmap-format ++MAN5_TXT += gitformat-index.txt + MAN5_TXT += githooks.txt + MAN5_TXT += gitignore.txt + MAN5_TXT += gitmailmap.txt +@@ Documentation/Makefile: TECH_DOCS += technical/bitmap-format + TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition + TECH_DOCS += technical/http-protocol +-TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol --TECH_DOCS += technical/multi-pack-index - TECH_DOCS += technical/pack-heuristics - TECH_DOCS += technical/parallel-checkout - TECH_DOCS += technical/partial-clone + TECH_DOCS += technical/multi-pack-index + TECH_DOCS += technical/pack-format - ## Documentation/git-multi-pack-index.txt ## -@@ Documentation/git-multi-pack-index.txt: $ git multi-pack-index verify - - SEE ALSO - -------- --See link:technical/multi-pack-index.html[The Multi-Pack-Index Design --Document] and linkgit:gitformat-pack[5] for more information on the -+See linkgit:git-multi-pack-index[1] and -+linkgit:gitformat-multi-pack-index[5] for more information on the - multi-pack-index feature and its file format. - - - - ## Documentation/technical/multi-pack-index.txt => Documentation/gitformat-multi-pack-index.txt ## + ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ## @@ --Multi-Pack-Index (MIDX) Design Notes --==================================== -+gitformat-multi-pack-index(5) -+============================= ++gitformat-index(5) ++================== + +NAME +---- -+gitformat-multi-pack-index - The multi-pack-index file format ++gitformat-index - Git index format + +SYNOPSIS +-------- +[verse] -+$GIT_DIR/objects/pack/multi-pack-index ++$GIT_DIR/index + +DESCRIPTION +----------- ++ + Git index format +-================ - The Git object directory contains a 'pack' directory containing - packfiles (with suffix ".pack") and pack-indexes (with suffix -@@ Documentation/gitformat-multi-pack-index.txt: Related Links + == The Git index file has the following format - [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/ - Git Merge 2018 Contributor's summit notes (includes discussion of MIDX) +@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type: + with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, + tools should avoid interacting with a sparse index unless they understand + this extension. + +GIT +--- +Part of the linkgit:git[1] suite - ## Documentation/gitformat-pack.txt ## -@@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferred pack coming first). - The MIDX's reverse index is stored in the optional 'RIDX' chunk within - the MIDX itself. - -+SEE ALSO -+-------- -+ -+linkgit:gitformat-multi-pack-index[5] -+ - GIT - --- - Part of the linkgit:git[1] suite - ## command-list.txt ## -@@ command-list.txt: gitformat-bundle developerinterfaces - gitformat-chunk developerinterfaces +@@ command-list.txt: giteveryday guide + gitfaq guide + gitformat-bundle developerinterfaces gitformat-commit-graph developerinterfaces - gitformat-index developerinterfaces -+gitformat-multi-pack-index developerinterfaces - gitformat-pack developerinterfaces - gitformat-pack-cruft developerinterfaces - gitformat-signature developerinterfaces ++gitformat-index developerinterfaces + gitglossary guide + githooks userinterfaces + gitignore userinterfaces -: ----------- > 9: 42a4a3c3be8 docs: move signature docs to man section 5 8: 3505fa86039 ! 10: 576c1fef4b3 docs: move pack format docs to man section 5 @@ Commit message location. By moving these we can properly link from the newly created - gitformat-commit-graph do to a gitformat-chunk-format manpage we build - by default. + gitformat-commit-graph to a gitformat-chunk-format page. - 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. + Integrating "Documentation/technical/bitmap-format.txt" and + "Documentation/technical/cruft-packs.txt" might logically be part of + this change, but as those cover parts of the wider "pack + format" (including associated files) that's documented outside of + "Documentation/technical/pack-format.txt" let's leave those for now, + subsequent commit(s) will address those. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> @@ Documentation/Makefile: MAN1_TXT += gitweb.txt MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-chunk.txt MAN5_TXT += gitformat-commit-graph.txt -+MAN5_TXT += gitformat-index.txt -+MAN5_TXT += gitformat-pack-cruft.txt + MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-pack.txt -+MAN5_TXT += gitformat-signature.txt + MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt - MAN5_TXT += gitmailmap.txt -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk - TECH_DOCS += SubmittingPatches - TECH_DOCS += ToolsForGit - TECH_DOCS += technical/bitmap-format --TECH_DOCS += technical/cruft-packs - TECH_DOCS += technical/hash-function-transition +@@ Documentation/Makefile: TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol --TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index -TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone -@@ Documentation/Makefile: TECH_DOCS += technical/racy-git - TECH_DOCS += technical/reftable - TECH_DOCS += technical/send-pack-pipeline - TECH_DOCS += technical/shallow --TECH_DOCS += technical/signature-format - TECH_DOCS += technical/trivial-merge - SP_ARTICLES += $(TECH_DOCS) - SP_ARTICLES += technical/api-index ## Documentation/config/pack.txt ## @@ Documentation/config/pack.txt: permuted into their appropriate location when writing a new bitmap. @@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless - ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ## -@@ -+gitformat-index(5) -+================== -+ -+NAME -+---- -+gitformat-index - Git index format -+ -+SYNOPSIS -+-------- -+[verse] -+$GIT_DIR/index -+ -+DESCRIPTION -+----------- -+ - Git index format --================ - - == The Git index file has the following format - + ## Documentation/gitformat-index.txt ## @@ Documentation/gitformat-index.txt: Git index format entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the @@ Documentation/gitformat-index.txt: Git index format by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry. -@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type: - with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, - tools should avoid interacting with a sparse index unless they understand - this extension. -+ -+GIT -+--- -+Part of the linkgit:git[1] suite - - ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ## -@@ --= Cruft packs -+gitformat-pack-cruft(5) -+======================= -+ -+NAME -+---- -+gitformat-pack-cruft - The cruft pack file format -+ -+SYNOPSIS -+-------- -+[verse] -+$GIT_DIR/objects/pack/pack-*.mtimes -+ -+DESCRIPTION -+----------- - - The cruft packs feature offer an alternative to Git's traditional mechanism of - removing unreachable objects. This document provides an overview of Git's -@@ Documentation/gitformat-pack-cruft.txt: same. - To remove unreachable objects from your repository, Git offers `git repack -Ad` - (see linkgit:git-repack[1]). Quoting from the documentation: - --[quote] -+---- - [...] unreachable objects in a previous pack become loose, unpacked objects, - instead of being left in the old pack. [...] loose unreachable objects will be - pruned according to normal expiry rules with the next 'git gc' invocation. -+---- - - Unreachable objects aren't removed immediately, since doing so could race with - an incoming push which may reference an object which is about to be deleted. -@@ Documentation/gitformat-pack-cruft.txt: which aren't already stored in an earlier cruft pack) is significantly more - complicated to construct, and so aren't pursued here. The obvious drawback to - the current implementation is that the entire cruft pack must be re-written from - scratch. -+ -+GIT -+--- -+Part of the linkgit:git[1] suite ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ## @@ @@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferr + +GIT +--- -+Part of the linkgit:git[1] suite - - ## Documentation/technical/signature-format.txt => Documentation/gitformat-signature.txt ## -@@ --Git signature format --==================== -+gitformat-signature(5) -+====================== - --== Overview -+NAME -+---- -+gitformat-signature - Git cryptographic signature formats -+ -+SYNOPSIS -+-------- -+[verse] -+<[tag|commit] object header(s)> -+<over-the-wire protocol> -+ -+DESCRIPTION -+----------- - - Git uses cryptographic signatures in various places, currently objects (tags, - commits, mergetags) and transactions (pushes). In every case, the command which -@@ Documentation/gitformat-signature.txt: Date: Wed Jun 15 09:13:29 2016 +0000 - # gpg: There is no indication that the signature belongs to the owner. - # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 - ---- -+ -+GIT -+--- +Part of the linkgit:git[1] suite ## Documentation/gitprotocol-pack.txt ## @@ command-list.txt: gitdiffcore guide gitformat-bundle developerinterfaces +gitformat-chunk developerinterfaces gitformat-commit-graph developerinterfaces -+gitformat-index developerinterfaces + gitformat-index developerinterfaces +gitformat-pack developerinterfaces -+gitformat-pack-cruft developerinterfaces -+gitformat-signature developerinterfaces + gitformat-signature developerinterfaces gitglossary guide githooks userinterfaces - gitignore userinterfaces ## pack-revindex.h ## @@ -: ----------- > 11: b9dde9788d4 docs: move cruft pack docs to gitformat-pack 9: c4a7fe9d439 = 12: c572688c525 docs: move http-protocol docs to man section 5 -- 2.37.1.1233.g61622908797
