Mercurial: The Definitive Guide

If you’ve looked at the Mercurial book site in the past 24 hours, you’ll have noticed that both its look and the name of the book have changed.

First, the cosmetic news. The change in appearance is due to my switching over to the system I used to publish Real World Haskell. I’ve always made the source code to the Mercurial book available, but now it includes the source of the Django app and jQuery code that drives the comment system. So if you’re writing an online book, have at it!

The change in title occurs because O’Reilly Media is going to publish the book in a few months, once I’ve tidied it up (with, I hope, your help!). The content is still licensed under the OPL, so you remain free to use and modify my work under remarkably liberal terms.

O’Reilly and I are donating my royalties on this book to the Software Freedom Conservancy, so if you buy a hardcopy, you’ll be helping one of the finest causes in the software world.

This is a great time to get involved in the production and polishing of the book, and as I did with the Haskell book, I’ll give credit to everyone who provides their name. If you’re interested in helping out, be it by contributing content, corrections, typo fixes, or suggestions, you have two easy ways to do so:

  • Clone a copy of the source tree and start sending patches
  • Use the comment system on the web site to point out errors and omissions, or to make suggestions
  • For bigger stuff, report an issue

So please dive on in, and let’s make this book an even more outstanding resource for the Mercurial community!

Posted in mercurial
15 comments on “Mercurial: The Definitive Guide
  1. Daniel says:


    This is a LOT of work that you are giving out. Just wanted to let you know there are some of us that GREATLY appreciate your work.


  2. Bryan,
    This is great news. Your Mercurial book really helped me improve my daily use of Mercurial. I look forward to have a hardcopy. Since then, I’ll be happy to contribute back. Thanks.

  3. It’s great to see the book improving again. I hope that’ll also entail you being more active in the hg community again.

    Are the sales going specifically to the Mercurial part of the SFC, or just to the SFC in general?

  4. A typo:
    > So if you’re writing an online book, have [a look] at it!

  5. Greg says:


    You are a scholar and a gentleman. Keep up the amazing work!

  6. I already know your book, so what gripped me first wasn’t it content, but the comment system.

    I just love that!

    I searched for _exactly this_ for years (for shadowtalk…), but everything I found had flaws which made it unusable for me.

    What’s the license of your comment system? (GPL compatible?)

  7. John Vandervort says:

    Great Book! Congrats. It was very helpful.
    Are the links in the rss comment feeds supposed to be going to

  8. Paddy3118 says:

    I’ve just started reading the online edition, and would just say that it would be nice if the comment indicator was a different pale colour to indicate when people had actually made some comments on a paragraph.

    – Paddy.

  9. Mark Blakeney says:

    Bryan, I think something is badly broken in the new book. I’m a mercurial newbie and tried to follow the tutorial but there are too many errors. See chapter 2 where I left one comment (along with other people) describing some blatant mismatches between the figures and the words. Something is also wrong with the comment system as after my first comment it now always just hangs when I try to enter another comment. So note there are errors from the 1st figure on in chapter 2 but I could not comment there about them.

  10. Mark Blakeney says:

    Hi Bryan, I see today that you have fixed some of the errors in chapter 2 I refer to above. There is at least one other blatant error but I can’t comment on the site because the comment system now just hangs for me.

    First error on chapter 2 page occurs in the very first figure on the page. In the line “cp ../new-hello.c hello.c” where does new-hello.c come from? It was not created in the previous chapter. Further down you say you have fixed the merge abort example and you say to “notice that it has both of our former heads as its parents” but the bottom of the figure has merely been cut off so the result can not be seen at all.

  11. Mark, there’s a comment describing what new-hello.c is in the actual shell example. Is that not clear enough? If so, I’ll find some other way to flag it.

  12. Mark Blakeney says:

    There’s a shell comment “The file new-hello.c is lightly edited”. Sorry, that sentence did/does not make sense. More to the point however is that the file is copied from the parent directory which is not a repo area. Where did that source file magically come from? I struck this confusing point and the later merge abort example and it just seemed to me the tutorial examples had got out of sync with the words in some kind of documentation build error.

    I’m here because one of the significant advantages stated by Google Code when they recently choose mercurial over git was its documentation, in particular they quoted your book (see So, seeing these simple errors in an early chapter, leads me to conclude they must be very recently introduced, possibly by this new django implementation. Surely these errors have not always existed?

    Thanks for this great resource however and thanks for commenting back to me here. Have you looked at why the comments don’t work reliably on the book site?

  13. Mark, what happened with some of the infelicities was that Mercurial itself changed, and it had been a while since I updated the text of the book. Thanks for spotting them.

    I’ve tidied up that example to be a little more obvious.

  14. Lukas says:

    Thanks a lot for that guide. It helps me understanding the ideas behind mercurial.

  15. Nicolas says:

    I’m *so* borrowing your comment system! Thanks for giving the source!

Leave a Reply

Your email address will not be published. Required fields are marked *