From: Junio C Hamano <gitster@pobox.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: git@vger.kernel.org, "Philip Oakley" <philipoakley@iee.email>,
"Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>,
"SZEDER Gábor" <szeder.dev@gmail.com>,
"Eric Sunshine" <sunshine@sunshineco.com>
Subject: Re: [PATCH v2 1/5] help: correct the usage string in -h and documentation
Date: Fri, 10 Sep 2021 18:12:31 -0700 [thread overview]
Message-ID: <xmqqr1dvoqyo.fsf@gitster.g> (raw)
In-Reply-To: patch-v2-1.5-b10bfd21f14-20210910T112545Z-avarab@gmail.com
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
> index 44fe8860b3f..568a0b606f3 100644
> --- a/Documentation/git-help.txt
> +++ b/Documentation/git-help.txt
> @@ -9,7 +9,7 @@ SYNOPSIS
> --------
> [verse]
> 'git help' [-a|--all [--[no-]verbose]] [-g|--guides]
> - [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
> + [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
This one is good, but ...
> diff --git a/builtin/help.c b/builtin/help.c
> index b7eec06c3de..44ea2798cda 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -59,7 +59,8 @@ static struct option builtin_help_options[] = {
> };
>
> static const char * const builtin_help_usage[] = {
> - N_("git help [--all] [--guides] [--man | --web | --info] [<command>]"),
> + N_("git help [-a|--all] [-g|--guides] [--[no-]verbose]]\n"
> + " [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
Aside from the addition of so-far-missing "verbose", which is
obviously a good change, I am not sure if the other change is a good
idea.
This is because *_usage[] is designed to be always shown together
with the list of options built from the option table the
parse_options() uses, and the readers will see the correspondence
between long and short options even more clear there.
$ git help -h
usage: git help [--all] [--guides] [--man | --web | --info] [<command>]
-a, --all print all available commands
-g, --guides print list of useful guides
-c, --config print all configuration variable names
-m, --man show man page
-w, --web show manual in web browser
-i, --info show info page
-v, --verbose print command description
If you look at output from
$ git grep -A4 -e '_usage\[' builtin/\*.c
you'll notice that many of them do not even spell out each option
and instead have a single [<options>] placeholder unless the command
has only very small number of options. With the number of options
that "git help" takes, it might even be warranted to switch to the
more generic "git help [<option>...] [<command>]".
Not a strict veto, but just making sure if the over-cluttering of
the early lines in "help -h" output has been considered as a
possible downside before suggesting this change.
Thanks.
next prev parent reply other threads:[~2021-09-11 1:12 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-08 15:24 [PATCH 0/6] help: fix usage nits & bugs, completion shellscript->C Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 1/6] help: correct the usage string in -h and documentation Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 2/6] help: correct usage string for "git help --guides" Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 3/6] help tests: add test for --config output Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 4/6] help: refactor "for_human" control flow in cmd_help() Ævar Arnfjörð Bjarmason
2021-09-08 16:41 ` Eric Sunshine
2021-09-08 17:02 ` Junio C Hamano
2021-09-08 19:36 ` Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 5/6] help: correct logic error in combining --all and --config Ævar Arnfjörð Bjarmason
2021-09-08 16:39 ` Eric Sunshine
2021-09-08 19:37 ` Ævar Arnfjörð Bjarmason
2021-09-10 8:08 ` Eric Sunshine
2021-09-10 11:09 ` Ævar Arnfjörð Bjarmason
2021-09-08 15:24 ` [PATCH 6/6] help / completion: make "git help" do the hard work Ævar Arnfjörð Bjarmason
2021-09-10 11:28 ` [PATCH v2 0/5] help: fix usage nits & bugs, completion shellscript->C Ævar Arnfjörð Bjarmason
2021-09-10 11:28 ` [PATCH v2 1/5] help: correct the usage string in -h and documentation Ævar Arnfjörð Bjarmason
2021-09-11 1:12 ` Junio C Hamano [this message]
2021-09-11 2:34 ` Ævar Arnfjörð Bjarmason
2021-09-10 11:28 ` [PATCH v2 2/5] help: correct usage & behavior of "git help --guides" Ævar Arnfjörð Bjarmason
2021-09-10 18:15 ` Philip Oakley
2021-09-10 18:21 ` Philip Oakley
2021-09-21 13:49 ` Ævar Arnfjörð Bjarmason
2021-09-21 14:20 ` Philip Oakley
2021-09-11 1:22 ` Junio C Hamano
2021-09-10 11:28 ` [PATCH v2 3/5] help tests: add test for --config output Ævar Arnfjörð Bjarmason
2021-09-11 1:32 ` Junio C Hamano
2021-09-11 2:25 ` Ævar Arnfjörð Bjarmason
2021-09-13 19:21 ` Philip Oakley
2021-09-10 11:28 ` [PATCH v2 4/5] help: correct logic error in combining --all and --config Ævar Arnfjörð Bjarmason
2021-09-10 23:45 ` Junio C Hamano
2021-09-10 11:28 ` [PATCH v2 5/5] help / completion: make "git help" do the hard work Ævar Arnfjörð Bjarmason
2021-09-11 1:35 ` Junio C Hamano
2021-09-21 22:40 ` [PATCH v3 0/9] help: fix usage nits & bugs, completion shellscript->C Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 1/9] help: correct the usage string in -h and documentation Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 2/9] help: correct usage & behavior of "git help --guides" Ævar Arnfjörð Bjarmason
2021-09-23 18:05 ` Junio C Hamano
2021-09-21 22:40 ` [PATCH v3 3/9] help tests: add test for --config output Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 4/9] help: correct logic error in combining --all and --config Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 5/9] help: correct logic error in combining --all and --guides Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 6/9] help: simplify by moving to OPT_CMDMODE() Ævar Arnfjörð Bjarmason
2021-09-23 18:03 ` Junio C Hamano
2021-09-23 18:05 ` Junio C Hamano
2021-09-21 22:40 ` [PATCH v3 7/9] help tests: test --config-for-completion option & output Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 8/9] help / completion: make "git help" do the hard work Ævar Arnfjörð Bjarmason
2021-09-21 22:40 ` [PATCH v3 9/9] help: move column config discovery to help.c library Ævar Arnfjörð Bjarmason
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqr1dvoqyo.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=pclouds@gmail.com \
--cc=philipoakley@iee.email \
--cc=sunshine@sunshineco.com \
--cc=szeder.dev@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).