1.1 --- a/en/Makefile	Wed Nov 15 13:10:30 2006 -0800
     1.2 +++ b/en/Makefile	Wed Nov 15 15:59:41 2006 -0800
     1.3 @@ -18,7 +18,8 @@
     1.4  	srcinstall.tex \
     1.5  	template.tex \
     1.6  	tour-basic.tex \
     1.7 -	tour-merge.tex
     1.8 +	tour-merge.tex \
     1.9 +	undo.tex
    1.10  
    1.11  image-sources := \
    1.12  	filelog.svg \
    1.13 @@ -54,6 +55,7 @@
    1.14  	mq.tarball \
    1.15  	mq.tools \
    1.16  	mq.tutorial \
    1.17 +	rollback \
    1.18  	template.simple \
    1.19  	template.svnstyle \
    1.20  	tour \

     2.1 --- a/en/concepts.tex	Wed Nov 15 13:10:30 2006 -0800
     2.2 +++ b/en/concepts.tex	Wed Nov 15 15:59:41 2006 -0800
     2.3 @@ -110,6 +110,7 @@
     2.4  arbitrary binary contents; it doesn't need to treat text as special.
     2.5  
     2.6  \subsection{Safe operation}
     2.7 +\label{sec:concepts:txn}
     2.8  
     2.9  Mercurial only ever \emph{appends} data to the end of a revlog file.
    2.10  It never modifies a section of a file after it has written it.  This

     3.1 --- a/en/daily.tex	Wed Nov 15 13:10:30 2006 -0800
     3.2 +++ b/en/daily.tex	Wed Nov 15 15:59:41 2006 -0800
     3.3 @@ -165,6 +165,8 @@
     3.4  file.  It treats these copied files specially when you merge your work
     3.5  with someone else's.
     3.6  
     3.7 +\subsection{The results of copying during a merge}
     3.8 +
     3.9  What happens during a merge is that changes ``follow'' a copy.  To
    3.10  best illustrate what this means, let's create an example.  We'll start
    3.11  with the usual tiny repository that contains a single file.
    3.12 @@ -307,6 +309,13 @@
    3.13  something you might expect to ``simply work,'' but not all revision
    3.14  control systems actually do this.)
    3.15  
    3.16 +Whereas having changes follow a copy is a feature where you can
    3.17 +perhaps nod and say ``yes, that might be useful,'' it should be clear
    3.18 +that having them follow a rename is definitely important.  Without
    3.19 +this facility, it would simply be too easy for changes to become
    3.20 +orphaned when files are renamed.
    3.21 +
    3.22 +
    3.23  %%% Local Variables: 
    3.24  %%% mode: latex
    3.25  %%% TeX-master: "00book"

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/rollback	Wed Nov 15 15:59:41 2006 -0800
     4.3 @@ -0,0 +1,37 @@
     4.4 +#!/bin/bash
     4.5 +
     4.6 +hg init a
     4.7 +cd a
     4.8 +echo a > a
     4.9 +hg ci -A -m 'First commit'
    4.10 +
    4.11 +echo a >> a
    4.12 +
    4.13 +#$ name: tip
    4.14 +
    4.15 +#$ name: commit
    4.16 +
    4.17 +hg status
    4.18 +echo b > b
    4.19 +hg commit -m 'Add file b'
    4.20 +
    4.21 +#$ name: status
    4.22 +
    4.23 +hg status
    4.24 +hg tip
    4.25 +
    4.26 +#$ name: rollback
    4.27 +
    4.28 +hg rollback
    4.29 +hg tip
    4.30 +hg status
    4.31 +
    4.32 +#$ name: add
    4.33 +
    4.34 +hg add b
    4.35 +hg commit -m 'Add file b, this time for real'
    4.36 +
    4.37 +#$ name: twice
    4.38 +
    4.39 +hg rollback
    4.40 +hg rollback

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/undo.tex	Wed Nov 15 15:59:41 2006 -0800
     5.3 @@ -0,0 +1,117 @@
     5.4 +\chapter{Finding and fixing your mistakes}
     5.5 +\label{chap:undo}
     5.6 +
     5.7 +To err might be human, but to really handle the consequences well
     5.8 +takes a top-notch revision control system.  In this chapter, we'll
     5.9 +discuss some of the techniques you can use when you find that a
    5.10 +problem has crept into your project.  Mercurial has some highly
    5.11 +capable features that will help you to isolate the sources of
    5.12 +problems, and to handle them appropriately.
    5.13 +
    5.14 +\section{Easily recovered errors}
    5.15 +
    5.16 +\subsection{The accidental commit}
    5.17 +
    5.18 +I have the occasional but persistent problem of typing rather more
    5.19 +quickly than I can think, which sometimes results in me committing a
    5.20 +changeset that is either incomplete or plain wrong.  In my case, the
    5.21 +usual kind of incomplete changeset is one in which I've created a new
    5.22 +source file, but forgotten to \hgcmd{add} it.  A ``plain wrong''
    5.23 +changeset is not as common, but no less annoying.
    5.24 +
    5.25 +\subsection{Rolling back a transaction}
    5.26 +
    5.27 +In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
    5.28 +each modification of a repository as a \emph{transaction}.  Every time
    5.29 +you commit a changeset or pull changes from another repository,
    5.30 +Mercurial remembers what you did.  You can undo, or \emph{roll back},
    5.31 +exactly one of these actions using the \hgcmd{rollback} command.
    5.32 +
    5.33 +Here's a mistake that I often find myself making: committing a change
    5.34 +in which I've created a new file, but forgotten to \hgcmd{add} it.
    5.35 +\interaction{rollback.commit}
    5.36 +Looking at the output of \hgcmd{status} after the commit immediately
    5.37 +confirms the error.
    5.38 +\interaction{rollback.status}
    5.39 +The commit captured the changes to the file \filename{a}, but not the
    5.40 +new file \filename{b}.  If I were to push this changeset to a
    5.41 +repository that I shared with a colleague, the chances are high that
    5.42 +something in \filename{a} would refer to \filename{b}, which would not
    5.43 +be present in their repository when they pulled my changes.  I would
    5.44 +thus become the object of some indignation.
    5.45 +
    5.46 +However, luck is with me---I've caught my error before I pushed the
    5.47 +changeset.  I use the \hgcmd{rollback} command, and Mercurial makes
    5.48 +that last changeset vanish.
    5.49 +\interaction{rollback.rollback}
    5.50 +Notice that the changeset is no longer present in the repository's
    5.51 +history, and the working directory once again thinks that the file
    5.52 +\filename{a} is modified.  The changeset has been completely erased.
    5.53 +I can now safely \hgcmd{add} the file \filename{b}, and rerun my
    5.54 +commit.
    5.55 +\interaction{rollback.add}
    5.56 +
    5.57 +\subsection{The erroneous pull}
    5.58 +
    5.59 +It's common practice with Mercurial to maintain separate development
    5.60 +branches of a project in different repositories.  Your development
    5.61 +team might have one shared repository for your project's ``0.9''
    5.62 +release, and another, containing different changes, for the ``1.0''
    5.63 +release.
    5.64 +
    5.65 +Given this, you can imagine that the consequences could be messy if
    5.66 +you had a local ``0.9'' repository, and accidentally pulled changes
    5.67 +from the shared ``1.0'' repository into it.  At worst, you could be
    5.68 +paying insufficient attention, and push those changes into the shared
    5.69 +``0.9'' tree, confusing your entire team (but don't worry, we'll
    5.70 +return to this horror scenario later).  However, it's more likely that
    5.71 +you'll notice immediately, because Mercurial will display the URL it's
    5.72 +pulling from, or you will see it pull a suspiciously large number of
    5.73 +changes into the repository.
    5.74 +
    5.75 +The \hgcmd{rollback} command will work nicely to expunge all of the
    5.76 +changesets that you just pulled.  Mercurial groups all changes from
    5.77 +one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
    5.78 +all you need to undo this mistake.
    5.79 +
    5.80 +\subsection{Rolling back is useless once you've pushed}
    5.81 +
    5.82 +The value of the \hgcmd{rollback} command drops to zero once you've
    5.83 +pushed your changes to another repository.  Rolling back a change
    5.84 +makes it disappear entirely, but \emph{only} in the repository in
    5.85 +which you perform the \hgcmd{rollback}.  Because a rollback eliminates
    5.86 +history, there's no way for the disappearance of a change to propagate
    5.87 +between repositories.
    5.88 +
    5.89 +If you've pushed a change to another repository---particularly if it's
    5.90 +a shared repository---it has essentially ``escaped into the wild,''
    5.91 +and you'll have to recover from your mistake in a different way.  What
    5.92 +will happen if you push a changeset somewhere, then roll it back, then
    5.93 +pull from the repository you pushed to, is that the changeset will
    5.94 +reappear in your repository.
    5.95 +
    5.96 +(If you absolutely know for sure that the change you want to roll back
    5.97 +is the most recent change in the repository that you pushed to,
    5.98 +\emph{and} you know that nobody else could have pulled it from that
    5.99 +repository, you can roll back the changeset there, too, but you really
   5.100 +should really not rely on this working reliably.  If you do this,
   5.101 +sooner or later a change really will make it into a repository that
   5.102 +you don't directly control (or have forgotten about), and come back to
   5.103 +bite you.)
   5.104 +
   5.105 +\subsection{You can only roll back once}
   5.106 +
   5.107 +Mercurial stores exactly one transaction in its transaction log; that
   5.108 +transaction is the most recent one that occurred in the repository.
   5.109 +This means that you can only roll back one transaction.  If you expect
   5.110 +to be able to roll back one transaction, then its predecessor, this is
   5.111 +not the behaviour you will get.
   5.112 +\interaction{rollback.twice}
   5.113 +Once you've rolled back one transaction in a repository, you can't
   5.114 +roll back again in that repository until you perform another commit or
   5.115 +pull.
   5.116 +
   5.117 +%%% Local Variables: 
   5.118 +%%% mode: latex
   5.119 +%%% TeX-master: "00book"
   5.120 +%%% End: