diff options
| -rw-r--r-- | Documentation/Makefile | 1 | ||||
| -rw-r--r-- | Documentation/git-help.txt | 14 | ||||
| -rw-r--r-- | Documentation/git.txt | 8 | ||||
| -rw-r--r-- | Makefile | 1 | ||||
| -rw-r--r-- | builtin/help.c | 9 | ||||
| -rw-r--r-- | command-list.txt | 21 | ||||
| -rw-r--r-- | help.c | 12 | ||||
| -rw-r--r-- | help.h | 1 | ||||
| -rwxr-xr-x | t/t0012-help.sh | 12 |
9 files changed, 70 insertions, 9 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c..28eb940a9b 100644 --- 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 bead763fd2..4eb03bd6c3 100644 --- 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 302607a496..f69d32e1e7 100644 --- 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 ----------------------- @@ -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 dec82d1be2..1ab1c8a0dd 100644 --- 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 9bd6f3c48f..1d45303e14 100644 --- 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 @@ -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; @@ -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 6c33a43690..bee5ed1220 100755 --- 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 ' |