[PATCH v4 0/8] git doc + "git help": move "format" docs from technical/*
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Jul 18, 2022, 13:29 UTC
- Message-ID
- <cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com>
- In-Reply-To
- <cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com>
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-- 2.37.1.1032.gb00b5447790