git.cworth.org Git - cworth.org/blob - src/hgbook-git.mdwn

   1 [[!meta title="Git is easy to learn"]]
   2
   3 [[!tag git]]
   4
   5 For a while now I've had to listen to people tell me that git is
   6 somehow more complicated than other distributed source code management
   7 tools. A very recent example was what [Robert
   8 O'Callahan](http://weblogs.mozillazine.org/roc/)
   9 [said](http://weblogs.mozillazine.org/roc/archives/2007/08/mercurial.html)
  10 about a month ago talking about mercurial:
  11
  12 > Best of all the underlying model seems quite simple and I think I
  13 > understand it having read a few chapters of hgbook. I used git with
  14 > cairo without ever really understanding what git was doing.
  15
  16 This really confused me because I think I understand both git and
  17 mercurial fairly well, and I just don't see big user-visible
  18 differences in the "model" that they offer---particularly for new
  19 users. The model of each is basically identical. There are low-level
  20 implementation details. And while some argue that [repository formats
  21 matter](http://keithp.com/blogs/Repository_Formats_Matter/) that kind
  22 of low-level detail can have no bearing on the user.
  23
  24 So I went and took a look at the book he referred to, ([Distributed
  25 revision control with Mercurial](http://hgbook.red-bean.com/) by Bryan
  26 O'Sullivan). I read [Chapter 2: A tour of Mercurial: the
  27 basics](http://hgbook.red-bean.com/hgbookch2.html#x6-230002) and found
  28 it to be quite well-written and a very gentle introduction. But I also
  29 noticed that almost all of the text there could apply directly to
  30 git. When I mentioned that to roc, he said, "In that case, someone
  31 should write that text for git", and he said the [Git User's
  32 Manual](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html)
  33 didn't fit with him like this chapter did in terms of the order of
  34 introducing concepts and the level of detail used.
  35
  36 So I thought it might be an interesting project to "port" this chapter
  37 from mercurial to git. The book is freely licensed, (it's distributed
  38 under the [Open Publication
  39 License](http://www.opencontent.org/openpub/) which I found several
  40 problems with, but I'll save those for another day), so it would
  41 technically be possible. But I was also aware that the original author
  42 might not like the idea much. I talked to Bryan a bit about it and he
  43 admitted that my idea would make him "somewhat sad" but that I was
  44 obviously free to do what I wanted with the text within the license.
  45
  46 Well, I put the project off for a month because I think the feelings
  47 and desires of authors are important, in spite of what the license
  48 makes possible. And I definitely would not want to give the impression
  49 that the git community would want to leech off of the tremendous
  50 amount of hard work that Bryan has put into authoring this text.
  51
  52 But I also keep hearing more of this "git is hard to learn" and I felt
  53 that something needed to be done. So hopefully what I did last night
  54 won't offend Bryan too much. I have ported chapter 2 to git and the
  55 result is [A tour of git: the
  56 basics](http://cworth.org/hgbook-git/tour/).
  57
  58 This is not in any way an attempt to port the entire book. It's just
  59 the one chapter, and it's lost all its LaTeX goodness, (navigation,
  60 cross-referencing, PDF generation, etc.), and is just a static
  61 blog-post. I don't think it would even be a good idea technically to
  62 try to port the entire book, (even if were a good idea
  63 socially).
  64
  65 Instead, I really just wanted to attempt a demonstration that similar
  66 "easy to learn" text could describe git as well as it describes
  67 mercurial. And in fact, the exercise did point out several cosmetic
  68 deficiencies in git, (which can definitely impact the new-learner
  69 experience), and I've marked several of those with XXX comments in the
  70 text. It would be great to see many of these get fixed right away.
  71
  72 And as a route going forward for getting more complete, high-quality
  73 documentation for git, like I said, I don't think it would be wise
  74 to try to convert an entire book like Bryan's. But it might very well
  75 be a good idea to get some organizational ideas from a book like that
  76 to guide how to put together the Git User's Manual.
  77
  78 (And something I should do at some point is to read/edit the Git
  79 User's Manual. To be completely honest, I've never read it).
  80
  81 Anyway, I hope the text I have created is at least useful for
  82 somebody. And regardless of what your favorite distributed
  83 source-control tool is, just stay away from cvs and svn!