Hi Junio,
On 13/05/2019 23:44, Junio C Hamano wrote:
Philip Oakley <philipoakley@xxxxxxx> 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
