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

["Greg A. Woods" <woods@planix.com>]

[-- Attachment #1: Type: text/plain, Size: 3500 bytes --]

At Wed, 2 Dec 2009 15:09:04 -0500, Jeff King <peff@peff.net> wrote:
Subject: Re: "git merge" merges too much!
> 
> I find git is much simpler to use and understand if you start "at the
> bottom" with the basic concepts (because for the most part, git is
> really a set of tools for manipulating the few basic data structures).

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 skimmed it and didn't see any inconsistency. If you have something
> specific in mind, please point it out so we can fix it.

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.


> > (git-log(1) is worse than ls(1) for having too many options, but worst
> > of all in the release I'm still using it doesn't respond sensibly nor
> > consistently with other commands when given the "-?" option.)
> 
> $ ls -?
> ls: invalid option -- '?'
> Try `ls --help' for more information.

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.


> $ git log -h
> usage: git log [<options>] [<since>..<until>] [[--] <path>...]
>    or: git show [options] <object>...

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)

-- 
						Greg A. Woods
						Planix, Inc.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 186 bytes --]