1.1 --- a/en/undo.tex	Tue Dec 26 14:06:41 2006 -0800
     1.2 +++ b/en/undo.tex	Tue Dec 26 16:56:00 2006 -0800
     1.3 @@ -20,6 +20,7 @@
     1.4  changeset is not as common, but no less annoying.
     1.5  
     1.6  \subsection{Rolling back a transaction}
     1.7 +\label{sec:undo:rollback}
     1.8  
     1.9  In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
    1.10  each modification of a repository as a \emph{transaction}.  Every time
    1.11 @@ -207,6 +208,13 @@
    1.12  automatically, and building blocks that let you reverse part of a
    1.13  changeset by hand.
    1.14  
    1.15 +Before you read this section, here's something to keep in mind: the
    1.16 +\hgcmd{backout} command undoes changes by \emph{adding} history, not
    1.17 +by modifying or erasing it.  It's the right tool to use if you're
    1.18 +fixing bugs, but not if you're trying to undo some change that has
    1.19 +catastrophic consequences.  To deal with those, see
    1.20 +section~\ref{sec:undo:aaaiiieee}.
    1.21 +
    1.22  \subsection{Backing out a changeset}
    1.23  
    1.24  The \hgcmd{backout} command lets you ``undo'' the effects of an entire
    1.25 @@ -350,7 +358,7 @@
    1.26    \label{fig:undo:backout-manual-merge}
    1.27  \end{figure}
    1.28  
    1.29 -\subsection{A rationale}
    1.30 +\subsection{Why \hgcmd{backout} works as it does}
    1.31  
    1.32  Here's a brief description of how the \hgcmd{backout} command works.
    1.33  \begin{enumerate}
    1.34 @@ -396,6 +404,52 @@
    1.35  changes, and modifications to binary files, none of which
    1.36  \command{patch} can deal with.
    1.37  
    1.38 +\section{Changes that should never have been}
    1.39 +\label{sec:undo:aaaiiieee}
    1.40 +
    1.41 +Most of the time, the \hgcmd{backout} command is exactly what you need
    1.42 +if you want to undo the effects of a change.  It leaves a permanent
    1.43 +record of exactly what you did, both when committing the original
    1.44 +changeset and when you cleaned up after it.
    1.45 +
    1.46 +On rare occasions, though, you may find that you've committed a change
    1.47 +that really should not be present in the repository at all.  For
    1.48 +example, it would be very unusual, and usually considered a mistake,
    1.49 +to commit a software project's object files as well as its source
    1.50 +files.  Object files have almost no intrinsic value, and they're
    1.51 +\emph{big}, so they increase the size of the repository and the amount
    1.52 +of time it takes to clone or pull changes.
    1.53 +
    1.54 +Before I discuss the options that you have if you commit a ``brown
    1.55 +paper bag'' change (the kind that's so bad that you want to pull a
    1.56 +brown paper bag over your head), let me first discuss some approaches
    1.57 +that probably won't work.
    1.58 +
    1.59 +Since Mercurial treats history as accumulative---every change builds
    1.60 +on top of all changes that preceded it---you generally can't just make
    1.61 +disastrous changes disappear.  The one exception is when you've just
    1.62 +committed a change, and it hasn't been pushed or pulled into another
    1.63 +repository.  That's when you can safely use the \hgcmd{rollback}
    1.64 +command, as I detailed in section~\ref{sec:undo:rollback}.
    1.65 +
    1.66 +After you've pushed a bad change to another repository, you
    1.67 +\emph{could} still use \hgcmd{rollback} to make your local copy of the
    1.68 +change disappear, but it won't have the consequences you want.  The
    1.69 +change will still be present in the remote repository, so it will
    1.70 +reappear in your local repository the next time you pull.
    1.71 +
    1.72 +If a situation like this arises, and you know which repositories your
    1.73 +bad change has propagated into, you can \emph{try} to get rid of the
    1.74 +changeefrom \emph{every} one of those repositories.  This is, of
    1.75 +course, not a satisfactory solution: if you miss even a single
    1.76 +repository while you're expunging, the change is still ``in the
    1.77 +wild'', and could propagate further.
    1.78 +
    1.79 +If you've committed one or more changes \emph{after} the change that
    1.80 +you'd like to see disappear, your options are further reduced.
    1.81 +Mercurial doesn't provide a way to ``punch a hole'' in history,
    1.82 +leaving changesets intact.
    1.83 +
    1.84  %%% Local Variables: 
    1.85  %%% mode: latex
    1.86  %%% TeX-master: "00book"