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@121: \section{Easily recovered errors} 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@121: \filename{a} is modified. The changeset has been completely erased. bos@121: I can now safely \hgcmd{add} the file \filename{b}, and rerun my bos@121: 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@121: %%% Local Variables: bos@121: %%% mode: latex bos@121: %%% TeX-master: "00book" bos@121: %%% End: