annotate en/undo.tex @ 124:c9aad709bd3a

Document the backout command.

\chapter{Finding and fixing your mistakes}
\label{chap:undo}

To err might be human, but to really handle the consequences well
takes a top-notch revision control system.  In this chapter, we'll
discuss some of the techniques you can use when you find that a
problem has crept into your project.  Mercurial has some highly
capable features that will help you to isolate the sources of
problems, and to handle them appropriately.

\section{Erasing local history}

\subsection{The accidental commit}

I have the occasional but persistent problem of typing rather more
quickly than I can think, which sometimes results in me committing a
changeset that is either incomplete or plain wrong.  In my case, the
usual kind of incomplete changeset is one in which I've created a new
source file, but forgotten to \hgcmd{add} it.  A ``plain wrong''
changeset is not as common, but no less annoying.

\subsection{Rolling back a transaction}

In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
each modification of a repository as a \emph{transaction}.  Every time
you commit a changeset or pull changes from another repository,
Mercurial remembers what you did.  You can undo, or \emph{roll back},
exactly one of these actions using the \hgcmd{rollback} command.

Here's a mistake that I often find myself making: committing a change
in which I've created a new file, but forgotten to \hgcmd{add} it.
\interaction{rollback.commit}
Looking at the output of \hgcmd{status} after the commit immediately
confirms the error.
\interaction{rollback.status}
The commit captured the changes to the file \filename{a}, but not the
new file \filename{b}.  If I were to push this changeset to a
repository that I shared with a colleague, the chances are high that
something in \filename{a} would refer to \filename{b}, which would not
be present in their repository when they pulled my changes.  I would
thus become the object of some indignation.

However, luck is with me---I've caught my error before I pushed the
changeset.  I use the \hgcmd{rollback} command, and Mercurial makes
that last changeset vanish.
\interaction{rollback.rollback}
Notice that the changeset is no longer present in the repository's
history, and the working directory once again thinks that the file
\filename{a} is modified.  The commit and rollback have left the
working directory exactly as it was prior to the commit; the changeset
has been completely erased.  I can now safely \hgcmd{add} the file
\filename{b}, and rerun my commit.
\interaction{rollback.add}

\subsection{The erroneous pull}

It's common practice with Mercurial to maintain separate development
branches of a project in different repositories.  Your development
team might have one shared repository for your project's ``0.9''
release, and another, containing different changes, for the ``1.0''
release.

Given this, you can imagine that the consequences could be messy if
you had a local ``0.9'' repository, and accidentally pulled changes
from the shared ``1.0'' repository into it.  At worst, you could be
paying insufficient attention, and push those changes into the shared
``0.9'' tree, confusing your entire team (but don't worry, we'll
return to this horror scenario later).  However, it's more likely that
you'll notice immediately, because Mercurial will display the URL it's
pulling from, or you will see it pull a suspiciously large number of
changes into the repository.

The \hgcmd{rollback} command will work nicely to expunge all of the
changesets that you just pulled.  Mercurial groups all changes from
one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
all you need to undo this mistake.

\subsection{Rolling back is useless once you've pushed}

The value of the \hgcmd{rollback} command drops to zero once you've
pushed your changes to another repository.  Rolling back a change
makes it disappear entirely, but \emph{only} in the repository in
which you perform the \hgcmd{rollback}.  Because a rollback eliminates
history, there's no way for the disappearance of a change to propagate
between repositories.

If you've pushed a change to another repository---particularly if it's
a shared repository---it has essentially ``escaped into the wild,''
and you'll have to recover from your mistake in a different way.  What
will happen if you push a changeset somewhere, then roll it back, then
pull from the repository you pushed to, is that the changeset will
reappear in your repository.

(If you absolutely know for sure that the change you want to roll back
is the most recent change in the repository that you pushed to,
\emph{and} you know that nobody else could have pulled it from that
repository, you can roll back the changeset there, too, but you really
should really not rely on this working reliably.  If you do this,
sooner or later a change really will make it into a repository that
you don't directly control (or have forgotten about), and come back to
bite you.)

\subsection{You can only roll back once}

Mercurial stores exactly one transaction in its transaction log; that
transaction is the most recent one that occurred in the repository.
This means that you can only roll back one transaction.  If you expect
to be able to roll back one transaction, then its predecessor, this is
not the behaviour you will get.
\interaction{rollback.twice}
Once you've rolled back one transaction in a repository, you can't
roll back again in that repository until you perform another commit or
pull.

\section{Reverting the mistaken change}

If you make a modification to a file, and decide that you really
didn't want to change the file at all, and you haven't yet committed
your changes, the \hgcmd{revert} command is the one you'll need.  It
looks at the changeset that's the parent of the working directory, and
restores the contents of the file to their state as of that changeset.
(That's a long-winded way of saying that, in the normal case, it
undoes your modifications.)

Let's illustrate how the \hgcmd{revert} command works with yet another
small example.  We'll begin by modifying a file that Mercurial is
already tracking.
\interaction{daily.revert.modify}
If we don't want that change, we can simply \hgcmd{revert} the file.
\interaction{daily.revert.unmodify}
The \hgcmd{revert} command provides us with an extra degree of safety
by saving our modified file with a \filename{.orig} extension.
\interaction{daily.revert.status}

Here is a summary of the cases that the \hgcmd{revert} command can
deal with.  We will describe each of these in more detail in the
section that follows.
\begin{itemize}
\item If you modify a file, it will restore the file to its unmodified
  state.
\item If you \hgcmd{add} a file, it will undo the ``added'' state of
  the file, but leave the file itself untouched.
\item If you delete a file without telling Mercurial, it will restore
  the file to its unmodified contents.
\item If you use the \hgcmd{remove} command to remove a file, it will
  undo the ``removed'' state of the file, and restore the file to its
  unmodified contents.
\end{itemize}

\subsection{File management errors}
\label{sec:undo:mgmt}

The \hgcmd{revert} command is useful for more than just modified
files.  It lets you reverse the results of all of Mercurial's file
management commands---\hgcmd{add}, \hgcmd{remove}, and so on.

If you \hgcmd{add} a file, then decide that in fact you don't want
Mercurial to track it, use \hgcmd{revert} to undo the add.  Don't
worry; Mercurial will not modify the file in any way.  It will just
``unmark'' the file.
\interaction{daily.revert.add}

Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
\hgcmd{revert} to restore it to the contents it had as of the parent
of the working directory.
\interaction{daily.revert.remove}
This works just as well for a file that you deleted by hand, without
telling Mercurial (recall that in Mercurial terminology, this kind of
file is called ``missing'').
\interaction{daily.revert.missing}

If you revert a \hgcmd{copy}, the copied-to file remains in your
working directory afterwards, untracked.  Since a copy doesn't affect
the copied-from file in any way, Mercurial doesn't do anything with
the copied-from file.
\interaction{daily.revert.copy}

\subsubsection{A slightly special case: reverting a rename}

If you \hgcmd{rename} a file, there is one small detail that
you should remember.  When you \hgcmd{revert} a rename, it's not
enough to provide the name of the renamed-to file, as you can see
here.
\interaction{daily.revert.rename}
As you can see from the output of \hgcmd{status}, the renamed-to file
is no longer identified as added, but the renamed-\emph{from} file is
still removed!  This is counter-intuitive (at least to me), but at
least it's easy to deal with.
\interaction{daily.revert.rename-orig}
So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
the source and destination names.  

(By the way, if you rename a file, then modify the renamed-to file,
then revert both components of the rename, when Mercurial restores the
file that was removed as part of the rename, it will be unmodified.
If you need the modifications in the renamed-to file to show up in the
renamed-from file, don't forget to copy them over.)

These fiddly aspects of reverting a rename arguably constitute a small
bug in Mercurial.

\section{Dealing with committed changes}

Consider a case where you have committed a change $a$, and another
change $b$ on top of it; you then realise that change $a$ was
incorrect.  Mercurial lets you ``back out'' an entire changeset
automatically, and building blocks that let you reverse part of a
changeset by hand.

\subsection{Backing out a changeset}

The \hgcmd{backout} command lets you ``undo'' the effects of an entire
changeset in an automated fashion.  Because Mercurial's history is
immutable, this command \emph{does not} get rid of the changeset you
want to undo.  Instead, it creates a new changeset that
\emph{reverses} the effect of the to-be-undone changeset.

The operation of the \hgcmd{backout} command is a little intricate, so
let's illustrate it with some examples.  First, we'll create a
repository with some simple changes.
\interaction{backout.init}

The \hgcmd{backout} command takes a single changeset ID as its
argument; this is the changeset to back out.  Normally,
\hgcmd{backout} will drop you into a text editor to write a commit
message, so you can record why you're backing the change out.  In this
example, we provide a commit message on the command line using the
\hgopt{backout}{-m} option.

\subsection{Backing out the tip changeset}

We're going to start by backing out the last changeset we committed.
\interaction{backout.simple}
You can see that the second line from \filename{myfile} is no longer
present.  Taking a look at the output of \hgcmd{log} gives us an idea
of what the \hgcmd{backout} command has done.
\interaction{backout.simple.log}
Notice that the new changeset that \hgcmd{backout} has created is a
child of the changeset we backed out.  It's easier to see this in
figure~\ref{fig:undo:backout}, which presents a graphical view of the
change history.  As you can see, the history is nice and linear.

\begin{figure}[htb]
  \centering
  \grafix{undo-simple}
  \caption{Backing out a change using the \hgcmd{backout} command}
  \label{fig:undo:backout}
\end{figure}

\subsection{Backing out a non-tip change}

If you want to back out a change other than the last one you
committed, pass the \hgopt{backout}{--merge} option to the
\hgcmd{backout} command.
\interaction{backout.non-tip.clone}
This makes backing out any changeset a ``one-shot'' operation that's
usually simple and fast.
\interaction{backout.non-tip.backout}

If you take a look at the contents of \filename{myfile} after the
backout finishes, you'll see that the first and third changes are
present, but not the second.
\interaction{backout.non-tip.cat}

As the graphical history in figure~\ref{fig:undo:backout-non-tip}
illustrates, Mercurial actually commits \emph{two} changes in this
kind of situation (the box-shaped nodes are the ones that Mercurial
commits automatically).  Before Mercurial begins the backout process,
it first remembers what the current parent of the working directory
is.  It then backs out the target changeset, and commits that as a
changeset.  Finally, it merges back to the previous parent of the
working directory, and commits the result of the merge.

\begin{figure}[htb]
  \centering
  \grafix{undo-non-tip}
  \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
  \label{fig:undo:backout-non-tip}
\end{figure}

The result is that you end up ``back where you were'', only with some
extra history that undoes the effect of the changeset you wanted to
back out.

\subsubsection{Always use the \hgopt{backout}{--merge} option}

In fact, since the \hgopt{backout}{--merge} option will do the ``right
thing'' whether or not the changeset you're backing out is the tip
(i.e.~it won't try to merge if it's backing out the tip, since there's
no need), you should \emph{always} use this option when you run the
\hgcmd{backout} command.

\subsection{Gaining more control of the backout process}

While I've recommended that you always use the
\hgopt{backout}{--merge} option when backing out a change, the
\hgcmd{backout} command lets you decide how to merge a backout
changeset.  Taking control of the backout process by hand is something
you will rarely need to do, but it can be useful to understand what
the \hgcmd{backout} command is doing for you automatically.  To
illustrate this, let's clone our first repository, but omit the
backout change that it contains.

\interaction{backout.manual.clone}
As with our earlier example, We'll commit a third changeset, then back
out its parent, and see what happens.
\interaction{backout.manual.backout} 
Our new changeset is again a descendant of the changeset we backout
out; it's thus a new head, \emph{not} a descendant of the changeset
that was the tip.  The \hgcmd{backout} command was quite explicit in
telling us this.
\interaction{backout.manual.log}

Again, it's easier to see what has happened by looking at a graph of
the revision history, in figure~\ref{fig:undo:backout-manual}.  This
makes it clear that when we use \hgcmd{backout} to back out a change
other than the tip, Mercurial adds a new head to the repository (the
change it committed is box-shaped).

\begin{figure}[htb]
  \centering
  \grafix{undo-manual}
  \caption{Backing out a change using the \hgcmd{backout} command}
  \label{fig:undo:backout-manual}
\end{figure}

After the \hgcmd{backout} command has completed, it leaves the new
``backout'' changeset as the parent of the working directory.
\interaction{backout.manual.parents}
Now we have two isolated sets of changes.
\interaction{backout.manual.heads}

Let's think about what we expect to see as the contents of
\filename{myfile} now.  The first change should be present, because
we've never backed it out.  The second change should be missing, as
that's the change we backed out.  Since the history graph shows the
third change as a separate head, we \emph{don't} expect to see the
third change present in \filename{myfile}.
\interaction{backout.manual.cat}
To get the third change back into the file, we just do a normal merge
of our two heads.
\interaction{backout.manual.merge}
Afterwards, the graphical history of our repository looks like
figure~\ref{fig:undo:backout-manual-merge}.

\begin{figure}[htb]
  \centering
  \grafix{undo-manual-merge}
  \caption{Manually merging a backout change}
  \label{fig:undo:backout-manual-merge}
\end{figure}

\subsection{A rationale}

Here's a brief description of how the \hgcmd{backout} command works.
\begin{enumerate}
\item It ensures that the working directory is ``clean'', i.e.~that
  the output of \hgcmd{status} would be empty.
\item It remembers the current parent of the working directory.  Let's
  call this changeset \texttt{orig}
\item It does the equivalent of a \hgcmd{update} to sync the working
  directory to the changeset you want to back out.  Let's call this
  changeset \texttt{backout}
\item It finds the parent of that changeset.  Let's call that
  changeset \texttt{parent}.
\item For each file that the \texttt{backout} changeset affected, it
  does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
  to restore it to the contents it had before that changeset was
  committed.
\item It commits the result as a new changeset.  This changeset has
  \texttt{backout} as its parent.
\item If you specify \hgopt{backout}{--merge} on the command line, it
  merges with \texttt{orig}, and commits the result of the merge.
\end{enumerate}

An alternative way to implement the \hgcmd{backout} command would be
to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
the \cmdopt{patch}{--reverse} option to the \command{patch} command to
reverse the effect of the change without fiddling with the working
directory.  This sounds much simpler, but it would not work nearly as
well.

The reason that \hgcmd{backout} does an update, a commit, a merge, and
another commit is to give the merge machinery the best chance to do a
good job when dealing with all the changes \emph{between} the change
you're backing out and the current tip.  

If you're backing out a changeset that's~100 revisions back in your
project's history, the chances that the \command{patch} command will
be able to apply a reverse diff cleanly are not good, because
intervening changes are likely to have ``broken the context'' that
\command{patch} uses to determine whether it can apply a patch (if
this sounds like gibberish, see \section{sec:mq:patch} for a
discussion of the \command{patch} command).  Also, Mercurial's merge
machinery will handle files and directories being renamed, permission
changes, and modifications to binary files, none of which
\command{patch} can deal with.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: