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

Is there a cli way, especially on Git for Windows bash, to get the html man page of git(1)? I have it on my system, so can go via another page but..

All the `git <cmd> --help` appear to work, but I can't determine the correct invocation for bringing up the stupid content tracker's page in the browser. Previously I'd have expected either `git --help` or `git git --help` to work (can't remember which). The former only produces the short form -h help in the bash window, the latter says 'git' isn't a command.

cc'ing Dscho and Duy who have had recent contact with that area who may know.

On Mon, May 13, 2019 at 09:47:27PM +0100, Philip Oakley wrote:

Try "git help git".

It might be worth mentioning it in the paragraph at the end of "git help".

-Peff

Hi Peff On 13/05/2019 21:53, Jeff King wrote:

Ahh, that's the one. I'd totally forgot about that method.

True. I'll stick on my todo list, along with adding to the general usage message. Possibly "Or `git help git`."

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. (It's almost the same isue as `git --version`).

Philip

Philip Oakley <philipoakley@iee.org> writes:

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

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". Those who did "git <cmd> --help" did not bother doing so.

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

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.

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.

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

It is not immediately obvious how to use the `git help` system to show the git(1) page, with all its background and ccordinating material, such as environment variables.

Let's simply list it as the last few words of the last usage line.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org>
---
 git.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

On Tue, May 14, 2019 at 04:24:50PM +0100, Philip Oakley wrote:

I'm not sure the wording makes sense here. It sounds like you're saying, "Or use 'git help git' to read about specific subcommands or concepts." which isn't really what I think you're trying to say.

What about, "Or, use 'git help git' for a detailed guide of the Git system as a whole."

(I'm still not sure that's quite it - since `git help git` mostly details the flags you can pass to git before invoking a subcommand. But I'm not sure that `git --help` is the place to say that...)

On Tue, May 14, 2019 at 05:17:17PM -0700, Emily Shaffer wrote:

I had a similar reaction on reading Philip's patch. I think your suggestion is better. We could even shorten it to just:

  Use 'git help git' for an overview of the system.

Looking at "git help git" I actually think the DESCRIPTION section could do a better job of being a first entry-point for new readers of the documentation. But I don't think that needs to be a blocker for what we're discussing here.

Yeah, I almost suggested something like:

  Use 'git help git' for options and environment variables that affect
  all subcommands.

I'm not sure if that points people in a useful direction, or if it is getting too much into the weeds (again, probably the description section of git(1) could talk about how to find which documentation where.

I also think it should point to git-scm.com for the hyper-linked documentation, since it's less ugly than the stuff at git.github.io, but that's really getting off-topic. :)

-Peff

Hi Peff,

On 15/05/2019 02:53, Jeff King wrote:

That is a lot better. I like it. Concise and effective. I'll create a v2.

I'd agree for both points.

Interestingly, try seeing if you can use tab completion to type in 'git help git'. It's nearly as hard to find as the user-manual, which isn't a man(1) page ;-)

Philip

It is not immediately obvious how to use the `git help` system to show the git(1) page, with its overview and its background and coordinating material, such as environment variables.

Let's simply list it as the last few words of the last usage line.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org>
---
 git.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

On Wed, May 15, 2019 at 4:11 AM Philip Oakley <philipoakley@iee.org> wrote:

If you want to be consistent with the wording shown for "git help <...>", you might want s/Use/See/.

This hopefully is a final version of the usage message to show how to access the git(1) manual page.

The V3 change is Eric's suggestion to use 'See'.

I have also taken the opportunity [Patch 2/2] to pick up peff's suggestion to include the git-scm doc link, and also correct the mis-quoting of a link to the html formatted github doc pages.

Philip Oakley (2):
  git.c: show usage for accessing the git(1) help page
  Doc: git.txt: remove backticks from link and add git-scm.com/docs

 Documentation/git.txt | 3 ++-
 git.c                 | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

It is not immediately obvious how to use the `git help` system to show the git(1) page, with its overview and its background and coordinating material, such as environment variables.

Let's simply list it as the last few words of the last usage line.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org>
---
 git.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

While checking the html formatted git(1) manual page, it was noted that the link to https://git.github.io/htmldocs/git.html was formatted as code. Remove the backticks.

While at it, add the https://git-scm.com/docs link which one reviewer noted had linkable section headings.

Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Philip Oakley <philipoakley@iee.org> writes:

Good.  I just ran

	$ git grep '`https*://' Documentation/

to see if any hits I see are for the real URL the user may want to click on. There are some that are pointing at real sites, but I do not think users would want to clickon many of them while reading the documentation.

Except perhaps for these to see what's there:

Documentation/git-archimport.txt: Attempt to auto-register archives at `http://mirrors.sourcecontrol.net` Documentation/git-cvsimport.txt:* cvs2git (part of cvs2svn), `http://subversion.apache.org/`

On 16/05/2019 02:56, Junio C Hamano wrote:

I'd had a quick brows and mainly found example.com ;-) Any other excepts were at the other end of the doc relative to git(1)...

That domain is gone. Whole line should probably be removed.

Still there. Still updated - last news 2019-04-24. Could remove backticks.

Philip

On Thu, May 16, 2019 at 12:25:47PM +0100, Philip Oakley wrote:

Heh, see:

  https://public-inbox.org/git/20170420203441.mrlwbkqinub7m225@sigill.intra.peff.net/

I left it to people who actually care about arch to clean up that line and figure out if there is some useful alternative.

-Peff

On 16/05/2019 23:22, Jeff King wrote:

Thanks. I'll sit on my hands on that one then (i.e. do nothing).

Hi Emily,

On 15/05/2019 01:17, Emily Shaffer wrote:

True.

I had thought about a longer sentence, but was squeezing it in, given that we (I) had to add in the other parts of that help footnote...

It's more that we are updating the system's response to a misunderstood command, hopefully with something that includes a link to our putative top level man page. It's tricky to get to without already knowing it's there.

Philip