Re: A tour of git: the basics (and notes on some unfriendly messages)

[Carl Worth <cworth@cworth.org>]

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

On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote:
> Thanks for starting this.  It was an interesting read.

You're welcome. I hope it's useful for people.

The original goal was to demonstrate that git is no harder to learn
than mercurial. So that attempt is done, now, (whether successful or
not, I can't really judge).

Now, after getting some initial feedback, it's clear that the document
could further be improved by focusing on the "git way" of doing things
that aren't as natural in hg, (like multiple branches in a single
repository).

Rather than extending the current document, though, I think I'll just
draw up on outline based on what I think would be a good order to
introduce the topics. And then I'll see what text in the current
user's guide could plug into that outline, and what pieces might
be missing or could be improved.

At least, that's my thoughts for now. I don't know if I'll get around
to it though, (we'll have to see if I get annoyed into doing that work
like I got annoyed into this first project).

> "git help init" would give man page.  The time when the short
> help is given is when you mistype options, as in:
>
> 	$ git init --huh?

Oh, and that's *really* short output. Just a summary of the
command-line options and no description. If you look at "hg help" it
has a middle-ground option which is little more than a brief
description and a very small number of options. I think that's a
useful thing to consider for "git help". Or, perhaps just carefully
construct the man page so that this most important information is
first. See "git help clone" for example which does have a better order
than "git help init" in my opinion.

Meanwhile, "git init --huh?" is totally appropriate in just printing
usage information. That's really all you want to see if you
forget the exact name of a particular command-line option.

Trying a couple of random examples though, git could be better in some
cases:

	$ git log --pretty=complete
	fatal: invalid --pretty format: complete

That's a fairly specific error message, but no information on what I
might have meant to say. A fix should be be quite simple, (presumably
there's a list of --pretty options it just looped through and it might
as well print them out).

	$ git log --format=fuller
	fatal: unrecognized argument: --format=fuller

There's no usage given in this case at all. It should print some usage
statement, hopefully containing --pretty. Admittedly, this one is
*really* hard to fix entirely since there is a ridiculously large
number of possible options to a command like "git log". But a summary
of the most common stuff should still help.

Thanks for the various typo fixes. I've implemented those, (and the
things submitted by others). There were some particularly bad markup
problems where "git commit <file>" was being misinterpreted and
presented as "git commit" which was fairly disastrous for my intended
meaning.

Hopefully it's much better now.

-Carl

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