Re: git --help not actually showing the git(1) help page..

From: Philip Oakley <philipoakley@iee.org>
Date: May 14, 2019, 14:05 UTC
Message-ID: <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org>
In-Reply-To: <xmqqwoiu9dpb.fsf@gitster-ct.c.googlers.com>

Hi Junio, On 13/05/2019 23:44, Junio C Hamano wrote:

Show 7 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> On GfW I commonly use the `git <cmd> --help` when things go wrong, so
>> making the response to that give the right advice would be good.
> There are three levels of details ;-) "git --help" is meant as a
> shorter and sweeter version of "git help git" that is more detailed
> than "git -h".

Though that's not what happens at the moment. For the plain `git --help` case it simply defaults to the `-h` case, while for any other `git cmd --help` it does pop up the git-for-windows configured web browser manual page.

> It is conceivable for an enterprising developer to write a set of
> documentation with medium level details and make "git add --help"
> give such a medium level doc, more detailed than "git add -h" but
> more concice than "git help add".

I'd agree that there's a need for some typical usage/teaching level documentation to _complement_ the reference manual nature of the man pages. It's a chicken - egg situation for some users we/they need the bit of education before they can know they need to refer to, and understand, the respective man pages.

> Those who did "git <cmd> --help"
> did not bother doing so.
>

I tend to go with including the complementary usage/teaching aspects in a distinct section of the man pages, though some of this is based on examples from other software, e.g. Matlab for design/systems engineers.

A simplistic patch for just the 'usage' message to follow.

Philip