Re: [PATCH v2 2/5] help: correct usage & behavior of "git help --guides"

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Fri, Sep 10 2021, Philip Oakley wrote:

> On 10/09/2021 19:15, Philip Oakley wrote:
>> On 10/09/2021 12:28, Ævar Arnfjörð Bjarmason wrote:
>>> As noted in 65f98358c0c (builtin/help.c: add --guide option,
>>> 2013-04-02) and a133737b809 (doc: include --guide option description
>>> for "git help", 2013-04-02) which introduced the --guide option it
>>> cannot be combined with e.g. <command>.
>>>
>>> Change both the usage string to reflect that, and test and assert for
>>> this behavior in the command itself. Now that we assert this in code
>>> we don't need to exhaustively describe the previous confusing behavior
>>> in the documentation either, instead of silently ignoring the provided
>>> argument we'll now error out.
>>>
>>> The comment being removed was added in 15f7d494380 (builtin/help.c:
>>> split "-a" processing into two, 2013-04-02). The "Ignore any remaining
>>> args" part of it is now no longer applicable as explained above, let's
>>> just remove it entirely, it's rather obvious that if we're returning
>>> we're done.
>>>
>>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>>> ---
>>>  Documentation/git-help.txt |  6 +++---
>>>  builtin/help.c             | 11 +++++++----
>>>  t/t0012-help.sh            |  4 ++++
>>>  3 files changed, 14 insertions(+), 7 deletions(-)
>>>
>>> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
>>> index 568a0b606f3..cb8e3d4da9e 100644
>>> --- a/Documentation/git-help.txt
>>> +++ b/Documentation/git-help.txt
>>> @@ -8,8 +8,9 @@ git-help - Display help information about Git
>>>  SYNOPSIS
>>>  --------
>>>  [verse]
>>> -'git help' [-a|--all [--[no-]verbose]] [-g|--guides]
>>> +'git help' [-a|--all [--[no-]verbose]]
>>>  	   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
>>> +'git help' [-g|--guides]
>> Shouldn't we also include the [-c|--config] options here in the synopsis,
>> and the help_usage below?
>
> I see this is fixed in 4/5

I updated the config message for the v3 to say it'll be addressed later>

>> Further, shouldn't we mention this (git help -c) on the git config man
>> page, e.g. "A list all available configuration variables can be
>> generated by `git help -c`." 
>
> Still feel this one would be useful (but may be out of scope of this series)

We already have such a mention in the documentation, it pre-dates this
series. I.e.:
    
    -c::
    --config::
            List all available configuration variables. This is a short
            summary of the list in linkgit:git-config[1].
    
The "short summary" there is quite the understatement, but that wording
was added in , 3ac68a93fd2 (help: add --config to list all available
config, 2018-05-26) so it wasn't some mistake with the option drifting
out of sync with an earlier implementation.

I think what Nguyễn meant here was "much shorte than 'git help config'".