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

[Carl Worth <cworth@cworth.org>]

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

I recently "ported" the introductory chapter of Bryan O’Sullivan's
Distributed revision control with Mercurial[1] from mercurial to
git. The result is here:

	A tour of git: the basics
	http://cworth.org/hgbook-git/tour/

I did this as an attempt to demonstrate that git and mercurial are
fundamentally equally "easy to learn", and definitely not as an effort
to try to leech Bryan's hard work, (nor would I even want to encourage
that kind of thing). More of my rationale is available here:

	Git is easy to learn
	http://cworth.org/hgbook-git/

I have two reasons for sharing this with the list. First, I'd
appreciate any feedback that the knowledgable readers on this list
might have. If anything could be made more clear, or if I have factual
mistakes in the text, I'd definitely like to fix those. Please let me
know.

Second, the process of porting the document highlighted a few issues
in git that I think would be nice to fix. I only noticed fairly
cosmetic issues, but I included them as XXX comments in the text. I'll
share them here as well: (all of these are with git 1.5.3.2).

 * Is "git help" actually a builtin thing or just a way to call out to
   "man"? Does it work at all in Windows ports of git, for example?
   (OK, so that one's just a question, not an issue it git)

 * Would it make sense to put much smaller amounts of text into "git
   help" than the entire man page? For example, maybe just the
   description and the most common options or maybe an example? Maybe
   do something like "git -v help" for more details? See my text for
   more on this, or compare "git help init" to "hg help init" and "hg
   -v help init".

  * The output from a git-clone operating locally is really confusing:

	$ git clone hello hello-clone
	Initialized empty Git repository in /tmp/hello-clone/.git/
	0 blocks

    Empty? Didn't I just clone it? What does "0 blocks" mean?

  * git-log by default displays "Date" that is the author date, but
    also only uses committer date for options such as --since. This is
    confusing.

  * It would be nice if all short-format options, (like "git log -p"), were
    also available in a long-format option, (like "git log --patch").

  * There's a ton of extraneous output from git-fetch. I would love to
    see it reduced to a single-line progress bar, (even if a
    multiple-staged progress bar). I'm imagining a final line
    something like:

	Computing (100%) Transferring (100%)

    But you can imagine more accurate words than those, (I'm not even
    sure what all of the things mean that git-fetch is currently
    reporting progress on).

Obviously some of these would be pretty easy, and I should jump into
the git implementation to try them out, but I've just been typing this
stuff as fast as I could, and I'm about to go campout in the rain and
hail now, (fun, fun!), so I wanted to get this out before I forgot
anything.

Thanks in advance for any of your time, attention, or feedback, (and
especially any patches!).

-Carl

[1] http://hgbook.red-bean.com/
	

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