How do Git on Linux users launch/read the user-manual?

As a Windows user, when I want to look at the Git user-manual, I tend to `git help git`, which on Git for Windows opens the users  default browser. For me, it's at C:/Program Files/Git/mingw64/share/doc/git-doc/git.html.

I can then browse that directory to find user-manual.html and open it from there (because I know it is there!).

How do Git on Linux users launch/read the user-manual?

Essentially the user manual isn't accessible from Git, and really it should be.

However it's not a formatted as a man page so some other access mechanism is needed, compatible with Linux, and Windows users. It would be nice if it was part of the `git help -g` list.

Excuse my ignorance for not knowing how linux users should access this usefully curated doc.

Question promoted by Philippe's recent inclusion of the FAQ to the doc list [1]

Philip

[1] https://lore.kernel.org/git/xmqqimgqwqif.fsf@gitster.c.googlers.com/T/#t

Philip Oakley <philipoakley@iee.email> writes:

Start from the same starting point

$ git help -w git

and then navigate to the link to "Git User Manual"?

Hi Junio,

On 20/05/2020 22:27, Junio C Hamano wrote:

And then what? Is it always some .html viewer, or viewing the raw .txt file, or something else? (it isn't the man view..) -- Philip

Philip Oakley <philipoakley@iee.email> writes:

"git help -w" is showing stuff in the web browser, and when you open git(1), which is rendered in HTML, and visit "Git User's Manual" link in it, the experience would be no different from those viewing via the browser on Windows---$(htmldir)/user-manual.html is where the rendered HTML version of the user-manual is.

Or are you asking something else?

On 21/05/2020 00:56, Junio C Hamano wrote:

I was more coming at the question from the other direction, that is, about accessing, normally, the git manuals, and discovering the desired information, both for existing and new users.

In your example, you needed to include the extra -w option, specific to this 'special' manual, while all the other hundreds of man pages would be accessed without it (even on Windows, as the config is set by default).

I also get the impression that many linux users may be using 'man' just as much as much as 'git help' but neither (without realising the need for the extra option) would show the user-manual (.txt|.html).

We do have the advised `git help -g` to list the concept guides, but that doesn't advise about the user-manual, which surely we should mention to those asking for help (without them needing a long journey of discovery). The list does include `git everyday`...

I appreciate that, for some, there is a view that new users are other peoples problems and that knowledgable users already know, roughly,  which command they wish to use and thus then peruse the appropriate reference manual to confirm the correct form for their command. I'd rather we direct uncertain users to their appropriate guide quickly, using their expected viewer method. Hence the question.

Philip

Philip Oakley <philipoakley@iee.email> writes:

For those who have help.format set to html, it is no "extra" thing required. I said "git help -w" so that people would understand what I meant regardless of their personal settings are.

Or are you saying that nobody on Linux uses the html format? I should stop keeping the git-htmldocs.git repository up to date, if that is the case, but I suspect it is not.

Or are you volunteering to update the mark-up (if necessary) so that user-manual would become part of "man" ("man git-user-manual", perhaps) suite? That would be an excellent suggestion.

Whatever proposal/volunteering comes from you after your question is answered would be quite interesting. Hopefully that would be one that is beneficial to the project as a whoel ;-)

Thanks.

Junio C Hamano <gitster@pobox.com> writes:

Having said that, I am not sure the way the material covered by the user-manual is presented in is a good match for the manpage format in the first place. Don't modern manpage viewers, or generic pagers that can display textual contents (which may happen to be the "man 1 git" output), or even a terminal enumrator that may happen to be showing the output of such a pager, notice a URL and allow users to activate on it (i.e. visit the HTML document the URL points at, by opening the URL in an already-running browser, or in a new instance of a browser)? So perhaps a better solution for those who live in a text terminal and view our documentation via "git help -m git" or even "man git" would be to write a full URL to reach a version of user manual available to the user, perhaps with file:/// URL "as text" in the man output? Then you do not have to reformat the user manual in the manpage format or anything silly like that.

Hmm?

Hi Junio,

On 21/05/2020 23:29, Junio C Hamano wrote:

No, I wasn't volunteering to update the user-manual to man format ;-)

I had previously suggested that an intermediate man page could provide the user link to the user-manual proper [1] but it wasn't really accepted.

True. A man page has a different focus.

This was the same question I was asking at the beginning (given that I'm 97.7% on Windows). Would a modern man viewer, if given the none existent user-manual man page path, try for the an html equivalent - I'm not thinking it does:

root@Philip-Win10:~# git help git             #works!

root@Philip-Win10:~# git help user-manual No manual entry for gituser-manual root@Philip-Win10:~#

(WSL - Ubuntu - git v2.23.0)

Maybe the help code (when using the -m code path) should test for the man file existence first, and revert to the -w code path as a fall back (with warning/advice)?  Just a thought.

It could provide a fall through for lots of other potential html help files, when stored in the correct path (if that's sensible for the various OS usages).

-- Philip

[1] https://lore.kernel.org/git/5561391C5EED4114A90C35518558A267@PhilipOakley/T/#u