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
12
'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
13
13
'git help' [-g|--guides]
14
14
'git help' [-c|--config]
15
+
'git help' [--user-interfaces]
15
16
16
17
DESCRIPTION
17
18
-----------
···
68
69
-g::
69
70
--guides::
70
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].
71
85
72
86
-i::
73
87
--info::
+8
Documentation/git.txt
+8
Documentation/git.txt
···
339
339
340
340
include::cmds-guide.txt[]
341
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[]
342
350
343
351
Configuration Mechanism
344
352
-----------------------
+1
Makefile
+1
Makefile
+9
builtin/help.c
+9
builtin/help.c
···
43
43
HELP_ACTION_ALL = 1,
44
44
HELP_ACTION_GUIDES,
45
45
HELP_ACTION_CONFIG,
46
+
HELP_ACTION_USER_INTERFACES,
46
47
HELP_ACTION_CONFIG_FOR_COMPLETION,
47
48
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
48
49
} cmd_mode;
···
69
70
70
71
OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
71
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),
72
76
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
73
77
HELP_ACTION_CONFIG),
74
78
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
···
84
88
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
85
89
"git help [-g|--guides]",
86
90
"git help [-c|--config]",
91
+
"git help [--user-interfaces]",
87
92
NULL
88
93
};
89
94
···
653
658
case HELP_ACTION_CONFIG_FOR_COMPLETION:
654
659
opt_mode_usage(argc, "--config-for-completion", help_format);
655
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();
656
665
return 0;
657
666
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
658
667
opt_mode_usage(argc, "--config-sections-for-completion",
+13
-8
command-list.txt
+13
-8
command-list.txt
···
43
43
# specified here, which can only have "guide" attribute and nothing
44
44
# else.
45
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
+
#
46
51
### command list (do not change this line)
47
52
# command name category [category] [category]
48
53
git-add mainporcelain worktree
···
192
197
git-whatchanged ancillaryinterrogators complete
193
198
git-worktree mainporcelain
194
199
git-write-tree plumbingmanipulators
195
-
gitattributes guide
196
-
gitcli guide
200
+
gitattributes userinterfaces
201
+
gitcli userinterfaces
197
202
gitcore-tutorial guide
198
203
gitcredentials guide
199
204
gitcvs-migration guide
···
201
206
giteveryday guide
202
207
gitfaq guide
203
208
gitglossary guide
204
-
githooks guide
205
-
gitignore guide
209
+
githooks userinterfaces
210
+
gitignore userinterfaces
206
211
gitk mainporcelain
207
-
gitmailmap guide
208
-
gitmodules guide
212
+
gitmailmap userinterfaces
213
+
gitmodules userinterfaces
209
214
gitnamespaces guide
210
215
gitremote-helpers guide
211
-
gitrepository-layout guide
212
-
gitrevisions guide
216
+
gitrepository-layout userinterfaces
217
+
gitrevisions userinterfaces
213
218
gitsubmodules guide
214
219
gittutorial guide
215
220
gittutorial-2 guide
+12
help.c
+12
help.c
···
38
38
{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
39
39
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
40
40
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
41
+
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
41
42
{ 0, NULL }
42
43
};
43
44
···
48
49
49
50
switch (category) {
50
51
case CAT_guide:
52
+
case CAT_userinterfaces:
51
53
prefix = "git";
52
54
break;
53
55
default:
···
427
429
{
428
430
struct category_description catdesc[] = {
429
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:") },
430
442
{ 0, NULL }
431
443
};
432
444
print_cmd_by_category(catdesc, NULL);
+1
help.h
+1
help.h
···
22
22
void list_common_cmds_help(void);
23
23
void list_all_cmds_help(int show_external_commands, int show_aliases);
24
24
void list_guides_help(void);
25
+
void list_user_interfaces_help(void);
25
26
26
27
void list_all_main_cmds(struct string_list *list);
27
28
void list_all_other_cmds(struct string_list *list);
+11
-1
t/t0012-help.sh
+11
-1
t/t0012-help.sh
···
44
44
test_expect_code 129 git help -g add &&
45
45
test_expect_code 129 git help -a -g &&
46
46
47
+
test_expect_code 129 git help --user-interfaces add &&
48
+
47
49
test_expect_code 129 git help -g -c &&
48
50
test_expect_code 129 git help --config-for-completion add &&
49
51
test_expect_code 129 git help --config-sections-for-completion add
···
104
106
test_i18ngrep "^ commit " help.output &&
105
107
test_i18ngrep "^ fetch " help.output
106
108
'
109
+
107
110
test_expect_success 'git help -g' '
108
111
git help -g >help.output &&
109
-
test_i18ngrep "^ attributes " help.output &&
110
112
test_i18ngrep "^ everyday " help.output &&
111
113
test_i18ngrep "^ tutorial " help.output
112
114
'
···
125
127
git -c help.htmlpath=html-with-docs help status &&
126
128
echo "html-with-docs/git-status.html" >expect &&
127
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
128
136
'
129
137
130
138
test_expect_success 'git help -c' '
···
220
228
Low-level Commands / Syncing Repositories
221
229
222
230
Low-level Commands / Internal Helpers
231
+
232
+
User-facing repository, command and file interfaces
223
233
EOF
224
234
test_cmp expect actual
225
235
'