mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Philip Oakley <>
To: Junio C Hamano <>
Cc: Jeff King <>, Git List <>,
	Johannes Schindelin <>,
	Duy Nguyen <>
Subject: Re: git --help not actually showing the git(1) help page..
Date: Tue, 14 May 2019 15:05:16 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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


  reply	other threads:[~2019-05-14 14:05 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-13 20:47 git --help not actually showing the git(1) help page Philip Oakley
2019-05-13 20:53 ` Jeff King
2019-05-13 21:55   ` Philip Oakley
2019-05-13 22:44     ` Junio C Hamano
2019-05-14 14:05       ` Philip Oakley [this message]
2019-05-14 15:24         ` [PATCH] git.c: show usage for accessing " Philip Oakley
2019-05-15  0:17           ` Emily Shaffer
2019-05-15  1:53             ` Jeff King
2019-05-15  6:43               ` Philip Oakley
2019-05-15  8:11                 ` [PATCH v2] " Philip Oakley
2019-05-15  8:14                   ` Eric Sunshine
2019-05-15 22:47                     ` [PATCH v3 0/2] " Philip Oakley
2019-05-15 22:47                       ` [PATCH v3 1/2] git.c: show usage for " Philip Oakley
2019-05-15 22:47                       ` [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add Philip Oakley
2019-05-16  1:56                         ` Junio C Hamano
2019-05-16 11:25                           ` Philip Oakley
2019-05-16 22:22                             ` Jeff King
2019-05-16 23:09                               ` Philip Oakley
2019-05-15  6:36             ` [PATCH] git.c: show usage for accessing the git(1) help page Philip Oakley

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).