Convention for help in git commands?

Hi,

is there a commonly accepted way how to handle help messages in git commands? In git-mv/git-rename, there is a full help message with description of options when "-h" is given. This seems to be the Cogito way; git commands seem to be used to output an one-liner usage only, and rely on the man page otherwise.

This should be more consistent. Proposal:
* All git commands should react on command line option "-h"
for help, dumping a few lines to stderr, prefixed by "usage:", giving
the command usage without further descriptions. For the usage
output, use the base name of the command, and not the absolute
path to the binary.
* For commands which need at least one argument, the usage
is also printed, if the command is run without argument
* On a error condition, prefix the message with "error:", and
do not print out anything else (like the usage line, or things
produced by the PERL "die", which appends "at scriptname line nn").

Perhaps these things should be done only for commands of the git lightwight porcelain?

Josef

Josef Weidendorfer <Josef.Weidendorfer@gmx.de> writes:

It drives me nuts when an error message shows only basename not full path and I find out that I was running a wrong executable much later after wasting a lot of time trying to debug it. But I think "usage: " saying the basename only is user friendly and a good convention.

This is slightly debatable. I'd rather see it error out for one thing, and we might want to do a sane default given no arguments later.

Probably.

On 10/26/05, Junio C Hamano <junkio@cox.net> wrote:

This could lead to subtle bugs when git is used by porcelains. If there are going to be changes in default behaviours, let's have them soon-ish ;-)

cheers,

martin

On Tuesday 25 October 2005 22:24, you wrote:

What is the difference for a porcelain between error out, presumable with an error message, and printing the usage alone?

Is there any dependency of porcelains to the fact the e.g. "git-rev-list" currently does nothing if not called with a commit-id? Somehow I think "git-rev-list" should give an error, as the usage string (with lots of options on a line of its own ?!) requires a commit-id as argument.

BTW, the error message of "mv" is: === mv: missing file operand Try `mv --help' for more information. === What about something similar to this? Mentioning the command which triggered the error is probably a good idea.

And I would add as another convention:
* "git-cmd -h" always should give the usage, and not error out
with "fatal: Not a git repository" before.

Josef

On 10/26/05, Josef Weidendorfer <Josef.Weidendorfer@gmx.de> wrote:

Sorry! My comment was aimed at the "do a sane default given no arguments later" part of Junio's post. Error vs help messages don't affect porcelains if you check your tty and avoid spitting out a help message when invoked from a script ;-)

cheers,

martin