hgbook
changeset 200:9bba958be4c6
Mention automatic example generation.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Apr 18 11:55:39 2007 -0700 (2007-04-18) |
parents | 58e3a6c76725 |
children | 80fc720338a5 |
files | en/preface.tex en/undo.tex |
line diff
1.1 --- a/en/preface.tex Mon Apr 16 17:37:27 2007 -0700 1.2 +++ b/en/preface.tex Wed Apr 18 11:55:39 2007 -0700 1.3 @@ -18,6 +18,39 @@ 1.4 it will prove useful to others. I also hope that readers will 1.5 contribute as they see fit. 1.6 1.7 +\section{About the examples in this book} 1.8 + 1.9 +This book takes an unusual approach to code samples. Every example is 1.10 +``live''---each one is actually the result of a shell script that 1.11 +executes the Mercurial commands you see. Every time an image of the 1.12 +book is built from its sources, all the example scripts are 1.13 +automatically run, and their current results compared against their 1.14 +expected results. 1.15 + 1.16 +The advantage of this approach is that the examples are always 1.17 +accurate; they describe \emph{exactly} the behaviour of the version of 1.18 +Mercurial that's mentioned at the front of the book. If I update the 1.19 +version of Mercurial that I'm documenting, and the output of some 1.20 +command changes, the build fails. 1.21 + 1.22 +There is a small disadvantage to this approach, which is that the 1.23 +dates and times you'll see in examples tend to be ``squashed'' 1.24 +together in a way that they wouldn't be if the same commands were 1.25 +being typed by a human. Where a human can issue no more than one 1.26 +command every few seconds, with any resulting timestamps 1.27 +correspondingly spread out, my automated example scripts run many 1.28 +commands in one second. 1.29 + 1.30 +As an instance of this, several consecutive commits in an example can 1.31 +show up as having occurred during the same second. You can see this 1.32 +occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect}, 1.33 +for instance. 1.34 + 1.35 +So when you're reading examples, don't place too much weight on the 1.36 +dates or times you see in the output of commands. But \emph{do} be 1.37 +confident that the behaviour you're seeing is consistent and 1.38 +reproducible. 1.39 + 1.40 \section{Colophon---this book is Free} 1.41 1.42 This book is licensed under the Open Publication License, and is
2.1 --- a/en/undo.tex Mon Apr 16 17:37:27 2007 -0700 2.2 +++ b/en/undo.tex Wed Apr 18 11:55:39 2007 -0700 2.3 @@ -26,7 +26,9 @@ 2.4 each modification of a repository as a \emph{transaction}. Every time 2.5 you commit a changeset or pull changes from another repository, 2.6 Mercurial remembers what you did. You can undo, or \emph{roll back}, 2.7 -exactly one of these actions using the \hgcmd{rollback} command. 2.8 +exactly one of these actions using the \hgcmd{rollback} command. (See 2.9 +section~\ref{sec:undo:rollback-after-push} for an important caveat 2.10 +about the use of this command.) 2.11 2.12 Here's a mistake that I often find myself making: committing a change 2.13 in which I've created a new file, but forgotten to \hgcmd{add} it. 2.14 @@ -77,6 +79,7 @@ 2.15 all you need to undo this mistake. 2.16 2.17 \subsection{Rolling back is useless once you've pushed} 2.18 +\label{sec:undo:rollback-after-push} 2.19 2.20 The value of the \hgcmd{rollback} command drops to zero once you've 2.21 pushed your changes to another repository. Rolling back a change 2.22 @@ -455,6 +458,7 @@ 2.23 changesets. Kind of an important omission. 2.24 2.25 \section{Finding the source of a bug} 2.26 +\label{sec:undo:bisect} 2.27 2.28 While it's all very well to be able to back out a changeset that 2.29 introduced a bug, this requires that you know which changeset to back