git

For a while now I've had to listen to people tell me that git is somehow more complicated than other distributed source code management tools. A very recent example was what Robert O'Callahan said about a month ago talking about mercurial:

Best of all the underlying model seems quite simple and I think I understand it having read a few chapters of hgbook. I used git with cairo without ever really understanding what git was doing.

This really confused me because I think I understand both git and mercurial fairly well, and I just don't see big user-visible differences in the "model" that they offer---particularly for new users. The model of each is basically identical. There are low-level implementation details. And while some argue that repository formats matter that kind of low-level detail can have no bearing on the user.

So I went and took a look at the book he referred to, (Distributed revision control with Mercurial by Bryan O'Sullivan). I read Chapter 2: A tour of Mercurial: the basics and found it to be quite well-written and a very gentle introduction. But I also noticed that almost all of the text there could apply directly to git. When I mentioned that to roc, he said, "In that case, someone should write that text for git", and he said the Git User's Manual didn't fit with him like this chapter did in terms of the order of introducing concepts and the level of detail used.

So I thought it might be an interesting project to "port" this chapter from mercurial to git. The book is freely licensed, (it's distributed under the Open Publication License which I found several problems with, but I'll save those for another day), so it would technically be possible. But I was also aware that the original author might not like the idea much. I talked to Bryan a bit about it and he admitted that my idea would make him "somewhat sad" but that I was obviously free to do what I wanted with the text within the license.

Well, I put the project off for a month because I think the feelings and desires of authors are important, in spite of what the license makes possible. And I definitely would not want to give the impression that the git community would want to leech off of the tremendous amount of hard work that Bryan has put into authoring this text.

But I also keep hearing more of this "git is hard to learn" and I felt that something needed to be done. So hopefully what I did last night won't offend Bryan too much. I have ported chapter 2 to git and the result is A tour of git: the basics.

This is not in any way an attempt to port the entire book. It's just the one chapter, and it's lost all its LaTeX goodness, (navigation, cross-referencing, PDF generation, etc.), and is just a static blog-post. I don't think it would even be a good idea technically to try to port the entire book, (even if were a good idea socially).

Instead, I really just wanted to attempt a demonstration that similar "easy to learn" text could describe git as well as it describes mercurial. And in fact, the exercise did point out several cosmetic deficiencies in git, (which can definitely impact the new-learner experience), and I've marked several of those with XXX comments in the text. It would be great to see many of these get fixed right away.

And as a route going forward for getting more complete, high-quality documentation for git, like I said, I don't think it would be wise to try to convert an entire book like Bryan's. But it might very well be a good idea to get some organizational ideas from a book like that to guide how to put together the Git User's Manual.

(And something I should do at some point is to read/edit the Git User's Manual. To be completely honest, I've never read it).

Anyway, I hope the text I have created is at least useful for somebody. And regardless of what your favorite distributed source-control tool is, just stay away from cvs and svn!