hgbook
annotate en/undo.tex @ 260:ec6a3bb10986
HTML: replace Unicode ligatures with plain ASCII.
Thanks to Johannes Hoff for spotting this.
Thanks to Johannes Hoff for spotting this.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun Jun 17 11:09:13 2007 -0700 (2007-06-17) |
parents | 3f53563c7579 |
children | d145739b7865 |
rev | line source |
---|---|
bos@121 | 1 \chapter{Finding and fixing your mistakes} |
bos@121 | 2 \label{chap:undo} |
bos@121 | 3 |
bos@121 | 4 To err might be human, but to really handle the consequences well |
bos@121 | 5 takes a top-notch revision control system. In this chapter, we'll |
bos@121 | 6 discuss some of the techniques you can use when you find that a |
bos@121 | 7 problem has crept into your project. Mercurial has some highly |
bos@121 | 8 capable features that will help you to isolate the sources of |
bos@121 | 9 problems, and to handle them appropriately. |
bos@121 | 10 |
bos@122 | 11 \section{Erasing local history} |
bos@121 | 12 |
bos@121 | 13 \subsection{The accidental commit} |
bos@121 | 14 |
bos@121 | 15 I have the occasional but persistent problem of typing rather more |
bos@121 | 16 quickly than I can think, which sometimes results in me committing a |
bos@121 | 17 changeset that is either incomplete or plain wrong. In my case, the |
bos@121 | 18 usual kind of incomplete changeset is one in which I've created a new |
bos@121 | 19 source file, but forgotten to \hgcmd{add} it. A ``plain wrong'' |
bos@121 | 20 changeset is not as common, but no less annoying. |
bos@121 | 21 |
bos@121 | 22 \subsection{Rolling back a transaction} |
bos@126 | 23 \label{sec:undo:rollback} |
bos@121 | 24 |
bos@121 | 25 In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats |
bos@121 | 26 each modification of a repository as a \emph{transaction}. Every time |
bos@121 | 27 you commit a changeset or pull changes from another repository, |
bos@121 | 28 Mercurial remembers what you did. You can undo, or \emph{roll back}, |
bos@200 | 29 exactly one of these actions using the \hgcmd{rollback} command. (See |
bos@200 | 30 section~\ref{sec:undo:rollback-after-push} for an important caveat |
bos@200 | 31 about the use of this command.) |
bos@121 | 32 |
bos@121 | 33 Here's a mistake that I often find myself making: committing a change |
bos@121 | 34 in which I've created a new file, but forgotten to \hgcmd{add} it. |
bos@121 | 35 \interaction{rollback.commit} |
bos@121 | 36 Looking at the output of \hgcmd{status} after the commit immediately |
bos@121 | 37 confirms the error. |
bos@121 | 38 \interaction{rollback.status} |
bos@121 | 39 The commit captured the changes to the file \filename{a}, but not the |
bos@121 | 40 new file \filename{b}. If I were to push this changeset to a |
bos@121 | 41 repository that I shared with a colleague, the chances are high that |
bos@121 | 42 something in \filename{a} would refer to \filename{b}, which would not |
bos@121 | 43 be present in their repository when they pulled my changes. I would |
bos@121 | 44 thus become the object of some indignation. |
bos@121 | 45 |
bos@121 | 46 However, luck is with me---I've caught my error before I pushed the |
bos@121 | 47 changeset. I use the \hgcmd{rollback} command, and Mercurial makes |
bos@121 | 48 that last changeset vanish. |
bos@121 | 49 \interaction{rollback.rollback} |
bos@121 | 50 Notice that the changeset is no longer present in the repository's |
bos@121 | 51 history, and the working directory once again thinks that the file |
bos@122 | 52 \filename{a} is modified. The commit and rollback have left the |
bos@122 | 53 working directory exactly as it was prior to the commit; the changeset |
bos@122 | 54 has been completely erased. I can now safely \hgcmd{add} the file |
bos@122 | 55 \filename{b}, and rerun my commit. |
bos@121 | 56 \interaction{rollback.add} |
bos@121 | 57 |
bos@121 | 58 \subsection{The erroneous pull} |
bos@121 | 59 |
bos@121 | 60 It's common practice with Mercurial to maintain separate development |
bos@121 | 61 branches of a project in different repositories. Your development |
bos@121 | 62 team might have one shared repository for your project's ``0.9'' |
bos@121 | 63 release, and another, containing different changes, for the ``1.0'' |
bos@121 | 64 release. |
bos@121 | 65 |
bos@121 | 66 Given this, you can imagine that the consequences could be messy if |
bos@121 | 67 you had a local ``0.9'' repository, and accidentally pulled changes |
bos@121 | 68 from the shared ``1.0'' repository into it. At worst, you could be |
bos@121 | 69 paying insufficient attention, and push those changes into the shared |
bos@121 | 70 ``0.9'' tree, confusing your entire team (but don't worry, we'll |
bos@121 | 71 return to this horror scenario later). However, it's more likely that |
bos@121 | 72 you'll notice immediately, because Mercurial will display the URL it's |
bos@121 | 73 pulling from, or you will see it pull a suspiciously large number of |
bos@121 | 74 changes into the repository. |
bos@121 | 75 |
bos@121 | 76 The \hgcmd{rollback} command will work nicely to expunge all of the |
bos@121 | 77 changesets that you just pulled. Mercurial groups all changes from |
bos@121 | 78 one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is |
bos@121 | 79 all you need to undo this mistake. |
bos@121 | 80 |
bos@121 | 81 \subsection{Rolling back is useless once you've pushed} |
bos@200 | 82 \label{sec:undo:rollback-after-push} |
bos@121 | 83 |
bos@121 | 84 The value of the \hgcmd{rollback} command drops to zero once you've |
bos@121 | 85 pushed your changes to another repository. Rolling back a change |
bos@121 | 86 makes it disappear entirely, but \emph{only} in the repository in |
bos@121 | 87 which you perform the \hgcmd{rollback}. Because a rollback eliminates |
bos@121 | 88 history, there's no way for the disappearance of a change to propagate |
bos@121 | 89 between repositories. |
bos@121 | 90 |
bos@121 | 91 If you've pushed a change to another repository---particularly if it's |
bos@121 | 92 a shared repository---it has essentially ``escaped into the wild,'' |
bos@121 | 93 and you'll have to recover from your mistake in a different way. What |
bos@121 | 94 will happen if you push a changeset somewhere, then roll it back, then |
bos@121 | 95 pull from the repository you pushed to, is that the changeset will |
bos@121 | 96 reappear in your repository. |
bos@121 | 97 |
bos@121 | 98 (If you absolutely know for sure that the change you want to roll back |
bos@121 | 99 is the most recent change in the repository that you pushed to, |
bos@121 | 100 \emph{and} you know that nobody else could have pulled it from that |
bos@121 | 101 repository, you can roll back the changeset there, too, but you really |
bos@121 | 102 should really not rely on this working reliably. If you do this, |
bos@121 | 103 sooner or later a change really will make it into a repository that |
bos@121 | 104 you don't directly control (or have forgotten about), and come back to |
bos@121 | 105 bite you.) |
bos@121 | 106 |
bos@121 | 107 \subsection{You can only roll back once} |
bos@121 | 108 |
bos@121 | 109 Mercurial stores exactly one transaction in its transaction log; that |
bos@121 | 110 transaction is the most recent one that occurred in the repository. |
bos@121 | 111 This means that you can only roll back one transaction. If you expect |
bos@121 | 112 to be able to roll back one transaction, then its predecessor, this is |
bos@121 | 113 not the behaviour you will get. |
bos@121 | 114 \interaction{rollback.twice} |
bos@121 | 115 Once you've rolled back one transaction in a repository, you can't |
bos@121 | 116 roll back again in that repository until you perform another commit or |
bos@121 | 117 pull. |
bos@121 | 118 |
bos@122 | 119 \section{Reverting the mistaken change} |
bos@122 | 120 |
bos@122 | 121 If you make a modification to a file, and decide that you really |
bos@124 | 122 didn't want to change the file at all, and you haven't yet committed |
bos@124 | 123 your changes, the \hgcmd{revert} command is the one you'll need. It |
bos@124 | 124 looks at the changeset that's the parent of the working directory, and |
bos@124 | 125 restores the contents of the file to their state as of that changeset. |
bos@124 | 126 (That's a long-winded way of saying that, in the normal case, it |
bos@124 | 127 undoes your modifications.) |
bos@122 | 128 |
bos@122 | 129 Let's illustrate how the \hgcmd{revert} command works with yet another |
bos@122 | 130 small example. We'll begin by modifying a file that Mercurial is |
bos@122 | 131 already tracking. |
bos@122 | 132 \interaction{daily.revert.modify} |
bos@122 | 133 If we don't want that change, we can simply \hgcmd{revert} the file. |
bos@122 | 134 \interaction{daily.revert.unmodify} |
bos@122 | 135 The \hgcmd{revert} command provides us with an extra degree of safety |
bos@122 | 136 by saving our modified file with a \filename{.orig} extension. |
bos@122 | 137 \interaction{daily.revert.status} |
bos@122 | 138 |
bos@124 | 139 Here is a summary of the cases that the \hgcmd{revert} command can |
bos@124 | 140 deal with. We will describe each of these in more detail in the |
bos@124 | 141 section that follows. |
bos@124 | 142 \begin{itemize} |
bos@124 | 143 \item If you modify a file, it will restore the file to its unmodified |
bos@124 | 144 state. |
bos@124 | 145 \item If you \hgcmd{add} a file, it will undo the ``added'' state of |
bos@124 | 146 the file, but leave the file itself untouched. |
bos@124 | 147 \item If you delete a file without telling Mercurial, it will restore |
bos@124 | 148 the file to its unmodified contents. |
bos@124 | 149 \item If you use the \hgcmd{remove} command to remove a file, it will |
bos@124 | 150 undo the ``removed'' state of the file, and restore the file to its |
bos@124 | 151 unmodified contents. |
bos@124 | 152 \end{itemize} |
bos@124 | 153 |
bos@122 | 154 \subsection{File management errors} |
bos@122 | 155 \label{sec:undo:mgmt} |
bos@122 | 156 |
bos@122 | 157 The \hgcmd{revert} command is useful for more than just modified |
bos@122 | 158 files. It lets you reverse the results of all of Mercurial's file |
bos@122 | 159 management commands---\hgcmd{add}, \hgcmd{remove}, and so on. |
bos@122 | 160 |
bos@122 | 161 If you \hgcmd{add} a file, then decide that in fact you don't want |
bos@122 | 162 Mercurial to track it, use \hgcmd{revert} to undo the add. Don't |
bos@122 | 163 worry; Mercurial will not modify the file in any way. It will just |
bos@122 | 164 ``unmark'' the file. |
bos@122 | 165 \interaction{daily.revert.add} |
bos@122 | 166 |
bos@122 | 167 Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use |
bos@122 | 168 \hgcmd{revert} to restore it to the contents it had as of the parent |
bos@122 | 169 of the working directory. |
bos@122 | 170 \interaction{daily.revert.remove} |
bos@122 | 171 This works just as well for a file that you deleted by hand, without |
bos@122 | 172 telling Mercurial (recall that in Mercurial terminology, this kind of |
bos@122 | 173 file is called ``missing''). |
bos@122 | 174 \interaction{daily.revert.missing} |
bos@122 | 175 |
bos@122 | 176 If you revert a \hgcmd{copy}, the copied-to file remains in your |
bos@123 | 177 working directory afterwards, untracked. Since a copy doesn't affect |
bos@123 | 178 the copied-from file in any way, Mercurial doesn't do anything with |
bos@123 | 179 the copied-from file. |
bos@122 | 180 \interaction{daily.revert.copy} |
bos@122 | 181 |
bos@122 | 182 \subsubsection{A slightly special case: reverting a rename} |
bos@122 | 183 |
bos@122 | 184 If you \hgcmd{rename} a file, there is one small detail that |
bos@122 | 185 you should remember. When you \hgcmd{revert} a rename, it's not |
bos@122 | 186 enough to provide the name of the renamed-to file, as you can see |
bos@122 | 187 here. |
bos@122 | 188 \interaction{daily.revert.rename} |
bos@122 | 189 As you can see from the output of \hgcmd{status}, the renamed-to file |
bos@122 | 190 is no longer identified as added, but the renamed-\emph{from} file is |
bos@122 | 191 still removed! This is counter-intuitive (at least to me), but at |
bos@122 | 192 least it's easy to deal with. |
bos@122 | 193 \interaction{daily.revert.rename-orig} |
bos@122 | 194 So remember, to revert a \hgcmd{rename}, you must provide \emph{both} |
bos@122 | 195 the source and destination names. |
bos@122 | 196 |
bos@122 | 197 (By the way, if you rename a file, then modify the renamed-to file, |
bos@122 | 198 then revert both components of the rename, when Mercurial restores the |
bos@122 | 199 file that was removed as part of the rename, it will be unmodified. |
bos@122 | 200 If you need the modifications in the renamed-to file to show up in the |
bos@122 | 201 renamed-from file, don't forget to copy them over.) |
bos@122 | 202 |
bos@123 | 203 These fiddly aspects of reverting a rename arguably constitute a small |
bos@122 | 204 bug in Mercurial. |
bos@122 | 205 |
bos@124 | 206 \section{Dealing with committed changes} |
bos@124 | 207 |
bos@124 | 208 Consider a case where you have committed a change $a$, and another |
bos@124 | 209 change $b$ on top of it; you then realise that change $a$ was |
bos@124 | 210 incorrect. Mercurial lets you ``back out'' an entire changeset |
bos@124 | 211 automatically, and building blocks that let you reverse part of a |
bos@124 | 212 changeset by hand. |
bos@124 | 213 |
bos@126 | 214 Before you read this section, here's something to keep in mind: the |
bos@126 | 215 \hgcmd{backout} command undoes changes by \emph{adding} history, not |
bos@126 | 216 by modifying or erasing it. It's the right tool to use if you're |
bos@126 | 217 fixing bugs, but not if you're trying to undo some change that has |
bos@126 | 218 catastrophic consequences. To deal with those, see |
bos@126 | 219 section~\ref{sec:undo:aaaiiieee}. |
bos@126 | 220 |
bos@124 | 221 \subsection{Backing out a changeset} |
bos@124 | 222 |
bos@124 | 223 The \hgcmd{backout} command lets you ``undo'' the effects of an entire |
bos@124 | 224 changeset in an automated fashion. Because Mercurial's history is |
bos@124 | 225 immutable, this command \emph{does not} get rid of the changeset you |
bos@124 | 226 want to undo. Instead, it creates a new changeset that |
bos@124 | 227 \emph{reverses} the effect of the to-be-undone changeset. |
bos@124 | 228 |
bos@124 | 229 The operation of the \hgcmd{backout} command is a little intricate, so |
bos@124 | 230 let's illustrate it with some examples. First, we'll create a |
bos@124 | 231 repository with some simple changes. |
bos@124 | 232 \interaction{backout.init} |
bos@124 | 233 |
bos@124 | 234 The \hgcmd{backout} command takes a single changeset ID as its |
bos@124 | 235 argument; this is the changeset to back out. Normally, |
bos@124 | 236 \hgcmd{backout} will drop you into a text editor to write a commit |
bos@124 | 237 message, so you can record why you're backing the change out. In this |
bos@124 | 238 example, we provide a commit message on the command line using the |
bos@124 | 239 \hgopt{backout}{-m} option. |
bos@124 | 240 |
bos@124 | 241 \subsection{Backing out the tip changeset} |
bos@124 | 242 |
bos@124 | 243 We're going to start by backing out the last changeset we committed. |
bos@124 | 244 \interaction{backout.simple} |
bos@124 | 245 You can see that the second line from \filename{myfile} is no longer |
bos@124 | 246 present. Taking a look at the output of \hgcmd{log} gives us an idea |
bos@124 | 247 of what the \hgcmd{backout} command has done. |
bos@124 | 248 \interaction{backout.simple.log} |
bos@124 | 249 Notice that the new changeset that \hgcmd{backout} has created is a |
bos@124 | 250 child of the changeset we backed out. It's easier to see this in |
bos@124 | 251 figure~\ref{fig:undo:backout}, which presents a graphical view of the |
bos@124 | 252 change history. As you can see, the history is nice and linear. |
bos@124 | 253 |
bos@124 | 254 \begin{figure}[htb] |
bos@124 | 255 \centering |
bos@124 | 256 \grafix{undo-simple} |
bos@124 | 257 \caption{Backing out a change using the \hgcmd{backout} command} |
bos@124 | 258 \label{fig:undo:backout} |
bos@124 | 259 \end{figure} |
bos@124 | 260 |
bos@124 | 261 \subsection{Backing out a non-tip change} |
bos@124 | 262 |
bos@124 | 263 If you want to back out a change other than the last one you |
bos@124 | 264 committed, pass the \hgopt{backout}{--merge} option to the |
bos@124 | 265 \hgcmd{backout} command. |
bos@124 | 266 \interaction{backout.non-tip.clone} |
bos@124 | 267 This makes backing out any changeset a ``one-shot'' operation that's |
bos@124 | 268 usually simple and fast. |
bos@124 | 269 \interaction{backout.non-tip.backout} |
bos@124 | 270 |
bos@124 | 271 If you take a look at the contents of \filename{myfile} after the |
bos@124 | 272 backout finishes, you'll see that the first and third changes are |
bos@124 | 273 present, but not the second. |
bos@124 | 274 \interaction{backout.non-tip.cat} |
bos@124 | 275 |
bos@124 | 276 As the graphical history in figure~\ref{fig:undo:backout-non-tip} |
bos@124 | 277 illustrates, Mercurial actually commits \emph{two} changes in this |
bos@124 | 278 kind of situation (the box-shaped nodes are the ones that Mercurial |
bos@124 | 279 commits automatically). Before Mercurial begins the backout process, |
bos@124 | 280 it first remembers what the current parent of the working directory |
bos@124 | 281 is. It then backs out the target changeset, and commits that as a |
bos@124 | 282 changeset. Finally, it merges back to the previous parent of the |
bos@124 | 283 working directory, and commits the result of the merge. |
bos@124 | 284 |
bos@124 | 285 \begin{figure}[htb] |
bos@124 | 286 \centering |
bos@124 | 287 \grafix{undo-non-tip} |
bos@124 | 288 \caption{Automated backout of a non-tip change using the \hgcmd{backout} command} |
bos@124 | 289 \label{fig:undo:backout-non-tip} |
bos@124 | 290 \end{figure} |
bos@124 | 291 |
bos@124 | 292 The result is that you end up ``back where you were'', only with some |
bos@124 | 293 extra history that undoes the effect of the changeset you wanted to |
bos@124 | 294 back out. |
bos@124 | 295 |
bos@124 | 296 \subsubsection{Always use the \hgopt{backout}{--merge} option} |
bos@124 | 297 |
bos@124 | 298 In fact, since the \hgopt{backout}{--merge} option will do the ``right |
bos@124 | 299 thing'' whether or not the changeset you're backing out is the tip |
bos@124 | 300 (i.e.~it won't try to merge if it's backing out the tip, since there's |
bos@124 | 301 no need), you should \emph{always} use this option when you run the |
bos@124 | 302 \hgcmd{backout} command. |
bos@124 | 303 |
bos@124 | 304 \subsection{Gaining more control of the backout process} |
bos@124 | 305 |
bos@124 | 306 While I've recommended that you always use the |
bos@124 | 307 \hgopt{backout}{--merge} option when backing out a change, the |
bos@124 | 308 \hgcmd{backout} command lets you decide how to merge a backout |
bos@124 | 309 changeset. Taking control of the backout process by hand is something |
bos@124 | 310 you will rarely need to do, but it can be useful to understand what |
bos@124 | 311 the \hgcmd{backout} command is doing for you automatically. To |
bos@124 | 312 illustrate this, let's clone our first repository, but omit the |
bos@124 | 313 backout change that it contains. |
bos@124 | 314 |
bos@124 | 315 \interaction{backout.manual.clone} |
bos@124 | 316 As with our earlier example, We'll commit a third changeset, then back |
bos@124 | 317 out its parent, and see what happens. |
bos@124 | 318 \interaction{backout.manual.backout} |
bos@124 | 319 Our new changeset is again a descendant of the changeset we backout |
bos@124 | 320 out; it's thus a new head, \emph{not} a descendant of the changeset |
bos@124 | 321 that was the tip. The \hgcmd{backout} command was quite explicit in |
bos@124 | 322 telling us this. |
bos@124 | 323 \interaction{backout.manual.log} |
bos@124 | 324 |
bos@124 | 325 Again, it's easier to see what has happened by looking at a graph of |
bos@124 | 326 the revision history, in figure~\ref{fig:undo:backout-manual}. This |
bos@124 | 327 makes it clear that when we use \hgcmd{backout} to back out a change |
bos@124 | 328 other than the tip, Mercurial adds a new head to the repository (the |
bos@124 | 329 change it committed is box-shaped). |
bos@124 | 330 |
bos@124 | 331 \begin{figure}[htb] |
bos@124 | 332 \centering |
bos@124 | 333 \grafix{undo-manual} |
bos@124 | 334 \caption{Backing out a change using the \hgcmd{backout} command} |
bos@124 | 335 \label{fig:undo:backout-manual} |
bos@124 | 336 \end{figure} |
bos@124 | 337 |
bos@124 | 338 After the \hgcmd{backout} command has completed, it leaves the new |
bos@124 | 339 ``backout'' changeset as the parent of the working directory. |
bos@124 | 340 \interaction{backout.manual.parents} |
bos@124 | 341 Now we have two isolated sets of changes. |
bos@124 | 342 \interaction{backout.manual.heads} |
bos@124 | 343 |
bos@124 | 344 Let's think about what we expect to see as the contents of |
bos@124 | 345 \filename{myfile} now. The first change should be present, because |
bos@124 | 346 we've never backed it out. The second change should be missing, as |
bos@124 | 347 that's the change we backed out. Since the history graph shows the |
bos@124 | 348 third change as a separate head, we \emph{don't} expect to see the |
bos@124 | 349 third change present in \filename{myfile}. |
bos@124 | 350 \interaction{backout.manual.cat} |
bos@124 | 351 To get the third change back into the file, we just do a normal merge |
bos@124 | 352 of our two heads. |
bos@124 | 353 \interaction{backout.manual.merge} |
bos@124 | 354 Afterwards, the graphical history of our repository looks like |
bos@124 | 355 figure~\ref{fig:undo:backout-manual-merge}. |
bos@124 | 356 |
bos@124 | 357 \begin{figure}[htb] |
bos@124 | 358 \centering |
bos@124 | 359 \grafix{undo-manual-merge} |
bos@124 | 360 \caption{Manually merging a backout change} |
bos@124 | 361 \label{fig:undo:backout-manual-merge} |
bos@124 | 362 \end{figure} |
bos@124 | 363 |
bos@126 | 364 \subsection{Why \hgcmd{backout} works as it does} |
bos@124 | 365 |
bos@124 | 366 Here's a brief description of how the \hgcmd{backout} command works. |
bos@124 | 367 \begin{enumerate} |
bos@124 | 368 \item It ensures that the working directory is ``clean'', i.e.~that |
bos@124 | 369 the output of \hgcmd{status} would be empty. |
bos@124 | 370 \item It remembers the current parent of the working directory. Let's |
bos@124 | 371 call this changeset \texttt{orig} |
bos@124 | 372 \item It does the equivalent of a \hgcmd{update} to sync the working |
bos@124 | 373 directory to the changeset you want to back out. Let's call this |
bos@124 | 374 changeset \texttt{backout} |
bos@124 | 375 \item It finds the parent of that changeset. Let's call that |
bos@124 | 376 changeset \texttt{parent}. |
bos@124 | 377 \item For each file that the \texttt{backout} changeset affected, it |
bos@124 | 378 does the equivalent of a \hgcmdargs{revert}{-r parent} on that file, |
bos@124 | 379 to restore it to the contents it had before that changeset was |
bos@124 | 380 committed. |
bos@124 | 381 \item It commits the result as a new changeset. This changeset has |
bos@124 | 382 \texttt{backout} as its parent. |
bos@124 | 383 \item If you specify \hgopt{backout}{--merge} on the command line, it |
bos@124 | 384 merges with \texttt{orig}, and commits the result of the merge. |
bos@124 | 385 \end{enumerate} |
bos@124 | 386 |
bos@124 | 387 An alternative way to implement the \hgcmd{backout} command would be |
bos@124 | 388 to \hgcmd{export} the to-be-backed-out changeset as a diff, then use |
bos@124 | 389 the \cmdopt{patch}{--reverse} option to the \command{patch} command to |
bos@124 | 390 reverse the effect of the change without fiddling with the working |
bos@124 | 391 directory. This sounds much simpler, but it would not work nearly as |
bos@124 | 392 well. |
bos@124 | 393 |
bos@124 | 394 The reason that \hgcmd{backout} does an update, a commit, a merge, and |
bos@124 | 395 another commit is to give the merge machinery the best chance to do a |
bos@124 | 396 good job when dealing with all the changes \emph{between} the change |
bos@124 | 397 you're backing out and the current tip. |
bos@124 | 398 |
bos@124 | 399 If you're backing out a changeset that's~100 revisions back in your |
bos@124 | 400 project's history, the chances that the \command{patch} command will |
bos@124 | 401 be able to apply a reverse diff cleanly are not good, because |
bos@124 | 402 intervening changes are likely to have ``broken the context'' that |
bos@124 | 403 \command{patch} uses to determine whether it can apply a patch (if |
bos@125 | 404 this sounds like gibberish, see \ref{sec:mq:patch} for a |
bos@124 | 405 discussion of the \command{patch} command). Also, Mercurial's merge |
bos@124 | 406 machinery will handle files and directories being renamed, permission |
bos@124 | 407 changes, and modifications to binary files, none of which |
bos@124 | 408 \command{patch} can deal with. |
bos@124 | 409 |
bos@126 | 410 \section{Changes that should never have been} |
bos@126 | 411 \label{sec:undo:aaaiiieee} |
bos@126 | 412 |
bos@126 | 413 Most of the time, the \hgcmd{backout} command is exactly what you need |
bos@126 | 414 if you want to undo the effects of a change. It leaves a permanent |
bos@126 | 415 record of exactly what you did, both when committing the original |
bos@126 | 416 changeset and when you cleaned up after it. |
bos@126 | 417 |
bos@126 | 418 On rare occasions, though, you may find that you've committed a change |
bos@126 | 419 that really should not be present in the repository at all. For |
bos@126 | 420 example, it would be very unusual, and usually considered a mistake, |
bos@126 | 421 to commit a software project's object files as well as its source |
bos@126 | 422 files. Object files have almost no intrinsic value, and they're |
bos@126 | 423 \emph{big}, so they increase the size of the repository and the amount |
bos@126 | 424 of time it takes to clone or pull changes. |
bos@126 | 425 |
bos@126 | 426 Before I discuss the options that you have if you commit a ``brown |
bos@126 | 427 paper bag'' change (the kind that's so bad that you want to pull a |
bos@126 | 428 brown paper bag over your head), let me first discuss some approaches |
bos@126 | 429 that probably won't work. |
bos@126 | 430 |
bos@126 | 431 Since Mercurial treats history as accumulative---every change builds |
bos@126 | 432 on top of all changes that preceded it---you generally can't just make |
bos@126 | 433 disastrous changes disappear. The one exception is when you've just |
bos@126 | 434 committed a change, and it hasn't been pushed or pulled into another |
bos@126 | 435 repository. That's when you can safely use the \hgcmd{rollback} |
bos@126 | 436 command, as I detailed in section~\ref{sec:undo:rollback}. |
bos@126 | 437 |
bos@126 | 438 After you've pushed a bad change to another repository, you |
bos@126 | 439 \emph{could} still use \hgcmd{rollback} to make your local copy of the |
bos@126 | 440 change disappear, but it won't have the consequences you want. The |
bos@126 | 441 change will still be present in the remote repository, so it will |
bos@126 | 442 reappear in your local repository the next time you pull. |
bos@126 | 443 |
bos@126 | 444 If a situation like this arises, and you know which repositories your |
bos@126 | 445 bad change has propagated into, you can \emph{try} to get rid of the |
bos@126 | 446 changeefrom \emph{every} one of those repositories. This is, of |
bos@126 | 447 course, not a satisfactory solution: if you miss even a single |
bos@126 | 448 repository while you're expunging, the change is still ``in the |
bos@126 | 449 wild'', and could propagate further. |
bos@126 | 450 |
bos@126 | 451 If you've committed one or more changes \emph{after} the change that |
bos@126 | 452 you'd like to see disappear, your options are further reduced. |
bos@126 | 453 Mercurial doesn't provide a way to ``punch a hole'' in history, |
bos@126 | 454 leaving changesets intact. |
bos@126 | 455 |
bos@129 | 456 XXX This needs filling out. The \texttt{hg-replay} script in the |
bos@129 | 457 \texttt{examples} directory works, but doesn't handle merge |
bos@129 | 458 changesets. Kind of an important omission. |
bos@129 | 459 |
bos@201 | 460 \subsection{Protect yourself from ``escaped'' changes} |
bos@201 | 461 |
bos@201 | 462 If you've committed some changes to your local repository and they've |
bos@201 | 463 been pushed or pulled somewhere else, this isn't necessarily a |
bos@201 | 464 disaster. You can protect yourself ahead of time against some classes |
bos@201 | 465 of bad changeset. This is particularly easy if your team usually |
bos@201 | 466 pulls changes from a central repository. |
bos@201 | 467 |
bos@201 | 468 By configuring some hooks on that repository to validate incoming |
bos@201 | 469 changesets (see chapter~\ref{chap:hook}), you can automatically |
bos@201 | 470 prevent some kinds of bad changeset from being pushed to the central |
bos@201 | 471 repository at all. With such a configuration in place, some kinds of |
bos@201 | 472 bad changeset will naturally tend to ``die out'' because they can't |
bos@201 | 473 propagate into the central repository. Better yet, this happens |
bos@201 | 474 without any need for explicit intervention. |
bos@201 | 475 |
bos@201 | 476 For instance, an incoming change hook that verifies that a changeset |
bos@201 | 477 will actually compile can prevent people from inadvertantly ``breaking |
bos@201 | 478 the build''. |
bos@201 | 479 |
bos@130 | 480 \section{Finding the source of a bug} |
bos@200 | 481 \label{sec:undo:bisect} |
bos@130 | 482 |
bos@130 | 483 While it's all very well to be able to back out a changeset that |
bos@130 | 484 introduced a bug, this requires that you know which changeset to back |
bos@130 | 485 out. Mercurial provides an invaluable extension, called |
bos@130 | 486 \hgext{bisect}, that helps you to automate this process and accomplish |
bos@130 | 487 it very efficiently. |
bos@130 | 488 |
bos@130 | 489 The idea behind the \hgext{bisect} extension is that a changeset has |
bos@130 | 490 introduced some change of behaviour that you can identify with a |
bos@130 | 491 simple binary test. You don't know which piece of code introduced the |
bos@130 | 492 change, but you know how to test for the presence of the bug. The |
bos@130 | 493 \hgext{bisect} extension uses your test to direct its search for the |
bos@130 | 494 changeset that introduced the code that caused the bug. |
bos@130 | 495 |
bos@130 | 496 Here are a few scenarios to help you understand how you might apply this |
bos@130 | 497 extension. |
bos@130 | 498 \begin{itemize} |
bos@130 | 499 \item The most recent version of your software has a bug that you |
bos@130 | 500 remember wasn't present a few weeks ago, but you don't know when it |
bos@130 | 501 was introduced. Here, your binary test checks for the presence of |
bos@130 | 502 that bug. |
bos@130 | 503 \item You fixed a bug in a rush, and now it's time to close the entry |
bos@130 | 504 in your team's bug database. The bug database requires a changeset |
bos@130 | 505 ID when you close an entry, but you don't remember which changeset |
bos@130 | 506 you fixed the bug in. Once again, your binary test checks for the |
bos@130 | 507 presence of the bug. |
bos@130 | 508 \item Your software works correctly, but runs~15\% slower than the |
bos@130 | 509 last time you measured it. You want to know which changeset |
bos@130 | 510 introduced the performance regression. In this case, your binary |
bos@130 | 511 test measures the performance of your software, to see whether it's |
bos@130 | 512 ``fast'' or ``slow''. |
bos@130 | 513 \item The sizes of the components of your project that you ship |
bos@130 | 514 exploded recently, and you suspect that something changed in the way |
bos@130 | 515 you build your project. |
bos@130 | 516 \end{itemize} |
bos@130 | 517 |
bos@130 | 518 From these examples, it should be clear that the \hgext{bisect} |
bos@130 | 519 extension is not useful only for finding the sources of bugs. You can |
bos@130 | 520 use it to find any ``emergent property'' of a repository (anything |
bos@130 | 521 that you can't find from a simple text search of the files in the |
bos@130 | 522 tree) for which you can write a binary test. |
bos@130 | 523 |
bos@130 | 524 We'll introduce a little bit of terminology here, just to make it |
bos@130 | 525 clear which parts of the search process are your responsibility, and |
bos@130 | 526 which are Mercurial's. A \emph{test} is something that \emph{you} run |
bos@130 | 527 when \hgext{bisect} chooses a changeset. A \emph{probe} is what |
bos@130 | 528 \hgext{bisect} runs to tell whether a revision is good. Finally, |
bos@130 | 529 we'll use the word ``bisect'', as both a noun and a verb, to stand in |
bos@130 | 530 for the phrase ``search using the \hgext{bisect} extension''. |
bos@130 | 531 |
bos@130 | 532 One simple way to automate the searching process would be simply to |
bos@130 | 533 probe every changeset. However, this scales poorly. If it took ten |
bos@130 | 534 minutes to test a single changeset, and you had 10,000 changesets in |
bos@130 | 535 your repository, the exhaustive approach would take on average~35 |
bos@130 | 536 \emph{days} to find the changeset that introduced a bug. Even if you |
bos@130 | 537 knew that the bug was introduced by one of the last 500 changesets, |
bos@130 | 538 and limited your search to those, you'd still be looking at over 40 |
bos@130 | 539 hours to find the changeset that introduced your bug. |
bos@130 | 540 |
bos@130 | 541 What the \emph{bisect} extension does is use its knowledge of the |
bos@130 | 542 ``shape'' of your project's revision history to perform a search in |
bos@130 | 543 time proportional to the \emph{logarithm} of the number of changesets |
bos@130 | 544 to check (the kind of search it performs is called a dichotomic |
bos@130 | 545 search). With this approach, searching through 10,000 changesets will |
bos@130 | 546 take less than two hours, even at ten minutes per test. Limit your |
bos@130 | 547 search to the last 500 changesets, and it will take less than an hour. |
bos@130 | 548 |
bos@130 | 549 The \hgext{bisect} extension is aware of the ``branchy'' nature of a |
bos@130 | 550 Mercurial project's revision history, so it has no problems dealing |
bos@130 | 551 with branches, merges, or multiple heads in a repoository. It can |
bos@130 | 552 prune entire branches of history with a single probe, which is how it |
bos@130 | 553 operates so efficiently. |
bos@130 | 554 |
bos@130 | 555 \subsection{Using the \hgext{bisect} extension} |
bos@130 | 556 |
bos@130 | 557 Here's an example of \hgext{bisect} in action. To keep the core of |
bos@130 | 558 Mercurial simple, \hgext{bisect} is packaged as an extension; this |
bos@130 | 559 means that it won't be present unless you explicitly enable it. To do |
bos@130 | 560 this, edit your \hgrc\ and add the following section header (if it's |
bos@130 | 561 not already present): |
bos@130 | 562 \begin{codesample2} |
bos@130 | 563 [extensions] |
bos@130 | 564 \end{codesample2} |
bos@130 | 565 Then add a line to this section to enable the extension: |
bos@130 | 566 \begin{codesample2} |
bos@130 | 567 hbisect = |
bos@130 | 568 \end{codesample2} |
bos@130 | 569 \begin{note} |
bos@130 | 570 That's right, there's a ``\texttt{h}'' at the front of the name of |
bos@130 | 571 the \hgext{bisect} extension. The reason is that Mercurial is |
bos@130 | 572 written in Python, and uses a standard Python package called |
bos@130 | 573 \texttt{bisect}. If you omit the ``\texttt{h}'' from the name |
bos@130 | 574 ``\texttt{hbisect}'', Mercurial will erroneously find the standard |
bos@130 | 575 Python \texttt{bisect} package, and try to use it as a Mercurial |
bos@130 | 576 extension. This won't work, and Mercurial will crash repeatedly |
bos@130 | 577 until you fix the spelling in your \hgrc. Ugh. |
bos@130 | 578 \end{note} |
bos@130 | 579 |
bos@130 | 580 Now let's create a repository, so that we can try out the |
bos@130 | 581 \hgext{bisect} extension in isolation. |
bos@130 | 582 \interaction{bisect.init} |
bos@130 | 583 We'll simulate a project that has a bug in it in a simple-minded way: |
bos@130 | 584 create trivial changes in a loop, and nominate one specific change |
bos@130 | 585 that will have the ``bug''. This loop creates 50 changesets, each |
bos@130 | 586 adding a single file to the repository. We'll represent our ``bug'' |
bos@130 | 587 with a file that contains the text ``i have a gub''. |
bos@130 | 588 \interaction{bisect.commits} |
bos@130 | 589 |
bos@130 | 590 The next thing that we'd like to do is figure out how to use the |
bos@130 | 591 \hgext{bisect} extension. We can use Mercurial's normal built-in help |
bos@130 | 592 mechanism for this. |
bos@130 | 593 \interaction{bisect.help} |
bos@130 | 594 |
bos@130 | 595 The \hgext{bisect} extension works in steps. Each step proceeds as follows. |
bos@130 | 596 \begin{enumerate} |
bos@130 | 597 \item You run your binary test. |
bos@130 | 598 \begin{itemize} |
bos@130 | 599 \item If the test succeeded, you tell \hgext{bisect} by running the |
bos@130 | 600 \hgcmdargs{bisect}{good} command. |
bos@130 | 601 \item If it failed, use the \hgcmdargs{bisect}{bad} command to let |
bos@130 | 602 the \hgext{bisect} extension know. |
bos@130 | 603 \end{itemize} |
bos@130 | 604 \item The extension uses your information to decide which changeset to |
bos@130 | 605 test next. |
bos@130 | 606 \item It updates the working directory to that changeset, and the |
bos@130 | 607 process begins again. |
bos@130 | 608 \end{enumerate} |
bos@130 | 609 The process ends when \hgext{bisect} identifies a unique changeset |
bos@130 | 610 that marks the point where your test transitioned from ``succeeding'' |
bos@130 | 611 to ``failing''. |
bos@130 | 612 |
bos@130 | 613 To start the search, we must run the \hgcmdargs{bisect}{init} command. |
bos@130 | 614 \interaction{bisect.search.init} |
bos@130 | 615 |
bos@130 | 616 In our case, the binary test we use is simple: we check to see if any |
bos@130 | 617 file in the repository contains the string ``i have a gub''. If it |
bos@130 | 618 does, this changeset contains the change that ``caused the bug''. By |
bos@130 | 619 convention, a changeset that has the property we're searching for is |
bos@130 | 620 ``bad'', while one that doesn't is ``good''. |
bos@130 | 621 |
bos@130 | 622 Most of the time, the revision to which the working directory is |
bos@130 | 623 synced (usually the tip) already exhibits the problem introduced by |
bos@130 | 624 the buggy change, so we'll mark it as ``bad''. |
bos@130 | 625 \interaction{bisect.search.bad-init} |
bos@130 | 626 |
bos@130 | 627 Our next task is to nominate a changeset that we know \emph{doesn't} |
bos@130 | 628 have the bug; the \hgext{bisect} extension will ``bracket'' its search |
bos@130 | 629 between the first pair of good and bad changesets. In our case, we |
bos@130 | 630 know that revision~10 didn't have the bug. (I'll have more words |
bos@130 | 631 about choosing the first ``good'' changeset later.) |
bos@130 | 632 \interaction{bisect.search.good-init} |
bos@130 | 633 |
bos@130 | 634 Notice that this command printed some output. |
bos@130 | 635 \begin{itemize} |
bos@130 | 636 \item It told us how many changesets it must consider before it can |
bos@130 | 637 identify the one that introduced the bug, and how many tests that |
bos@130 | 638 will require. |
bos@130 | 639 \item It updated the working directory to the next changeset to test, |
bos@130 | 640 and told us which changeset it's testing. |
bos@130 | 641 \end{itemize} |
bos@130 | 642 |
bos@130 | 643 We now run our test in the working directory. We use the |
bos@130 | 644 \command{grep} command to see if our ``bad'' file is present in the |
bos@130 | 645 working directory. If it is, this revision is bad; if not, this |
bos@130 | 646 revision is good. |
bos@131 | 647 \interaction{bisect.search.step1} |
bos@130 | 648 |
bos@130 | 649 This test looks like a perfect candidate for automation, so let's turn |
bos@130 | 650 it into a shell function. |
bos@131 | 651 \interaction{bisect.search.mytest} |
bos@130 | 652 We can now run an entire test step with a single command, |
bos@130 | 653 \texttt{mytest}. |
bos@131 | 654 \interaction{bisect.search.step2} |
bos@130 | 655 A few more invocations of our canned test step command, and we're |
bos@130 | 656 done. |
bos@131 | 657 \interaction{bisect.search.rest} |
bos@130 | 658 |
bos@130 | 659 Even though we had~40 changesets to search through, the \hgext{bisect} |
bos@130 | 660 extension let us find the changeset that introduced our ``bug'' with |
bos@130 | 661 only five tests. Because the number of tests that the \hgext{bisect} |
bos@130 | 662 extension grows logarithmically with the number of changesets to |
bos@130 | 663 search, the advantage that it has over the ``brute force'' search |
bos@130 | 664 approach increases with every changeset you add. |
bos@130 | 665 |
bos@130 | 666 \subsection{Cleaning up after your search} |
bos@130 | 667 |
bos@130 | 668 When you're finished using the \hgext{bisect} extension in a |
bos@130 | 669 repository, you can use the \hgcmdargs{bisect}{reset} command to drop |
bos@130 | 670 the information it was using to drive your search. The extension |
bos@130 | 671 doesn't use much space, so it doesn't matter if you forget to run this |
bos@130 | 672 command. However, \hgext{bisect} won't let you start a new search in |
bos@130 | 673 that repository until you do a \hgcmdargs{bisect}{reset}. |
bos@131 | 674 \interaction{bisect.search.reset} |
bos@130 | 675 |
bos@130 | 676 \section{Tips for finding bugs effectively} |
bos@130 | 677 |
bos@130 | 678 \subsection{Give consistent input} |
bos@130 | 679 |
bos@130 | 680 The \hgext{bisect} extension requires that you correctly report the |
bos@130 | 681 result of every test you perform. If you tell it that a test failed |
bos@130 | 682 when it really succeeded, it \emph{might} be able to detect the |
bos@130 | 683 inconsistency. If it can identify an inconsistency in your reports, |
bos@130 | 684 it will tell you that a particular changeset is both good and bad. |
bos@130 | 685 However, it can't do this perfectly; it's about as likely to report |
bos@130 | 686 the wrong changeset as the source of the bug. |
bos@130 | 687 |
bos@130 | 688 \subsection{Automate as much as possible} |
bos@130 | 689 |
bos@130 | 690 When I started using the \hgext{bisect} extension, I tried a few times |
bos@130 | 691 to run my tests by hand, on the command line. This is an approach |
bos@130 | 692 that I, at least, am not suited to. After a few tries, I found that I |
bos@130 | 693 was making enough mistakes that I was having to restart my searches |
bos@130 | 694 several times before finally getting correct results. |
bos@130 | 695 |
bos@130 | 696 My initial problems with driving the \hgext{bisect} extension by hand |
bos@130 | 697 occurred even with simple searches on small repositories; if the |
bos@130 | 698 problem you're looking for is more subtle, or the number of tests that |
bos@130 | 699 \hgext{bisect} must perform increases, the likelihood of operator |
bos@130 | 700 error ruining the search is much higher. Once I started automating my |
bos@130 | 701 tests, I had much better results. |
bos@130 | 702 |
bos@130 | 703 The key to automated testing is twofold: |
bos@130 | 704 \begin{itemize} |
bos@130 | 705 \item always test for the same symptom, and |
bos@130 | 706 \item always feed consistent input to the \hgcmd{bisect} command. |
bos@130 | 707 \end{itemize} |
bos@130 | 708 In my tutorial example above, the \command{grep} command tests for the |
bos@130 | 709 symptom, and the \texttt{if} statement takes the result of this check |
bos@130 | 710 and ensures that we always feed the same input to the \hgcmd{bisect} |
bos@130 | 711 command. The \texttt{mytest} function marries these together in a |
bos@130 | 712 reproducible way, so that every test is uniform and consistent. |
bos@130 | 713 |
bos@130 | 714 \subsection{Check your results} |
bos@130 | 715 |
bos@130 | 716 Because the output of a \hgext{bisect} search is only as good as the |
bos@130 | 717 input you give it, don't take the changeset it reports as the |
bos@130 | 718 absolute truth. A simple way to cross-check its report is to manually |
bos@130 | 719 run your test at each of the following changesets: |
bos@130 | 720 \begin{itemize} |
bos@130 | 721 \item The changeset that it reports as the first bad revision. Your |
bos@130 | 722 test should still report this as bad. |
bos@130 | 723 \item The parent of that changeset (either parent, if it's a merge). |
bos@130 | 724 Your test should report this changeset as good. |
bos@130 | 725 \item A child of that changeset. Your test should report this |
bos@130 | 726 changeset as bad. |
bos@130 | 727 \end{itemize} |
bos@130 | 728 |
bos@130 | 729 \subsection{Beware interference between bugs} |
bos@130 | 730 |
bos@130 | 731 It's possible that your search for one bug could be disrupted by the |
bos@130 | 732 presence of another. For example, let's say your software crashes at |
bos@130 | 733 revision 100, and worked correctly at revision 50. Unknown to you, |
bos@130 | 734 someone else introduced a different crashing bug at revision 60, and |
bos@130 | 735 fixed it at revision 80. This could distort your results in one of |
bos@130 | 736 several ways. |
bos@130 | 737 |
bos@130 | 738 It is possible that this other bug completely ``masks'' yours, which |
bos@130 | 739 is to say that it occurs before your bug has a chance to manifest |
bos@130 | 740 itself. If you can't avoid that other bug (for example, it prevents |
bos@130 | 741 your project from building), and so can't tell whether your bug is |
bos@130 | 742 present in a particular changeset, the \hgext{bisect} extension cannot |
bos@130 | 743 help you directly. Instead, you'll need to manually avoid the |
bos@130 | 744 changesets where that bug is present, and do separate searches |
bos@130 | 745 ``around'' it. |
bos@130 | 746 |
bos@130 | 747 A different problem could arise if your test for a bug's presence is |
wbunaarfubss@248 | 748 not specific enough. If you check for ``my program crashes'', then |
bos@130 | 749 both your crashing bug and an unrelated crashing bug that masks it |
bos@130 | 750 will look like the same thing, and mislead \hgext{bisect}. |
bos@130 | 751 |
bos@130 | 752 \subsection{Bracket your search lazily} |
bos@130 | 753 |
bos@130 | 754 Choosing the first ``good'' and ``bad'' changesets that will mark the |
bos@130 | 755 end points of your search is often easy, but it bears a little |
mrowe@257 | 756 discussion nevertheless. From the perspective of \hgext{bisect}, the |
bos@130 | 757 ``newest'' changeset is conventionally ``bad'', and the older |
bos@130 | 758 changeset is ``good''. |
bos@130 | 759 |
bos@130 | 760 If you're having trouble remembering when a suitable ``good'' change |
bos@130 | 761 was, so that you can tell \hgext{bisect}, you could do worse than |
bos@130 | 762 testing changesets at random. Just remember to eliminate contenders |
bos@130 | 763 that can't possibly exhibit the bug (perhaps because the feature with |
bos@130 | 764 the bug isn't present yet) and those where another problem masks the |
bos@130 | 765 bug (as I discussed above). |
bos@130 | 766 |
bos@130 | 767 Even if you end up ``early'' by thousands of changesets or months of |
bos@130 | 768 history, you will only add a handful of tests to the total number that |
bos@130 | 769 \hgext{bisect} must perform, thanks to its logarithmic behaviour. |
bos@130 | 770 |
bos@121 | 771 %%% Local Variables: |
bos@121 | 772 %%% mode: latex |
bos@121 | 773 %%% TeX-master: "00book" |
bos@121 | 774 %%% End: |