Re: Git documentation consistency (was: "git merge" merges too much!)

At Wed, 2 Dec 2009 15:09:04 -0500, Jeff King <peff@peff.net> wrote:
Subject: Re: "git merge" merges too much!

I think that's the problem actually -- I don't really want to know too much about how it works under the hood (yet), I just want to use it in the most effective way for my purposes.

There's lots of talk about using Git as the basis for a true high-level VCS and SCM system, yet it doesn't look to me that anyone has created such a VCS or SCMS using Git.

I think anyone who's been participating on this list for any significant amount of time is far too close to the subject to be able to serve as a candid independent technical editor who could really help clean things up and make the documentation much more consistent. Obviously such an editor would also require the help of experts at all the details too. :-)

Unfortunately I'm not a very good technical editor, and I don't really have time to devote to doing such editing of documentation either.

Please keep in mind all the world is not GNU:

	$ ls -?
	ls: unknown option -- ?
	usage: ls [-AaBbCcdFfghikLlmnopqRrSsTtuWwx1] [file ...]

My point was that _most_ other Git sub-commands already do respond to "-?" sensibly with real, helpful, information; usually a summary of the command options and parameters.

I.e. this is yet another form of inconsistency in "documentation" in Git. :-)

The reference to "ls" was just as a comparison with it's somewhat extensive variety of options. In fact "git log" is way more complex than "ls" because its parameters are not all just simple flags like those for "ls" -- they often have their own parameters too.

Indeed, so why the heck can't it do something similar with '-?'. That's just sloppy programming, no? Most other commands know '-?', and despite the silliness with GNU Ls, use of '-?' to request summary usage information is pretty much a de facto standard for unix commands.

Your point about mentioning "--help" in the summary usage information is a good one though -- especially for a command with a very complex set of command-line parameters. However that alone isn't sufficient -- users still need the summary as that alone helps trigger associations and may be sufficient to allow a user to proceed quickly to get the command to do what they want.

(the whole "fatal: not a git repository" error for "git foo -[h?]" handling is also a rather silly one -- but I guess when something grows quickly and from many inputs there's not always time to keep some of these basic things clean and consistent)