Why are there multiple ways to get the manual in Git?

Why are there multiple ways to get the manual in Git?

[Andrew Johnson]

Hi,

I was curious as to why the developers of Git decided to have three
methods to get the manual for a verb. I am a developer who strives to
understand Git to its fullest extent, and will share any information
given on this question.

While reading Pro Git 2nd Ed. I came across these three methods:

$ git help <verb>
$ git <verb> --help
$ man git-<verb>

I tested all three to confirm they were equivalent.

What was the motivation behind the complication, if any? I presume
most developers would not provide multiple commands that do the same
thing for absolutely no reason, so I led myself to ask this question.

Respectfully,
Andrew Johnson

Re: Why are there multiple ways to get the manual in Git?

[Fredrik Gustafsson]

On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:
> $ git help <verb>
> $ git <verb> --help
> $ man git-<verb>
> 
> I tested all three to confirm they were equivalent.

While I'm not able to answer your question, I can shred a little light
about them not being equal. For example using a windows machine

$ man git <verb>

does not work and

$ git help <verb>

opens a webbrowser instead of a man page. Using a unix system I would
however assume that

$ man git <verb>

would work since it's the standard way of getting help on those systems.

-- 
Fredrik Gustafsson

phone: +46 733-608274
e-mail: iveqy@iveqy.com
website: http://www.iveqy.com

Re: Why are there multiple ways to get the manual in Git?

[Philip Oakley]

From: "Fredrik Gustafsson" <iveqy@iveqy.com>
> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:
>> $ git help <verb>
>> $ git <verb> --help
>> $ man git-<verb>
>>
>> I tested all three to confirm they were equivalent.

It is (IIUC) in a general sort of way "by design", and a little bit of 
accident.

>
> While I'm not able to answer your question, I can shred a little light
> about them not being equal. For example using a windows machine
>
> $ man git <verb>
>
> does not work and
>
> $ git help <verb>
>
> opens a webbrowser instead of a man page. Using a unix system I would
> however assume that
>
> $ man git <verb>
>
> would work since it's the standard way of getting help on those systems.
>
> -- 

Historically git was a set of shell scripts named git-*, so each stood 
alone.

Then there was the great consolidation (around V1.6?) which created the 
modern `git <cmd>' approach, with every command normally having  -h 
and --help options for short form usage and long form man pages.

The option capability became standardised. Also a `git help <cmd>` command 
was created. Underneath there are still the (backward compatible) git-* 
forms. The help command allowed selection of display type, so that on 
Unix/Linux man was the norm, while an --html (or --web) option is available 
for those who like the pretty browser view

The help commnad just converts the parameters to achieve the expected 
display (with various fallbacks if the command or guide is missing, etc)

Meanwhile on Windows, the man facility was not ported as part of git, so it 
defaults to the --web version. If you are on Windows, and download the SDK 
as well you can install the man viewer and other goodies

--
Philip

Re: Why are there multiple ways to get the manual in Git?

[Christian Couder]

On Sat, Sep 17, 2016 at 8:39 PM, Fredrik Gustafsson <iveqy@iveqy.com> wrote:
> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:
>> $ git help <verb>
>> $ git <verb> --help
>> $ man git-<verb>
>>
>> I tested all three to confirm they were equivalent.

Maybe it will be easier to understand if you try:

$ git help help

or

$ git help --help

or

$ man git-help

:-)

> While I'm not able to answer your question, I can shred a little light
> about them not being equal. For example using a windows machine
>
> $ man git <verb>

(It should be "git-<verb>" above.)

> does not work and
>
> $ git help <verb>
>
> opens a webbrowser instead of a man page.

Yeah, it is one of the reasons.
There are systems where "man" is not the standard ways to get help,
and text on the command line is not the prefered format for help
content.
So the "git help" command has different default depending on the OS to
better suit user expectations on each OS.
This way people can just be teached to use "git help" and that will do
something sensible everywhere.

> Using a unix system I would
> however assume that
>
> $ man git <verb>

(Again it should be "git-<verb>" above.)

> would work since it's the standard way of getting help on those systems.

Yeah, so we need that to work to make people happy on unix systems.

Another reason is that "git help" provides more configurability and
more features like its -a and -g options.
It could provide even more in the future, like options to search in
the documentation.

Re: Why are there multiple ways to get the manual in Git?

[Jakub Narębski]

W dniu 17.09.2016 o 20:39, Fredrik Gustafsson pisze:
> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:

>> $ git help <verb>
>> $ git <verb> --help
>> $ man git-<verb>
>>
>> I tested all three to confirm they were equivalent.
> 
> While I'm not able to answer your question, I can shred a little light
> about them not being equal. For example using a windows machine
> 
> $ man git-<verb>
> 
> does not work and
> 
> $ git help <verb>
> 
> opens a webbrowser instead of a man page. Using a unix system I would
> however assume that
> 
> $ man git-<verb>
> 
> would work since it's the standard way of getting help on those systems.

There is also additional difference.  There are help pages which are
not about specific Git command, but about concepts (gitcli, gitrevisions,
githooks, gitrepository-layout, gitglossary), or about files (gitignore,
gitattributes, to some extent githooks).

Those are only accessible with `git help <concept>` or, on OS with
installed 'man', also `man <gitconcept>`.

Just FYI
-- 
Jakub Narębski

Re: Why are there multiple ways to get the manual in Git?

[Philip Oakley]

From: "Jakub Narębski" <jnareb@gmail.com>
>W dniu 17.09.2016 o 20:39, Fredrik Gustafsson pisze:
>> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:
>
>>> $ git help <verb>
>>> $ git <verb> --help
>>> $ man git-<verb>
>>>
>>> I tested all three to confirm they were equivalent.
>>
>> While I'm not able to answer your question, I can shred a little light
>> about them not being equal. For example using a windows machine
>>
>> $ man git-<verb>
>>
>> does not work and
>>
>> $ git help <verb>
>>
>> opens a webbrowser instead of a man page. Using a unix system I would
>> however assume that
>>
>> $ man git-<verb>
>>
>> would work since it's the standard way of getting help on those systems.
>
> There is also additional difference.  There are help pages which are
> not about specific Git command, but about concepts (gitcli, gitrevisions,
> githooks, gitrepository-layout, gitglossary), or about files (gitignore,
> gitattributes, to some extent githooks).
>
> Those are only accessible with `git help <concept>` or, on OS with
> installed 'man', also `man <gitconcept>`.

The `git revisions --help` does work ;-) But like you say, its apparent 
"command" name is 'gitrevisions'.

Thus real commands gave a git-command name, while concepts have a gitconcept 
name which can then be found via the man command.

--
Philip 

Re: Why are there multiple ways to get the manual in Git?

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> The `git revisions --help` does work ;-)

Not anymore ;-)

I think Ralf Thielow fixed it recently.

Re: Why are there multiple ways to get the manual in Git?

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
> 
>> The `git revisions --help` does work ;-)
> 
> Not anymore ;-)
> 
> I think Ralf Thielow fixed it recently.

hmm, I sort of though it would still work with a valid guide.

I'd only checked with my last GfW version.
--
hey ho
Philip