git docs: add a category for user-facing file, repo and command UX

Create a new "Repository, command and file interfaces" section in the
main "git help git" manual page. Move things that belong under this
new criteria from the generic "Guides" section.

The "Guides" section was added in f442f28a81b (git.txt: add list of
guides, 2020-08-05). It makes sense to have e.g. "giteveryday(7)" and
"gitfaq(7)" listed under "Guides".

But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".

An alternate name that was considered for this new section was "User
formats", for consistency with the nomenclature used for man section 5
in general. My man(1) lists it as "File formats and conventions,
e.g. /etc/passwd".

So calling this "git help --formats" or "git help --user-formats"
would make sense for e.g. gitignore(5), but would be stretching it
somewhat for githooks(5), and would seem really suspect for the likes
of gitcli(7).

Let's instead pick a name that's closer to the generic term "User
interface", which is really what this documentation discusses: General
user-interface documentation that doesn't obviously belong elsewhere.

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 4f801f4e4c9470c42ae7933a68970a4984bc54b5..28eb940a9b8ff923993058d7f717bfe044dc71e3 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
        cmds-synchingrepositories.txt \
        cmds-synchelpers.txt \
        cmds-guide.txt \
+       cmds-userinterfaces.txt \
        cmds-purehelpers.txt \
        cmds-foreignscminterface.txt
 

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index bead763fd290cf57170f9fb2bd4c32bf600fc1c0..4eb03bd6c38f27b8186ff822551ad8879ea0a8a5 100644 (file)
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -12,6 +12,7 @@ SYNOPSIS
 'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-interfaces]
 
 DESCRIPTION
 -----------
@@ -69,6 +70,19 @@ OPTIONS
 --guides::
        Prints a list of the Git concept guides on the standard output.
 
+--user-interfaces::
+       Prints a list of the repository, command and file interfaces
+       documentation on the standard output.
++
+In-repository file interfaces such as `.git/info/exclude` are
+documented here (see linkgit:gitrepository-layout[5]), as well as
+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).
++
+This section of the documentation also covers general or widespread
+user-interface conventions (e.g. linkgit:gitcli[7]), and
+pseudo-configuration such as the file-based `.git/hooks/*` interface
+described in linkgit:githooks[5].
+
 -i::
 --info::
        Display manual page for the command in the 'info' format. The

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 302607a49676d59aef4f1f8d39d3a302b7b66cc2..f69d32e1e7934c080ba4ebaad510843731f69efc 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+Repository, command and file interfaces
+---------------------------------------
+
+This documentation discusses repository and command interfaces which
+users are expected to interact with directly. See `--user-formats` in
+linkgit:git-help[1] for more details on the critera.
+
+include::cmds-userinterfaces.txt[]
 
 Configuration Mechanism
 -----------------------

diff --git a/Makefile b/Makefile
index 1624471badc2f8110c6c1ee0fcc5e09c1f529720..ea0ef7df7344b416810cf35f31fe344ecd20b84f 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -3532,6 +3532,7 @@ check-docs::
                sed -e '1,/^### command list/d' \
                    -e '/^#/d' \
                    -e '/guide$$/d' \
+                   -e '/interfaces$$/d' \
                    -e 's/[     ].*//' \
                    -e 's/^/listed /' command-list.txt; \
                $(MAKE) -C Documentation print-man1 | \

diff --git a/builtin/help.c b/builtin/help.c
index dec82d1be27a505dcc6874c1922f42f80bf933c2..1ab1c8a0dd77493b80ba4f7622aaf27b9ed5b496 100644 (file)
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
        HELP_ACTION_ALL = 1,
        HELP_ACTION_GUIDES,
        HELP_ACTION_CONFIG,
+       HELP_ACTION_USER_INTERFACES,
        HELP_ACTION_CONFIG_FOR_COMPLETION,
        HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {
 
        OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
                    HELP_ACTION_GUIDES),
+       OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
+                   N_("print list of user-facing repository, command and file interfaces"),
+                   HELP_ACTION_USER_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, "",
@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {
        N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
        "git help [-g|--guides]",
        "git help [-c|--config]",
+       "git help [--user-interfaces]",
        NULL
 };
 
@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
                opt_mode_usage(argc, "--config-for-completion", help_format);
                list_config_help(SHOW_CONFIG_VARS);
                return 0;
+       case HELP_ACTION_USER_INTERFACES:
+               opt_mode_usage(argc, "--user-interfaces", help_format);
+               list_user_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 9bd6f3c48f4d1853e4cc5df7a9685696f63d72ce..1d45303e14c0cbdd40198530bd3e5429a928295c 100644 (file)
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,11 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# User-facing repository, command and file interfaces such as
+# documentation for the .gitmodules, .mailmap etc. files lives in man
+# sections 5 and 7. These entries can only have the "userinterfaces"
+# attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -192,8 +197,8 @@ git-verify-tag                          ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
-gitattributes                           guide
-gitcli                                  guide
+gitattributes                           userinterfaces
+gitcli                                  userinterfaces
 gitcore-tutorial                        guide
 gitcredentials                          guide
 gitcvs-migration                        guide
@@ -201,15 +206,15 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitglossary                             guide
-githooks                                guide
-gitignore                               guide
+githooks                                userinterfaces
+gitignore                               userinterfaces
 gitk                                    mainporcelain
-gitmailmap                              guide
-gitmodules                              guide
+gitmailmap                              userinterfaces
+gitmodules                              userinterfaces
 gitnamespaces                           guide
 gitremote-helpers                       guide
-gitrepository-layout                    guide
-gitrevisions                            guide
+gitrepository-layout                    userinterfaces
+gitrevisions                            userinterfaces
 gitsubmodules                           guide
 gittutorial                             guide
 gittutorial-2                           guide

diff --git a/help.c b/help.c
index 8a09f18a3d91ea5ed1234722960c217372d48883..3e2a78863b767e17474400ac7cf7f6138fee2907 100644 (file)
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
        { CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
        { 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") },
        { 0, NULL }
 };
 
@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
 
        switch (category) {
        case CAT_guide:
+       case CAT_userinterfaces:
                prefix = "git";
                break;
        default:
@@ -433,6 +435,16 @@ void list_guides_help(void)
        putchar('\n');
 }
 
+void list_user_interfaces_help(void)
+{
+       struct category_description catdesc[] = {
+               { CAT_userinterfaces, N_("User-facing repository, command and file 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 971a3ad855acdc2d02697993ed8a7730626b8572..243104c27a7fa6f2cf0966fabfbfdfb1635478a1 100644 (file)
--- a/help.h
+++ b/help.h
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
 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_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 6c33a4369015c813a73384ff68149463c5189105..bee5ed12203f7b6cc7b401c5a4a017fa69987bac 100755 (executable)
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
        test_expect_code 129 git help -g add &&
        test_expect_code 129 git help -a -g &&
 
+       test_expect_code 129 git help --user-interfaces add &&
+
        test_expect_code 129 git help -g -c &&
        test_expect_code 129 git help --config-for-completion add &&
        test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
        test_i18ngrep "^   commit " help.output &&
        test_i18ngrep "^   fetch  " help.output
 '
+
 test_expect_success 'git help -g' '
        git help -g >help.output &&
-       test_i18ngrep "^   attributes " help.output &&
        test_i18ngrep "^   everyday   " help.output &&
        test_i18ngrep "^   tutorial   " help.output
 '
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
        test_cmp expect test-browser.log
 '
 
+test_expect_success 'git help --user-interfaces' '
+       git help --user-interfaces >help.output &&
+       grep "^   attributes   " help.output &&
+       grep "^   mailmap   " help.output
+'
+
 test_expect_success 'git help -c' '
        git help -c >help.output &&
        cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
        Low-level Commands / Syncing Repositories
 
        Low-level Commands / Internal Helpers
+
+       User-facing repository, command and file interfaces
        EOF
        test_cmp expect actual
 '