freshlybakedca.ke
Git fork
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>
authored by
Ævar Arnfjörð Bjarmason
and committed by
Junio C Hamano
d976c510
dba1e539
+1
Documentation/Makefile
+1
Documentation/Makefile
+14
Documentation/git-help.txt
+14
Documentation/git-help.txt
···
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
-g::
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::
+8
Documentation/git.txt
+8
Documentation/git.txt
···
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
-----------------------
+1
Makefile
+1
Makefile
+9
builtin/help.c
+9
builtin/help.c
···
43
HELP_ACTION_ALL = 1,
44
HELP_ACTION_GUIDES,
45
HELP_ACTION_CONFIG,
46
HELP_ACTION_CONFIG_FOR_COMPLETION,
47
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
48
} cmd_mode;
···
69
70
OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
71
HELP_ACTION_GUIDES),
72
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
73
HELP_ACTION_CONFIG),
74
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
···
84
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
85
"git help [-g|--guides]",
86
"git help [-c|--config]",
87
NULL
88
};
89
···
653
case HELP_ACTION_CONFIG_FOR_COMPLETION:
654
opt_mode_usage(argc, "--config-for-completion", help_format);
655
list_config_help(SHOW_CONFIG_VARS);
656
return 0;
657
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
658
opt_mode_usage(argc, "--config-sections-for-completion",
···
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;
···
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, "",
···
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
···
658
case HELP_ACTION_CONFIG_FOR_COMPLETION:
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",
+13
-8
command-list.txt
+13
-8
command-list.txt
···
43
# specified here, which can only have "guide" attribute and nothing
44
# else.
45
#
46
### command list (do not change this line)
47
# command name category [category] [category]
48
git-add mainporcelain worktree
···
192
git-whatchanged ancillaryinterrogators complete
193
git-worktree mainporcelain
194
git-write-tree plumbingmanipulators
195
-
gitattributes guide
196
-
gitcli guide
197
gitcore-tutorial guide
198
gitcredentials guide
199
gitcvs-migration guide
···
201
giteveryday guide
202
gitfaq guide
203
gitglossary guide
204
-
githooks guide
205
-
gitignore guide
206
gitk mainporcelain
207
-
gitmailmap guide
208
-
gitmodules guide
209
gitnamespaces guide
210
gitremote-helpers guide
211
-
gitrepository-layout guide
212
-
gitrevisions guide
213
gitsubmodules guide
214
gittutorial guide
215
gittutorial-2 guide
···
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
···
197
git-whatchanged ancillaryinterrogators complete
198
git-worktree mainporcelain
199
git-write-tree plumbingmanipulators
200
+
gitattributes userinterfaces
201
+
gitcli userinterfaces
202
gitcore-tutorial guide
203
gitcredentials guide
204
gitcvs-migration guide
···
206
giteveryday guide
207
gitfaq guide
208
gitglossary guide
209
+
githooks userinterfaces
210
+
gitignore userinterfaces
211
gitk mainporcelain
212
+
gitmailmap userinterfaces
213
+
gitmodules userinterfaces
214
gitnamespaces guide
215
gitremote-helpers guide
216
+
gitrepository-layout userinterfaces
217
+
gitrevisions userinterfaces
218
gitsubmodules guide
219
gittutorial guide
220
gittutorial-2 guide
+12
help.c
+12
help.c
···
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
{ 0, NULL }
42
};
43
···
48
49
switch (category) {
50
case CAT_guide:
51
prefix = "git";
52
break;
53
default:
···
427
{
428
struct category_description catdesc[] = {
429
{ CAT_guide, N_("The Git concept guides are:") },
430
{ 0, NULL }
431
};
432
print_cmd_by_category(catdesc, NULL);
···
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
···
49
50
switch (category) {
51
case CAT_guide:
52
+
case CAT_userinterfaces:
53
prefix = "git";
54
break;
55
default:
···
429
{
430
struct category_description catdesc[] = {
431
{ CAT_guide, N_("The Git concept guides are:") },
432
+
{ 0, NULL }
433
+
};
434
+
print_cmd_by_category(catdesc, NULL);
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);
+1
help.h
+1
help.h
···
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);
+11
-1
t/t0012-help.sh
+11
-1
t/t0012-help.sh
···
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 -g -c &&
48
test_expect_code 129 git help --config-for-completion add &&
49
test_expect_code 129 git help --config-sections-for-completion add
···
104
test_i18ngrep "^ commit " help.output &&
105
test_i18ngrep "^ fetch " help.output
106
'
107
test_expect_success 'git help -g' '
108
git help -g >help.output &&
109
-
test_i18ngrep "^ attributes " help.output &&
110
test_i18ngrep "^ everyday " help.output &&
111
test_i18ngrep "^ tutorial " help.output
112
'
···
125
git -c help.htmlpath=html-with-docs help status &&
126
echo "html-with-docs/git-status.html" >expect &&
127
test_cmp expect test-browser.log
128
'
129
130
test_expect_success 'git help -c' '
···
220
Low-level Commands / Syncing Repositories
221
222
Low-level Commands / Internal Helpers
223
EOF
224
test_cmp expect actual
225
'
···
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
···
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 &&
112
test_i18ngrep "^ everyday " help.output &&
113
test_i18ngrep "^ tutorial " help.output
114
'
···
127
git -c help.htmlpath=html-with-docs help status &&
128
echo "html-with-docs/git-status.html" >expect &&
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' '
···
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
'