Add hgbook-git post

diff --git a/src/hgbook-git.mdwn b/src/hgbook-git.mdwn
new file mode 100644 (file)
index 0000000..07f8bed
--- /dev/null
+++ b/src/hgbook-git.mdwn
@@ -0,0 +1,83 @@
+[[meta title="Git is easy to learn"]]
+
+[[tag 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](http://weblogs.mozillazine.org/roc/)
+[said](http://weblogs.mozillazine.org/roc/archives/2007/08/mercurial.html)
+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](http://keithp.com/blogs/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](http://hgbook.red-bean.com/) by Bryan
+O'Sullivan). I read [Chapter 2: A tour of Mercurial: the
+basics](http://hgbook.red-bean.com/hgbookch2.html#x6-230002) 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](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html)
+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](http://www.opencontent.org/openpub/) 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](http://cworth.org/hgbook-git/tour/).
+
+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!