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>
Ævar Arnfjörð Bjarmason committed
Aug 4, 2022 at 18:28 UTC
d976c5100fb5f55f648d8b400bcbda1116b82dec
9 files changed
+70
-9
Documentation/Makefile
+1
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
290
cmds-synchingrepositories.txt \
291
cmds-synchelpers.txt \
292
cmds-guide.txt \
293
+ cmds-userinterfaces.txt \
294
cmds-purehelpers.txt \
295
cmds-foreignscminterface.txt
296
Documentation/git-help.txt
+14
@@ -12,6 +12,7 @@ SYNOPSIS
12
'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
13
'git help' [-g|--guides]
14
'git help' [-c|--config]
15
+'git help' [--user-interfaces]
16
17
DESCRIPTION
18
-----------
@@ -69,6 +70,19 @@ OPTIONS
70
--guides::
71
Prints a list of the Git concept guides on the standard output.
72
73
+--user-interfaces::
74
+ Prints a list of the repository, command and file interfaces
75
+ documentation on the standard output.
76
++
77
+In-repository file interfaces such as `.git/info/exclude` are
78
+documented here (see linkgit:gitrepository-layout[5]), as well as
79
+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).
80
++
81
+This section of the documentation also covers general or widespread
82
+user-interface conventions (e.g. linkgit:gitcli[7]), and
83
+pseudo-configuration such as the file-based `.git/hooks/*` interface
84
+described in linkgit:githooks[5].
85
+
86
-i::
87
--info::
88
Display manual page for the command in the 'info' format. The
Documentation/git.txt
+8
@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.
339
340
include::cmds-guide.txt[]
341
342
+Repository, command and file interfaces
343
+---------------------------------------
344
+
345
+This documentation discusses repository and command interfaces which
346
+users are expected to interact with directly. See `--user-formats` in
347
+linkgit:git-help[1] for more details on the critera.
348
+
349
+include::cmds-userinterfaces.txt[]
350
351
Configuration Mechanism
352
-----------------------
Makefile
+1
@@ -3532,6 +3532,7 @@ check-docs::
3532
sed -e '1,/^### command list/d' \
3533
-e '/^#/d' \
3534
-e '/guide$$/d' \
3535
+ -e '/interfaces$$/d' \
3536
-e 's/[ ].*//' \
3537
-e 's/^/listed /' command-list.txt; \
3538
$(MAKE) -C Documentation print-man1 | \
builtin/help.c
+9
@@ -43,6 +43,7 @@ static enum help_action {
43
HELP_ACTION_ALL = 1,
44
HELP_ACTION_GUIDES,
45
HELP_ACTION_CONFIG,
46
+ HELP_ACTION_USER_INTERFACES,
47
HELP_ACTION_CONFIG_FOR_COMPLETION,
48
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
49
} cmd_mode;
@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {
70
71
OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
72
HELP_ACTION_GUIDES),
73
+ OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
74
+ N_("print list of user-facing repository, command and file interfaces"),
75
+ HELP_ACTION_USER_INTERFACES),
76
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
77
HELP_ACTION_CONFIG),
78
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {
88
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
89
"git help [-g|--guides]",
90
"git help [-c|--config]",
91
+ "git help [--user-interfaces]",
92
NULL
93
};
94
@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
659
opt_mode_usage(argc, "--config-for-completion", help_format);
660
list_config_help(SHOW_CONFIG_VARS);
661
return 0;
662
+ case HELP_ACTION_USER_INTERFACES:
663
+ opt_mode_usage(argc, "--user-interfaces", help_format);
664
+ list_user_interfaces_help();
665
+ return 0;
666
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
667
opt_mode_usage(argc, "--config-sections-for-completion",
668
help_format);
command-list.txt
+13
-8
@@ -43,6 +43,11 @@
43
# specified here, which can only have "guide" attribute and nothing
44
# else.
45
#
46
+# User-facing repository, command and file interfaces such as
47
+# documentation for the .gitmodules, .mailmap etc. files lives in man
48
+# sections 5 and 7. These entries can only have the "userinterfaces"
49
+# attribute and nothing else.
50
+#
51
### command list (do not change this line)
52
# command name category [category] [category]
53
git-add mainporcelain worktree
@@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators
197
git-whatchanged ancillaryinterrogators complete
198
git-worktree mainporcelain
199
git-write-tree plumbingmanipulators
195
-gitattributes guide
196
-gitcli guide
200
+gitattributes userinterfaces
201
+gitcli userinterfaces
202
gitcore-tutorial guide
203
gitcredentials guide
204
gitcvs-migration guide
@@ -201,15 +206,15 @@ gitdiffcore guide
206
giteveryday guide
207
gitfaq guide
208
gitglossary guide
204
-githooks guide
205
-gitignore guide
209
+githooks userinterfaces
210
+gitignore userinterfaces
211
gitk mainporcelain
207
-gitmailmap guide
208
-gitmodules guide
212
+gitmailmap userinterfaces
213
+gitmodules userinterfaces
214
gitnamespaces guide
215
gitremote-helpers guide
211
-gitrepository-layout guide
212
-gitrevisions guide
216
+gitrepository-layout userinterfaces
217
+gitrevisions userinterfaces
218
gitsubmodules guide
219
gittutorial guide
220
gittutorial-2 guide
help.c
+12
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
38
{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
39
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
40
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
41
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
42
{ 0, NULL }
43
};
44
@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
49
50
switch (category) {
51
case CAT_guide:
52
+ case CAT_userinterfaces:
53
prefix = "git";
54
break;
55
default:
@@ -433,6 +435,16 @@ void list_guides_help(void)
435
putchar('\n');
436
}
437
438
+void list_user_interfaces_help(void)
439
+{
440
+ struct category_description catdesc[] = {
441
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
442
+ { 0, NULL }
443
+ };
444
+ print_cmd_by_category(catdesc, NULL);
445
+ putchar('\n');
446
+}
447
+
448
static int get_alias(const char *var, const char *value, void *data)
449
{
450
struct string_list *list = data;
help.h
+1
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
22
void list_common_cmds_help(void);
23
void list_all_cmds_help(int show_external_commands, int show_aliases);
24
void list_guides_help(void);
25
+void list_user_interfaces_help(void);
26
27
void list_all_main_cmds(struct string_list *list);
28
void list_all_other_cmds(struct string_list *list);
t/t0012-help.sh
+11
-1
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
44
test_expect_code 129 git help -g add &&
45
test_expect_code 129 git help -a -g &&
46
47
+ test_expect_code 129 git help --user-interfaces add &&
48
+
49
test_expect_code 129 git help -g -c &&
50
test_expect_code 129 git help --config-for-completion add &&
51
test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
106
test_i18ngrep "^ commit " help.output &&
107
test_i18ngrep "^ fetch " help.output
108
'
109
+
110
test_expect_success 'git help -g' '
111
git help -g >help.output &&
109
- test_i18ngrep "^ attributes " help.output &&
112
test_i18ngrep "^ everyday " help.output &&
113
test_i18ngrep "^ tutorial " help.output
114
'
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
129
test_cmp expect test-browser.log
130
'
131
132
+test_expect_success 'git help --user-interfaces' '
133
+ git help --user-interfaces >help.output &&
134
+ grep "^ attributes " help.output &&
135
+ grep "^ mailmap " help.output
136
+'
137
+
138
test_expect_success 'git help -c' '
139
git help -c >help.output &&
140
cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
228
Low-level Commands / Syncing Repositories
229
230
Low-level Commands / Internal Helpers
231
+
232
+ User-facing repository, command and file interfaces
233
EOF
234
test_cmp expect actual
235
'