hgbook
diff en/undo.tex @ 121:9094c9fda8ec
Start chapter on error recovery.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Nov 15 15:59:41 2006 -0800 (2006-11-15) |
parents | |
children | 3af28630fe8c |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/undo.tex Wed Nov 15 15:59:41 2006 -0800 1.3 @@ -0,0 +1,117 @@ 1.4 +\chapter{Finding and fixing your mistakes} 1.5 +\label{chap:undo} 1.6 + 1.7 +To err might be human, but to really handle the consequences well 1.8 +takes a top-notch revision control system. In this chapter, we'll 1.9 +discuss some of the techniques you can use when you find that a 1.10 +problem has crept into your project. Mercurial has some highly 1.11 +capable features that will help you to isolate the sources of 1.12 +problems, and to handle them appropriately. 1.13 + 1.14 +\section{Easily recovered errors} 1.15 + 1.16 +\subsection{The accidental commit} 1.17 + 1.18 +I have the occasional but persistent problem of typing rather more 1.19 +quickly than I can think, which sometimes results in me committing a 1.20 +changeset that is either incomplete or plain wrong. In my case, the 1.21 +usual kind of incomplete changeset is one in which I've created a new 1.22 +source file, but forgotten to \hgcmd{add} it. A ``plain wrong'' 1.23 +changeset is not as common, but no less annoying. 1.24 + 1.25 +\subsection{Rolling back a transaction} 1.26 + 1.27 +In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats 1.28 +each modification of a repository as a \emph{transaction}. Every time 1.29 +you commit a changeset or pull changes from another repository, 1.30 +Mercurial remembers what you did. You can undo, or \emph{roll back}, 1.31 +exactly one of these actions using the \hgcmd{rollback} command. 1.32 + 1.33 +Here's a mistake that I often find myself making: committing a change 1.34 +in which I've created a new file, but forgotten to \hgcmd{add} it. 1.35 +\interaction{rollback.commit} 1.36 +Looking at the output of \hgcmd{status} after the commit immediately 1.37 +confirms the error. 1.38 +\interaction{rollback.status} 1.39 +The commit captured the changes to the file \filename{a}, but not the 1.40 +new file \filename{b}. If I were to push this changeset to a 1.41 +repository that I shared with a colleague, the chances are high that 1.42 +something in \filename{a} would refer to \filename{b}, which would not 1.43 +be present in their repository when they pulled my changes. I would 1.44 +thus become the object of some indignation. 1.45 + 1.46 +However, luck is with me---I've caught my error before I pushed the 1.47 +changeset. I use the \hgcmd{rollback} command, and Mercurial makes 1.48 +that last changeset vanish. 1.49 +\interaction{rollback.rollback} 1.50 +Notice that the changeset is no longer present in the repository's 1.51 +history, and the working directory once again thinks that the file 1.52 +\filename{a} is modified. The changeset has been completely erased. 1.53 +I can now safely \hgcmd{add} the file \filename{b}, and rerun my 1.54 +commit. 1.55 +\interaction{rollback.add} 1.56 + 1.57 +\subsection{The erroneous pull} 1.58 + 1.59 +It's common practice with Mercurial to maintain separate development 1.60 +branches of a project in different repositories. Your development 1.61 +team might have one shared repository for your project's ``0.9'' 1.62 +release, and another, containing different changes, for the ``1.0'' 1.63 +release. 1.64 + 1.65 +Given this, you can imagine that the consequences could be messy if 1.66 +you had a local ``0.9'' repository, and accidentally pulled changes 1.67 +from the shared ``1.0'' repository into it. At worst, you could be 1.68 +paying insufficient attention, and push those changes into the shared 1.69 +``0.9'' tree, confusing your entire team (but don't worry, we'll 1.70 +return to this horror scenario later). However, it's more likely that 1.71 +you'll notice immediately, because Mercurial will display the URL it's 1.72 +pulling from, or you will see it pull a suspiciously large number of 1.73 +changes into the repository. 1.74 + 1.75 +The \hgcmd{rollback} command will work nicely to expunge all of the 1.76 +changesets that you just pulled. Mercurial groups all changes from 1.77 +one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is 1.78 +all you need to undo this mistake. 1.79 + 1.80 +\subsection{Rolling back is useless once you've pushed} 1.81 + 1.82 +The value of the \hgcmd{rollback} command drops to zero once you've 1.83 +pushed your changes to another repository. Rolling back a change 1.84 +makes it disappear entirely, but \emph{only} in the repository in 1.85 +which you perform the \hgcmd{rollback}. Because a rollback eliminates 1.86 +history, there's no way for the disappearance of a change to propagate 1.87 +between repositories. 1.88 + 1.89 +If you've pushed a change to another repository---particularly if it's 1.90 +a shared repository---it has essentially ``escaped into the wild,'' 1.91 +and you'll have to recover from your mistake in a different way. What 1.92 +will happen if you push a changeset somewhere, then roll it back, then 1.93 +pull from the repository you pushed to, is that the changeset will 1.94 +reappear in your repository. 1.95 + 1.96 +(If you absolutely know for sure that the change you want to roll back 1.97 +is the most recent change in the repository that you pushed to, 1.98 +\emph{and} you know that nobody else could have pulled it from that 1.99 +repository, you can roll back the changeset there, too, but you really 1.100 +should really not rely on this working reliably. If you do this, 1.101 +sooner or later a change really will make it into a repository that 1.102 +you don't directly control (or have forgotten about), and come back to 1.103 +bite you.) 1.104 + 1.105 +\subsection{You can only roll back once} 1.106 + 1.107 +Mercurial stores exactly one transaction in its transaction log; that 1.108 +transaction is the most recent one that occurred in the repository. 1.109 +This means that you can only roll back one transaction. If you expect 1.110 +to be able to roll back one transaction, then its predecessor, this is 1.111 +not the behaviour you will get. 1.112 +\interaction{rollback.twice} 1.113 +Once you've rolled back one transaction in a repository, you can't 1.114 +roll back again in that repository until you perform another commit or 1.115 +pull. 1.116 + 1.117 +%%% Local Variables: 1.118 +%%% mode: latex 1.119 +%%% TeX-master: "00book" 1.120 +%%% End: