
bos@121: \chapter{Finding and fixing your mistakes}
bos@121: \label{chap:undo}
bos@121: 
bos@121: To err might be human, but to really handle the consequences well
bos@121: takes a top-notch revision control system.  In this chapter, we'll
bos@121: discuss some of the techniques you can use when you find that a
bos@121: problem has crept into your project.  Mercurial has some highly
bos@121: capable features that will help you to isolate the sources of
bos@121: problems, and to handle them appropriately.
bos@121: 
bos@122: \section{Erasing local history}
bos@121: 
bos@121: \subsection{The accidental commit}
bos@121: 
bos@121: I have the occasional but persistent problem of typing rather more
bos@121: quickly than I can think, which sometimes results in me committing a
bos@121: changeset that is either incomplete or plain wrong.  In my case, the
bos@121: usual kind of incomplete changeset is one in which I've created a new
bos@121: source file, but forgotten to \hgcmd{add} it.  A ``plain wrong''
bos@121: changeset is not as common, but no less annoying.
bos@121: 
bos@121: \subsection{Rolling back a transaction}
bos@121: 
bos@121: In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
bos@121: each modification of a repository as a \emph{transaction}.  Every time
bos@121: you commit a changeset or pull changes from another repository,
bos@121: Mercurial remembers what you did.  You can undo, or \emph{roll back},
bos@121: exactly one of these actions using the \hgcmd{rollback} command.
bos@121: 
bos@121: Here's a mistake that I often find myself making: committing a change
bos@121: in which I've created a new file, but forgotten to \hgcmd{add} it.
bos@121: \interaction{rollback.commit}
bos@121: Looking at the output of \hgcmd{status} after the commit immediately
bos@121: confirms the error.
bos@121: \interaction{rollback.status}
bos@121: The commit captured the changes to the file \filename{a}, but not the
bos@121: new file \filename{b}.  If I were to push this changeset to a
bos@121: repository that I shared with a colleague, the chances are high that
bos@121: something in \filename{a} would refer to \filename{b}, which would not
bos@121: be present in their repository when they pulled my changes.  I would
bos@121: thus become the object of some indignation.
bos@121: 
bos@121: However, luck is with me---I've caught my error before I pushed the
bos@121: changeset.  I use the \hgcmd{rollback} command, and Mercurial makes
bos@121: that last changeset vanish.
bos@121: \interaction{rollback.rollback}
bos@121: Notice that the changeset is no longer present in the repository's
bos@121: history, and the working directory once again thinks that the file
bos@122: \filename{a} is modified.  The commit and rollback have left the
bos@122: working directory exactly as it was prior to the commit; the changeset
bos@122: has been completely erased.  I can now safely \hgcmd{add} the file
bos@122: \filename{b}, and rerun my commit.
bos@121: \interaction{rollback.add}
bos@121: 
bos@121: \subsection{The erroneous pull}
bos@121: 
bos@121: It's common practice with Mercurial to maintain separate development
bos@121: branches of a project in different repositories.  Your development
bos@121: team might have one shared repository for your project's ``0.9''
bos@121: release, and another, containing different changes, for the ``1.0''
bos@121: release.
bos@121: 
bos@121: Given this, you can imagine that the consequences could be messy if
bos@121: you had a local ``0.9'' repository, and accidentally pulled changes
bos@121: from the shared ``1.0'' repository into it.  At worst, you could be
bos@121: paying insufficient attention, and push those changes into the shared
bos@121: ``0.9'' tree, confusing your entire team (but don't worry, we'll
bos@121: return to this horror scenario later).  However, it's more likely that
bos@121: you'll notice immediately, because Mercurial will display the URL it's
bos@121: pulling from, or you will see it pull a suspiciously large number of
bos@121: changes into the repository.
bos@121: 
bos@121: The \hgcmd{rollback} command will work nicely to expunge all of the
bos@121: changesets that you just pulled.  Mercurial groups all changes from
bos@121: one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
bos@121: all you need to undo this mistake.
bos@121: 
bos@121: \subsection{Rolling back is useless once you've pushed}
bos@121: 
bos@121: The value of the \hgcmd{rollback} command drops to zero once you've
bos@121: pushed your changes to another repository.  Rolling back a change
bos@121: makes it disappear entirely, but \emph{only} in the repository in
bos@121: which you perform the \hgcmd{rollback}.  Because a rollback eliminates
bos@121: history, there's no way for the disappearance of a change to propagate
bos@121: between repositories.
bos@121: 
bos@121: If you've pushed a change to another repository---particularly if it's
bos@121: a shared repository---it has essentially ``escaped into the wild,''
bos@121: and you'll have to recover from your mistake in a different way.  What
bos@121: will happen if you push a changeset somewhere, then roll it back, then
bos@121: pull from the repository you pushed to, is that the changeset will
bos@121: reappear in your repository.
bos@121: 
bos@121: (If you absolutely know for sure that the change you want to roll back
bos@121: is the most recent change in the repository that you pushed to,
bos@121: \emph{and} you know that nobody else could have pulled it from that
bos@121: repository, you can roll back the changeset there, too, but you really
bos@121: should really not rely on this working reliably.  If you do this,
bos@121: sooner or later a change really will make it into a repository that
bos@121: you don't directly control (or have forgotten about), and come back to
bos@121: bite you.)
bos@121: 
bos@121: \subsection{You can only roll back once}
bos@121: 
bos@121: Mercurial stores exactly one transaction in its transaction log; that
bos@121: transaction is the most recent one that occurred in the repository.
bos@121: This means that you can only roll back one transaction.  If you expect
bos@121: to be able to roll back one transaction, then its predecessor, this is
bos@121: not the behaviour you will get.
bos@121: \interaction{rollback.twice}
bos@121: Once you've rolled back one transaction in a repository, you can't
bos@121: roll back again in that repository until you perform another commit or
bos@121: pull.
bos@121: 
bos@122: \section{Reverting the mistaken change}
bos@122: 
bos@122: If you make a modification to a file, and decide that you really
bos@124: didn't want to change the file at all, and you haven't yet committed
bos@124: your changes, the \hgcmd{revert} command is the one you'll need.  It
bos@124: looks at the changeset that's the parent of the working directory, and
bos@124: restores the contents of the file to their state as of that changeset.
bos@124: (That's a long-winded way of saying that, in the normal case, it
bos@124: undoes your modifications.)
bos@122: 
bos@122: Let's illustrate how the \hgcmd{revert} command works with yet another
bos@122: small example.  We'll begin by modifying a file that Mercurial is
bos@122: already tracking.
bos@122: \interaction{daily.revert.modify}
bos@122: If we don't want that change, we can simply \hgcmd{revert} the file.
bos@122: \interaction{daily.revert.unmodify}
bos@122: The \hgcmd{revert} command provides us with an extra degree of safety
bos@122: by saving our modified file with a \filename{.orig} extension.
bos@122: \interaction{daily.revert.status}
bos@122: 
bos@124: Here is a summary of the cases that the \hgcmd{revert} command can
bos@124: deal with.  We will describe each of these in more detail in the
bos@124: section that follows.
bos@124: \begin{itemize}
bos@124: \item If you modify a file, it will restore the file to its unmodified
bos@124:   state.
bos@124: \item If you \hgcmd{add} a file, it will undo the ``added'' state of
bos@124:   the file, but leave the file itself untouched.
bos@124: \item If you delete a file without telling Mercurial, it will restore
bos@124:   the file to its unmodified contents.
bos@124: \item If you use the \hgcmd{remove} command to remove a file, it will
bos@124:   undo the ``removed'' state of the file, and restore the file to its
bos@124:   unmodified contents.
bos@124: \end{itemize}
bos@124: 
bos@122: \subsection{File management errors}
bos@122: \label{sec:undo:mgmt}
bos@122: 
bos@122: The \hgcmd{revert} command is useful for more than just modified
bos@122: files.  It lets you reverse the results of all of Mercurial's file
bos@122: management commands---\hgcmd{add}, \hgcmd{remove}, and so on.
bos@122: 
bos@122: If you \hgcmd{add} a file, then decide that in fact you don't want
bos@122: Mercurial to track it, use \hgcmd{revert} to undo the add.  Don't
bos@122: worry; Mercurial will not modify the file in any way.  It will just
bos@122: ``unmark'' the file.
bos@122: \interaction{daily.revert.add}
bos@122: 
bos@122: Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
bos@122: \hgcmd{revert} to restore it to the contents it had as of the parent
bos@122: of the working directory.
bos@122: \interaction{daily.revert.remove}
bos@122: This works just as well for a file that you deleted by hand, without
bos@122: telling Mercurial (recall that in Mercurial terminology, this kind of
bos@122: file is called ``missing'').
bos@122: \interaction{daily.revert.missing}
bos@122: 
bos@122: If you revert a \hgcmd{copy}, the copied-to file remains in your
bos@123: working directory afterwards, untracked.  Since a copy doesn't affect
bos@123: the copied-from file in any way, Mercurial doesn't do anything with
bos@123: the copied-from file.
bos@122: \interaction{daily.revert.copy}
bos@122: 
bos@122: \subsubsection{A slightly special case: reverting a rename}
bos@122: 
bos@122: If you \hgcmd{rename} a file, there is one small detail that
bos@122: you should remember.  When you \hgcmd{revert} a rename, it's not
bos@122: enough to provide the name of the renamed-to file, as you can see
bos@122: here.
bos@122: \interaction{daily.revert.rename}
bos@122: As you can see from the output of \hgcmd{status}, the renamed-to file
bos@122: is no longer identified as added, but the renamed-\emph{from} file is
bos@122: still removed!  This is counter-intuitive (at least to me), but at
bos@122: least it's easy to deal with.
bos@122: \interaction{daily.revert.rename-orig}
bos@122: So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
bos@122: the source and destination names.  
bos@122: 
bos@122: (By the way, if you rename a file, then modify the renamed-to file,
bos@122: then revert both components of the rename, when Mercurial restores the
bos@122: file that was removed as part of the rename, it will be unmodified.
bos@122: If you need the modifications in the renamed-to file to show up in the
bos@122: renamed-from file, don't forget to copy them over.)
bos@122: 
bos@123: These fiddly aspects of reverting a rename arguably constitute a small
bos@122: bug in Mercurial.
bos@122: 
bos@124: \section{Dealing with committed changes}
bos@124: 
bos@124: Consider a case where you have committed a change $a$, and another
bos@124: change $b$ on top of it; you then realise that change $a$ was
bos@124: incorrect.  Mercurial lets you ``back out'' an entire changeset
bos@124: automatically, and building blocks that let you reverse part of a
bos@124: changeset by hand.
bos@124: 
bos@124: \subsection{Backing out a changeset}
bos@124: 
bos@124: The \hgcmd{backout} command lets you ``undo'' the effects of an entire
bos@124: changeset in an automated fashion.  Because Mercurial's history is
bos@124: immutable, this command \emph{does not} get rid of the changeset you
bos@124: want to undo.  Instead, it creates a new changeset that
bos@124: \emph{reverses} the effect of the to-be-undone changeset.
bos@124: 
bos@124: The operation of the \hgcmd{backout} command is a little intricate, so
bos@124: let's illustrate it with some examples.  First, we'll create a
bos@124: repository with some simple changes.
bos@124: \interaction{backout.init}
bos@124: 
bos@124: The \hgcmd{backout} command takes a single changeset ID as its
bos@124: argument; this is the changeset to back out.  Normally,
bos@124: \hgcmd{backout} will drop you into a text editor to write a commit
bos@124: message, so you can record why you're backing the change out.  In this
bos@124: example, we provide a commit message on the command line using the
bos@124: \hgopt{backout}{-m} option.
bos@124: 
bos@124: \subsection{Backing out the tip changeset}
bos@124: 
bos@124: We're going to start by backing out the last changeset we committed.
bos@124: \interaction{backout.simple}
bos@124: You can see that the second line from \filename{myfile} is no longer
bos@124: present.  Taking a look at the output of \hgcmd{log} gives us an idea
bos@124: of what the \hgcmd{backout} command has done.
bos@124: \interaction{backout.simple.log}
bos@124: Notice that the new changeset that \hgcmd{backout} has created is a
bos@124: child of the changeset we backed out.  It's easier to see this in
bos@124: figure~\ref{fig:undo:backout}, which presents a graphical view of the
bos@124: change history.  As you can see, the history is nice and linear.
bos@124: 
bos@124: \begin{figure}[htb]
bos@124:   \centering
bos@124:   \grafix{undo-simple}
bos@124:   \caption{Backing out a change using the \hgcmd{backout} command}
bos@124:   \label{fig:undo:backout}
bos@124: \end{figure}
bos@124: 
bos@124: \subsection{Backing out a non-tip change}
bos@124: 
bos@124: If you want to back out a change other than the last one you
bos@124: committed, pass the \hgopt{backout}{--merge} option to the
bos@124: \hgcmd{backout} command.
bos@124: \interaction{backout.non-tip.clone}
bos@124: This makes backing out any changeset a ``one-shot'' operation that's
bos@124: usually simple and fast.
bos@124: \interaction{backout.non-tip.backout}
bos@124: 
bos@124: If you take a look at the contents of \filename{myfile} after the
bos@124: backout finishes, you'll see that the first and third changes are
bos@124: present, but not the second.
bos@124: \interaction{backout.non-tip.cat}
bos@124: 
bos@124: As the graphical history in figure~\ref{fig:undo:backout-non-tip}
bos@124: illustrates, Mercurial actually commits \emph{two} changes in this
bos@124: kind of situation (the box-shaped nodes are the ones that Mercurial
bos@124: commits automatically).  Before Mercurial begins the backout process,
bos@124: it first remembers what the current parent of the working directory
bos@124: is.  It then backs out the target changeset, and commits that as a
bos@124: changeset.  Finally, it merges back to the previous parent of the
bos@124: working directory, and commits the result of the merge.
bos@124: 
bos@124: \begin{figure}[htb]
bos@124:   \centering
bos@124:   \grafix{undo-non-tip}
bos@124:   \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
bos@124:   \label{fig:undo:backout-non-tip}
bos@124: \end{figure}
bos@124: 
bos@124: The result is that you end up ``back where you were'', only with some
bos@124: extra history that undoes the effect of the changeset you wanted to
bos@124: back out.
bos@124: 
bos@124: \subsubsection{Always use the \hgopt{backout}{--merge} option}
bos@124: 
bos@124: In fact, since the \hgopt{backout}{--merge} option will do the ``right
bos@124: thing'' whether or not the changeset you're backing out is the tip
bos@124: (i.e.~it won't try to merge if it's backing out the tip, since there's
bos@124: no need), you should \emph{always} use this option when you run the
bos@124: \hgcmd{backout} command.
bos@124: 
bos@124: \subsection{Gaining more control of the backout process}
bos@124: 
bos@124: While I've recommended that you always use the
bos@124: \hgopt{backout}{--merge} option when backing out a change, the
bos@124: \hgcmd{backout} command lets you decide how to merge a backout
bos@124: changeset.  Taking control of the backout process by hand is something
bos@124: you will rarely need to do, but it can be useful to understand what
bos@124: the \hgcmd{backout} command is doing for you automatically.  To
bos@124: illustrate this, let's clone our first repository, but omit the
bos@124: backout change that it contains.
bos@124: 
bos@124: \interaction{backout.manual.clone}
bos@124: As with our earlier example, We'll commit a third changeset, then back
bos@124: out its parent, and see what happens.
bos@124: \interaction{backout.manual.backout} 
bos@124: Our new changeset is again a descendant of the changeset we backout
bos@124: out; it's thus a new head, \emph{not} a descendant of the changeset
bos@124: that was the tip.  The \hgcmd{backout} command was quite explicit in
bos@124: telling us this.
bos@124: \interaction{backout.manual.log}
bos@124: 
bos@124: Again, it's easier to see what has happened by looking at a graph of
bos@124: the revision history, in figure~\ref{fig:undo:backout-manual}.  This
bos@124: makes it clear that when we use \hgcmd{backout} to back out a change
bos@124: other than the tip, Mercurial adds a new head to the repository (the
bos@124: change it committed is box-shaped).
bos@124: 
bos@124: \begin{figure}[htb]
bos@124:   \centering
bos@124:   \grafix{undo-manual}
bos@124:   \caption{Backing out a change using the \hgcmd{backout} command}
bos@124:   \label{fig:undo:backout-manual}
bos@124: \end{figure}
bos@124: 
bos@124: After the \hgcmd{backout} command has completed, it leaves the new
bos@124: ``backout'' changeset as the parent of the working directory.
bos@124: \interaction{backout.manual.parents}
bos@124: Now we have two isolated sets of changes.
bos@124: \interaction{backout.manual.heads}
bos@124: 
bos@124: Let's think about what we expect to see as the contents of
bos@124: \filename{myfile} now.  The first change should be present, because
bos@124: we've never backed it out.  The second change should be missing, as
bos@124: that's the change we backed out.  Since the history graph shows the
bos@124: third change as a separate head, we \emph{don't} expect to see the
bos@124: third change present in \filename{myfile}.
bos@124: \interaction{backout.manual.cat}
bos@124: To get the third change back into the file, we just do a normal merge
bos@124: of our two heads.
bos@124: \interaction{backout.manual.merge}
bos@124: Afterwards, the graphical history of our repository looks like
bos@124: figure~\ref{fig:undo:backout-manual-merge}.
bos@124: 
bos@124: \begin{figure}[htb]
bos@124:   \centering
bos@124:   \grafix{undo-manual-merge}
bos@124:   \caption{Manually merging a backout change}
bos@124:   \label{fig:undo:backout-manual-merge}
bos@124: \end{figure}
bos@124: 
bos@124: \subsection{A rationale}
bos@124: 
bos@124: Here's a brief description of how the \hgcmd{backout} command works.
bos@124: \begin{enumerate}
bos@124: \item It ensures that the working directory is ``clean'', i.e.~that
bos@124:   the output of \hgcmd{status} would be empty.
bos@124: \item It remembers the current parent of the working directory.  Let's
bos@124:   call this changeset \texttt{orig}
bos@124: \item It does the equivalent of a \hgcmd{update} to sync the working
bos@124:   directory to the changeset you want to back out.  Let's call this
bos@124:   changeset \texttt{backout}
bos@124: \item It finds the parent of that changeset.  Let's call that
bos@124:   changeset \texttt{parent}.
bos@124: \item For each file that the \texttt{backout} changeset affected, it
bos@124:   does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
bos@124:   to restore it to the contents it had before that changeset was
bos@124:   committed.
bos@124: \item It commits the result as a new changeset.  This changeset has
bos@124:   \texttt{backout} as its parent.
bos@124: \item If you specify \hgopt{backout}{--merge} on the command line, it
bos@124:   merges with \texttt{orig}, and commits the result of the merge.
bos@124: \end{enumerate}
bos@124: 
bos@124: An alternative way to implement the \hgcmd{backout} command would be
bos@124: to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
bos@124: the \cmdopt{patch}{--reverse} option to the \command{patch} command to
bos@124: reverse the effect of the change without fiddling with the working
bos@124: directory.  This sounds much simpler, but it would not work nearly as
bos@124: well.
bos@124: 
bos@124: The reason that \hgcmd{backout} does an update, a commit, a merge, and
bos@124: another commit is to give the merge machinery the best chance to do a
bos@124: good job when dealing with all the changes \emph{between} the change
bos@124: you're backing out and the current tip.  
bos@124: 
bos@124: If you're backing out a changeset that's~100 revisions back in your
bos@124: project's history, the chances that the \command{patch} command will
bos@124: be able to apply a reverse diff cleanly are not good, because
bos@124: intervening changes are likely to have ``broken the context'' that
bos@124: \command{patch} uses to determine whether it can apply a patch (if
bos@125: this sounds like gibberish, see \ref{sec:mq:patch} for a
bos@124: discussion of the \command{patch} command).  Also, Mercurial's merge
bos@124: machinery will handle files and directories being renamed, permission
bos@124: changes, and modifications to binary files, none of which
bos@124: \command{patch} can deal with.
bos@124: 
bos@121: %%% Local Variables: 
bos@121: %%% mode: latex
bos@121: %%% TeX-master: "00book"
bos@121: %%% End: 




