Re: [PATCH/RFC] Make help behaviour more consistent

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 11, 2013, 03:03 UTC
Message-ID: <7v1ubmd4dt.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1362937729-9050-1-git-send-email-kevin@bracey.fi>

Kevin Bracey <kevin@bracey.fi> writes:

Show 17 quoted lines

> Previously, the command "help" and the option "-h" behaved differently
> depending on whether a command was specified or not. Old user interface:
>
> Commands with no defaults show usage: "git"           "git CMD"
> To specifically request usage:        "git help"      "git CMD -h"
> To get a manual page:                 "git help git"  "git help CMD"
>
> Two significant usability flaws here:
>  - If using man, "man git" to side-step "git help" is obvious. But if
>    trying to use help.format=web, how to get the root html page? My
>    technique was "git help XXX" and click the "git(1) suite" link at the
>    bottom. "git help git" is non-obvious and apparently undocumented
>    (it's not mentioned by "git", "git help", or "git help help"...).
>
>  - Because git itself didn't support -h (and thus actually printed less
>    if you specified it), the general availability of -h for commands was
>    non-obvious. I didn't know about it until I started this patch.

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.

Having said that, I would agree that "git -h" that shows a "unknown option" error message that lists the supported command line options (just like how it reacts to "git -x") is less friendly than "git" that knows "-h" to show the short help text, and that part of the patch is a definite improvement. But other than that I do not see any "significant usablity flow" in it.

The patch seems to do a lot more than just teaching "git" to react to "-h" to give a short usage, instead of doing the generic "I do not know -h option" thing. I am not sure what merit these other changes of this patch have.

In the introductory part, you list three possibilities, but there is the fourth "git help help" to ask "git" to give me "help" about "help". Depending on where one comes from, that may also seem just as odd as "git help git" (again, I personally find neither is odd, though). Would this change help with that "usability flaw" as well?

Undecided...