From: Philip Oakley <philipoakley@iee.org>
To: Junio C Hamano <gitster@pobox.com>
Cc: Jeff King <peff@peff.net>, Git List <git@vger.kernel.org>,
Johannes Schindelin <Johannes.Schindelin@gmx.de>,
Duy Nguyen <pclouds@gmail.com>
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: <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org> (raw)
In-Reply-To: <xmqqwoiu9dpb.fsf@gitster-ct.c.googlers.com>
Hi Junio,
On 13/05/2019 23:44, Junio C Hamano wrote:
> 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
next prev parent 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 git-scm.com/docs 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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org \
--to=philipoakley@iee.org \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=pclouds@gmail.com \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 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
https://80x24.org/mirrors/git.git
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).