git docs: add a category for file formats, protocols and interfaces

Create a new "File formats, protocols and other developer interfaces"
section in the main "git help git" manual page and start moving the
documentation that now lives in "Documentation/technical/*.git" over
to it. This complements the newly added and adjacent "Repository,
command and file interfaces" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page. Subsequent commits will move more git
internal format documentation over.

Unfortunately the syntax of the current Documentation/technical/*.txt
is not the same (when it comes to section headings etc.) as our
Documentation/*.txt documentation, so change the relevant bits of
syntax as we're moving this over.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 28eb940a9b8ff923993058d7f717bfe044dc71e3..1a4a545f44abcedabf29158d820fff61a7b7eb7b 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
        cmds-synchingrepositories.txt \
        cmds-synchelpers.txt \
        cmds-guide.txt \
+       cmds-developerinterfaces.txt \
        cmds-userinterfaces.txt \
        cmds-purehelpers.txt \
        cmds-foreignscminterface.txt

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7685b570455cadc243929deecc197776326dfeba..f0b1282b9187234e6c96e87706a51df4864fcfda 100644 (file)
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in
 size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
-See link:technical/bundle-format.html[the `bundle-format`
-documentation] for more details and the discussion of "thin pack" in
-link:technical/pack-format.html[the pack format documentation] for
-further details.
+See linkgit:gitformat-bundle[5] for more details and the discussion of
+"thin pack" in link:technical/pack-format.html[the pack format
+documentation] for further details.
 
 OPTIONS
 -------
@@ -77,7 +76,7 @@ verify <file>::
        commits exist and are fully linked in the current repository.
        Then, 'git bundle' prints a list of missing commits, if any.
        Finally, information about additional capabilities, such as "object
-       filter", is printed. See "Capabilities" in link:technical/bundle-format.html
+       filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
        for more information. The exit code is zero for success, but will
        be nonzero if the bundle file is invalid.
 
@@ -337,6 +336,11 @@ You can also see what references it offers:
 $ git ls-remote mybundle
 ----------------
 
+FILE FORMAT
+-----------
+
+See linkgit:gitformat-bundle[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 4eb03bd6c38f27b8186ff822551ad8879ea0a8a5..2b0b5e390dcb94a651ca92ded8c1542a175f7f09 100644 (file)
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -13,6 +13,7 @@ SYNOPSIS
 'git help' [-g|--guides]
 'git help' [-c|--config]
 'git help' [--user-interfaces]
+'git help' [--developer-interfaces]
 
 DESCRIPTION
 -----------
@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and
 pseudo-configuration such as the file-based `.git/hooks/*` interface
 described in linkgit:githooks[5].
 
+--developer-interfaces::
+       Print list of file formats, protocols and other developer
+       interfaces documentation on the standard output.
+
 -i::
 --info::
        Display manual page for the command in the 'info' format. The

diff --git a/Documentation/git.txt b/Documentation/git.txt
index f69d32e1e7934c080ba4ebaad510843731f69efc..f064951b5c4a6bf0db103898455a6566958f8ab1 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.
 
 include::cmds-userinterfaces.txt[]
 
+File formats, protocols and other developer interfaces
+------------------------------------------------------
+
+This documentation discusses file formats, over-the-wire protocols and
+other git developer interfaces. See `--developer-interfaces` in
+linkgit:git-help[1].
+
+include::cmds-developerinterfaces.txt[]
+
 Configuration Mechanism
 -----------------------
 

diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 79%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index b9be8644cf5d53161b7190f580be935b28d402a3..6a9d9e5bf6f49119d9ce3f77a88c249a5cf0a554 100644 (file)
--- a/Documentation/technical/bundle-format.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -1,11 +1,33 @@
-= Git bundle v2 format
+gitformat-bundle(5)
+===================
 
-The Git bundle format is a format that represents both refs and Git objects.
+NAME
+----
+gitformat-bundle - The bundle file format
+
+
+SYNOPSIS
+--------
+[verse]
+*.bundle
+*.bdl
+
+DESCRIPTION
+-----------
+
+The Git bundle format is a format that represents both refs and Git
+objects. A bundle is a header in a format similar to
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
 
-== Format
+The format is created and read by the linkgit:git-bundle[1] command,
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
+
+
+FORMAT
+------
 
 We will use ABNF notation to define the Git bundle format. See
-protocol-common.txt for the details.
+link:technical/protocol-common.html for the details.
 
 A v2 bundle looks like this:
 
@@ -36,7 +58,9 @@ value        = *(%01-09 / %0b-FF)
 pack         = ... ; packfile
 ----
 
-== Semantics
+
+SEMANTICS
+---------
 
 A Git bundle consists of several parts.
 
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
 This is a comment and it has no specific meaning. The writer of the bundle MAY
 put any string here. The reader of the bundle MUST ignore the comment.
 
-=== Note on the shallow clone and a Git bundle
+Note on the shallow clone and a Git bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note that the prerequisites does not represent a shallow-clone boundary. The
 semantics of the prerequisites and the shallow-clone boundaries are different,
 and the Git bundle v2 format cannot represent a shallow clone repository.
 
-== Capabilities
+CAPABILITIES
+------------
 
 Because there is no opportunity for negotiation, unknown capabilities cause 'git
 bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
 * `filter` specifies an object filter as in the `--filter` option in
   linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
   `.promisor` pack-file after it is unbundled.
+
+GIT
+---
+Part of the linkgit:git[1] suite

diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 425377dfeb7fc0856773fd5eaaac7dd3b7b1c999..02408a0062f0c8c380847b32592aae5671ca85de 100755 (executable)
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -32,6 +32,9 @@ my %SECTIONS;
                'SEE ALSO' => {
                        order => $order++,
                },
+               'FILE FORMAT' => {
+                       order => $order++,
+               },
                'GIT' => {
                        required => 1,
                        order => $order++,

diff --git a/builtin/help.c b/builtin/help.c
index 1ab1c8a0dd77493b80ba4f7622aaf27b9ed5b496..09ac4289f13065a20e0fb50d08d0a784d3dab8e0 100644 (file)
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
        HELP_ACTION_GUIDES,
        HELP_ACTION_CONFIG,
        HELP_ACTION_USER_INTERFACES,
+       HELP_ACTION_DEVELOPER_INTERFACES,
        HELP_ACTION_CONFIG_FOR_COMPLETION,
        HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {
        OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
                    N_("print list of user-facing repository, command and file interfaces"),
                    HELP_ACTION_USER_INTERFACES),
+       OPT_CMDMODE(0, "developer-interfaces", &cmd_mode,
+                   N_("print list of file formats, protocols and other developer interfaces"),
+                   HELP_ACTION_DEVELOPER_INTERFACES),
        OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
                    HELP_ACTION_CONFIG),
        OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {
        "git help [-g|--guides]",
        "git help [-c|--config]",
        "git help [--user-interfaces]",
+       "git help [--developer-interfaces]",
        NULL
 };
 
@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
                opt_mode_usage(argc, "--user-interfaces", help_format);
                list_user_interfaces_help();
                return 0;
+       case HELP_ACTION_DEVELOPER_INTERFACES:
+               opt_mode_usage(argc, "--developer-interfaces", help_format);
+               list_developer_interfaces_help();
+               return 0;
        case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
                opt_mode_usage(argc, "--config-sections-for-completion",
                               help_format);

diff --git a/command-list.txt b/command-list.txt
index 1d45303e14c0cbdd40198530bd3e5429a928295c..1950c4ccd9c5fd59f354ba83643ed6968a3446ed 100644 (file)
--- a/command-list.txt
+++ b/command-list.txt
@@ -48,6 +48,10 @@
 # sections 5 and 7. These entries can only have the "userinterfaces"
 # attribute and nothing else.
 #
+# Git's file formats and protocols, such as documentation for the
+# *.bundle format lives in man section 5. These entries can only have
+# the "developerinterfaces" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -205,6 +209,7 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bundle                        developerinterfaces
 gitglossary                             guide
 githooks                                userinterfaces
 gitignore                               userinterfaces

diff --git a/help.c b/help.c
index 3e2a78863b767e17474400ac7cf7f6138fee2907..991e33f8a6eb1950cff6fa9f9fbaa2a4909d640b 100644 (file)
--- a/help.c
+++ b/help.c
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
        { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
        { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
        { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
+       { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
        { 0, NULL }
 };
 
@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
        switch (category) {
        case CAT_guide:
        case CAT_userinterfaces:
+       case CAT_developerinterfaces:
                prefix = "git";
                break;
        default:
@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)
        putchar('\n');
 }
 
+void list_developer_interfaces_help(void)
+{
+       struct category_description catdesc[] = {
+               { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
+               { 0, NULL }
+       };
+       print_cmd_by_category(catdesc, NULL);
+       putchar('\n');
+}
+
 static int get_alias(const char *var, const char *value, void *data)
 {
        struct string_list *list = data;

diff --git a/help.h b/help.h
index 243104c27a7fa6f2cf0966fabfbfdfb1635478a1..af073a7a0263e7bdacf6dd01f13235b2a655f360 100644 (file)
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
 void list_all_cmds_help(int show_external_commands, int show_aliases);
 void list_guides_help(void);
 void list_user_interfaces_help(void);
+void list_developer_interfaces_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);

diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index bee5ed12203f7b6cc7b401c5a4a017fa69987bac..4ed2f242eb246b05e82527d16f7203ec2d163af9 100755 (executable)
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
        Low-level Commands / Internal Helpers
 
        User-facing repository, command and file interfaces
+
+       Developer-facing file file formats, protocols and interfaces
        EOF
        test_cmp expect actual
 '