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

From: Philip Oakley <philipoakley@iee.org>
Date: Sep 17, 2016, 19:12 UTC
Message-ID: <0B172DDC12B24525AF5FCEC4216B69E3@PhilipOakley>
In-Reply-To: <20160917183919.GJ20666@paksenarrion.iveqy.com>

From: "Fredrik Gustafsson" <iveqy@iveqy.com>

Show 6 quoted lines

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

Show 18 quoted lines

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