mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git docs: add a category for user-facing file, repo and command UX

Browse Source 
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 f442f28a81 (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>
This commit is contained in:
Ævar Arnfjörð Bjarmason
2022-08-04 18:28:33 +02:00
committed by Junio C Hamano
parent dba1e5392f
commit d976c5100f
9 changed files with 70 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
builtin/help.c
View File

@ -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);