On 11/03/2013 05:03, Junio C Hamano wrote:
Hmm, I feel more confused than convinced after reading the above
three times.  Perhaps that is because I am too used to the way how
"git" potty itself behaves, especially the part that "git help git"
is the way to ask "git" (the first token on the command line) to
give me "help" about "git" (the second) itself.

But you are nowhere told that "git help" will give you information on any topic other than Git commands. Starting from just typing "git", all you are told is that you can type "git help <command>". Given that information, you could at least logically deduce that "git help help" will give you help on "git help". (Not that it would help anyway - even git-help.txt doesn't say that you can specify anything other than a Git command, like "git" or "cli". But sounds like Philip's already on there case there).

If you can figure out "man git" for yourself (and if it's available - Windows?) then from there you're explicitly told how to directly access all the other docs using man itself, including gitrevisions(7), etc.

And having gotten to "man gitrevisions", I figured out that "git help revisions" could get to the HTML equivalent. Not documented, but at least fits the pattern, give or take a hyphen. But I never figured out "git help git", until I read the source. Why do I need to add the extra "git" to the help command for that page, and that page only? "git" isn't a Git command, and there's no "man gitgit" topic! Even if I explicitly try to point explicitly that I want a web page with "git help -w", I don't get it...

I think at the very minimum you need to make it explicitly clear right up front that "git help git" is available:

   See 'git help git' for more information on Git
See 'git help <command>' for more information on a specific command.

Seems ugly though. I'm at a loss to understand why "git help", the manual launching command, shouldn't by default simply launch the root of the manual tree, rather than replicate the behaviour of "git"/"git --help".

And something needs to be done to advertise the general existence of usage on commands. "-h" is currently hidden on page 4 of "man gitcli". (Is it anywhere else?) I've managed to avoid finding out about it for years! Checking a few people around me, none of them knew about it either.

At the minute "git" tells you about "git --help", which shows usage, but "git add --help" launches the manual. (Huh?) Given that, I always assumed there was no usage available for individual commands - if there was usage, surely it would be there on --help, like on "git". Never occurred to me it would be there under "-h" instead.

So how about going further than that patch, and making it even simpler. Collapse --help and -h to be synonyms. Then under either spelling, --help|-h always shows usage for "git" or "git <command>", as per GNU guidelines.

Then the manual launch only happens for "git help ..." and, "git help" on its own launches the root. And the output of "git [--help]" ends with:

   See 'git help [<command>]' for more information.


To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to