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 behavior 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 Finding the Source of a Bug, 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 behavior you’re seeing is consistent and reproducible.
Get Mercurial: The Definitive Guide now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
