From: Junio C Hamano <gitster@pobox.com>
Date: Sat, 11 Sep 2021 01:12:31 GMT
Subject: Re: [PATCH v2 1/5] help: correct the usage string in -h and documentation
Message-ID: <xmqqr1dvoqyo.fsf@gitster.g>
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.