Distributed revision control is a relatively new territory, and has thus far grown due to people’s willingness to strike out into ill-charted territory.
I am writing a book about distributed revision control because I believe that it is an important subject that deserves a field guide. I chose to write about Mercurial because it is the easiest tool to learn the terrain with, and yet it scales to the demands of real, challenging environments where many other revision control tools fail.
I am releasing this book while I am still writing it, in the hope that it will prove useful to others. I also hope that readers will contribute as they see fit.
This book takes an unusual approach to code samples. Every example is “live”—each one is actually the result of a shell script that executes the Mercurial commands you see. Every time an image of the book is built from its sources, all the example scripts are automatically run, and their current results compared against their expected results.
The advantage of this approach is that the examples are always accurate; they describe exactly the behaviour of the version of Mercurial that’s mentioned at the front of the book. If I update the version of Mercurial that I’m documenting, and the output of some command changes, the build fails.
There is a small disadvantage to this approach, which is that the dates and times you’ll see in examples tend to be “squashed” together in a way that they wouldn’t be if the same commands were being typed by a human. Where a human can issue no more than one command every few seconds, with any resulting timestamps correspondingly spread out, my automated example scripts run many commands in one second.
As an instance of this, several consecutive commits in an example can show up as having occurred during the same second. You can see this occur in the bisect example in section 9.5, for instance.
So when you’re reading examples, don’t place too much weight on the dates or times you see in the output of commands. But do be confident that the behaviour you’re seeing is consistent and reproducible.
This book is licensed under the Open Publication License, and is produced entirely using Free Software tools. It is typeset with LATEX; illustrations are drawn and rendered with Inkscape.
The complete source code for this book is published as a Mercurial repository, at http://hg.serpentine.com/mercurial/book.