Re: Git documentation consistency

From: Greg A. Woods <woods@planix.com>
Date: Dec 9, 2009, 19:56 UTC
Message-ID: <m1NISeX-000kmuC@most.weird.com>
In-Reply-To: <e51f66da0912030822ye1541b4gb1b8a3e07eb72484@mail.gmail.com>

At Thu, 3 Dec 2009 18:22:27 +0200, Marko Kreen <markokr@gmail.com> wrote:
Subject: Re: Git documentation consistency

Show 13 quoted lines

> 
> On 12/3/09, Greg A. Woods <woods@planix.com> wrote:
> > At Wed, 02 Dec 2009 17:34:01 -0800, Junio C Hamano <gitster@pobox.com> wrote:
> >  Subject: Re: Git documentation consistency
> >  > I think you are showing ignorance here, as -? is *not* even close to
> >  > standard, nor even widely used practice at all.
> >
> >  I think I should know something about Unix command line and option
> >  parsers, having used them for some 25 years or so now.  In fact I've
> >  used most every kind of unix that ever was, and I've worked on the
> >  source to more than a few.
> 
> '?' is what getopt(3) is supposed to return for unknown options.

Indeed, which is why it cannot ever, in general, be used as a valid option with some command-specific meaning, and so why the one-line form of the usage message should always be displayed when the user explicitly gives a '-?' option (i.e. in the same way as if any unknown option is given).

If the one-line usage message is too terse to explain more complex command line syntax then '-h' (and --help) should display a short multi-line summary of the command's usage.

I guess what I should have suggested in the first place is that all Git sub-commands should respond with a one-line[*] usage message when they encounter an unknown option, such as '-?', and that they should (only) display a more detailed multi-line help summary when given '-h' or '--help' options.

I was most surprised when I didn't get a one-line usage summary from "git log -?", just getopt(3)'s error message.

[*] commands which have multiple distinct modes of operation with separate and unique command-line syntax for each mode, should of course display a one-line summary for each command mode, such as in this example:

void
usage(void)
{
	fprintf(stderr, "Usage:  %s [-abcdef]\n", getprogname());
	fprintf(stderr, "        %s [-l]\n", getprogname());
	exit(2);
}

-- 
						Greg A. Woods
						Planix, Inc.

<woods@planix.com>       +1 416 218 0099        http://www.planix.com/