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

On Fri, Sep 10 2021, Philip Oakley wrote:

On 10/09/2021 19:15, Philip Oakley wrote:

quoted

On 10/09/2021 12:28, Ævar Arnfjörð Bjarmason wrote:

quoted

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 <redacted>
---
 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>

quoted

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'".