From: Carl Worth Date: Fri, 28 Sep 2007 22:48:44 +0000 (-0700) Subject: Add hgbook-git post X-Git-Url: https://git.cworth.org/git?p=cworth.org;a=commitdiff_plain;h=3116bca7e70795d30a8616919d612d33f50c344a Add hgbook-git post --- diff --git a/src/hgbook-git.mdwn b/src/hgbook-git.mdwn new file mode 100644 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!