Create a new "User-facing file formats" section in the main "git help
git" manual page. The "Guides" section was added to the manual page in
f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
to list all that documentation.
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)".
We take a wide view of what's considered a "user format", it's not
just a file format, but e.g. githooks(5) also belongs, since the
layout of the ".git/hooks/" and the placement of hooks in it is
something the user might be expected to interact with.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx>
---
Documentation/Makefile | 1 +
Documentation/git-help.txt | 13 +++++++++----
Documentation/git.txt | 7 +++++++
Makefile | 1 +
builtin/help.c | 8 ++++++++
command-list.txt | 16 ++++++++++------
help.c | 11 +++++++++++
help.h | 1 +
t/t0012-help.sh | 16 +++++++++++++++-
9 files changed, 63 insertions(+), 11 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index ed656db2ae9..e973be97162 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -316,6 +316,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
cmds-synchingrepositories.txt \
cmds-synchelpers.txt \
cmds-guide.txt \
+ cmds-userformats.txt \
cmds-purehelpers.txt \
cmds-foreignscminterface.txt
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 44ea63cc6d3..32081f3030d 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,15 @@ SYNOPSIS
--------
[verse]
'git help' [-a|--all [--[no-]verbose]]
- [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
+ [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
'git help' [-g|--guides]
'git help' [-c|--config]
+'git help' [--user-formats]
DESCRIPTION
-----------
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
command and a list of the most commonly used Git commands are printed
on the standard output.
@@ -26,8 +27,8 @@ printed on the standard output.
If the option `--guides` or `-g` is given, a list of the
Git concept guides is also printed on the standard output.
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
purpose, but this can be overridden by other options or configuration
variables.
@@ -62,6 +63,10 @@ OPTIONS
--guides::
Prints a list of the Git concept guides on the standard output.
+--user-formats::
+ Prints a list of the Git user-facing format 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 13f83a2a3a1..7a8be2991df 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -337,6 +337,13 @@ The following documentation pages are guides about Git concepts.
include::cmds-guide.txt[]
+User-facing file formats
+------------------------
+
+This documentation discusses file formats that users are expected to
+edit. These can also be listed with 'git help --user-formats'.
+
+include::cmds-userformats.txt[]
Configuration Mechanism
-----------------------
diff --git a/Makefile b/Makefile
index ed75ed422b5..c59fd6c2be9 100644
--- a/Makefile
+++ b/Makefile
@@ -3304,6 +3304,7 @@ check-docs::
sed -e '1,/^### command list/d' \
-e '/^#/d' \
-e '/guide$$/d' \
+ -e '/formats$$/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 75cd2fb407f..5e842ea5a26 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_FORMATS,
HELP_ACTION_CONFIG_FOR_COMPLETION,
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
} cmd_mode;
@@ -64,6 +65,8 @@ 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-formats", &cmd_mode, N_("print list of user-facing file formats"),
+ HELP_ACTION_USER_FORMATS),
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
HELP_ACTION_CONFIG),
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -79,6 +82,7 @@ static const char * const builtin_help_usage[] = {
" [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
N_("git help [-g|--guides]"),
N_("git help [-c|--config]"),
+ N_("git help [--user-formats]"),
NULL
};
@@ -613,6 +617,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
no_extra_argc(argc);
list_config_help(SHOW_CONFIG_VARS);
return 0;
+ case HELP_ACTION_USER_FORMATS:
+ no_extra_argc(argc);
+ list_user_formats_help();
+ return 0;
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
no_extra_argc(argc);
list_config_help(SHOW_CONFIG_SECTIONS);
diff --git a/command-list.txt b/command-list.txt
index 675c28f0bd0..e4118533e93 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,10 @@
# specified here, which can only have "guide" attribute and nothing
# else.
#
+# User-facing file formats such as documentation for the .gitmodules,
+# .mailmap etc. files lives in man section 5. These entries can only
+# have the "userformats" attribute and nothing else.
+#
### command list (do not change this line)
# command name category [category] [category]
git-add mainporcelain worktree
@@ -191,7 +195,7 @@ git-verify-tag ancillaryinterrogators
git-whatchanged ancillaryinterrogators complete
git-worktree mainporcelain
git-write-tree plumbingmanipulators
-gitattributes guide
+gitattributes userformats
gitcli guide
gitcore-tutorial guide
gitcredentials guide
@@ -200,14 +204,14 @@ gitdiffcore guide
giteveryday guide
gitfaq guide
gitglossary guide
-githooks guide
-gitignore guide
+githooks userformats
+gitignore userformats
gitk mainporcelain
-gitmailmap guide
-gitmodules guide
+gitmailmap userformats
+gitmodules userformats
gitnamespaces guide
gitremote-helpers guide
-gitrepository-layout guide
+gitrepository-layout userformats
gitrevisions guide
gitsubmodules guide
gittutorial guide
diff --git a/help.c b/help.c
index 973e47cdc30..a7b5c909056 100644
--- a/help.c
+++ b/help.c
@@ -37,6 +37,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_userformats, N_("User-facing file formats") },
{ 0, NULL }
};
@@ -422,6 +423,16 @@ void list_guides_help(void)
putchar('\n');
}
+void list_user_formats_help(void)
+{
+ struct category_description catdesc[] = {
+ { CAT_userformats, N_("The user-facing file formats are:") },
+ { 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 9d383f1a0b2..d01908078dc 100644
--- 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(void);
void list_guides_help(void);
+void list_user_formats_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 91b68c74a15..6a20a7303f8 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -41,6 +41,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-formats 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
@@ -78,9 +80,15 @@ test_expect_success 'git help' '
test_i18ngrep "^ commit " help.output &&
test_i18ngrep "^ fetch " help.output
'
+
+test_expect_success 'git help -a' '
+ git help -a >help.output &&
+ grep "^Main Porcelain Commands" help.output &&
+ grep "^User-facing file formats" 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
'
@@ -101,6 +109,12 @@ test_expect_success 'git help succeeds without git.html' '
test_cmp expect test-browser.log
'
+test_expect_success 'git help --formats' '
+ git help --user-formats >help.output &&
+ grep "^ gitattributes " help.output &&
+ grep "^ gitmailmap " help.output
+'
+
test_expect_success 'git help -c' '
git help -c >help.output &&
cat >expect <<-\EOF &&
--
2.34.1.929.ge922d848c7a
