hgbook

annotate en/undo.tex @ 514:db12ab3b3b25

find changesets by author, revision, files, or words in the commit message
corrected some typos on the title page.

translated a couple of index entries
author Javier Rojas <jerojasro@devnull.li>
date Sun Jan 18 19:45:33 2009 -0500 (2009-01-18)
parents 7a6bd93174bd
children f79542a53cb2 91adcea08b33
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
simon@313 197 % TODO: the output doesn't look like it will be removed!
simon@313 198
bos@122 199 (By the way, if you rename a file, then modify the renamed-to file,
bos@122 200 then revert both components of the rename, when Mercurial restores the
bos@122 201 file that was removed as part of the rename, it will be unmodified.
bos@122 202 If you need the modifications in the renamed-to file to show up in the
bos@122 203 renamed-from file, don't forget to copy them over.)
bos@122 204
bos@123 205 These fiddly aspects of reverting a rename arguably constitute a small
bos@122 206 bug in Mercurial.
bos@122 207
bos@124 208 \section{Dealing with committed changes}
bos@124 209
bos@124 210 Consider a case where you have committed a change $a$, and another
bos@124 211 change $b$ on top of it; you then realise that change $a$ was
bos@124 212 incorrect. Mercurial lets you ``back out'' an entire changeset
bos@124 213 automatically, and building blocks that let you reverse part of a
bos@124 214 changeset by hand.
bos@124 215
bos@126 216 Before you read this section, here's something to keep in mind: the
bos@126 217 \hgcmd{backout} command undoes changes by \emph{adding} history, not
bos@126 218 by modifying or erasing it. It's the right tool to use if you're
bos@126 219 fixing bugs, but not if you're trying to undo some change that has
bos@126 220 catastrophic consequences. To deal with those, see
bos@126 221 section~\ref{sec:undo:aaaiiieee}.
bos@126 222
bos@124 223 \subsection{Backing out a changeset}
bos@124 224
bos@124 225 The \hgcmd{backout} command lets you ``undo'' the effects of an entire
bos@124 226 changeset in an automated fashion. Because Mercurial's history is
bos@124 227 immutable, this command \emph{does not} get rid of the changeset you
bos@124 228 want to undo. Instead, it creates a new changeset that
bos@124 229 \emph{reverses} the effect of the to-be-undone changeset.
bos@124 230
bos@124 231 The operation of the \hgcmd{backout} command is a little intricate, so
bos@124 232 let's illustrate it with some examples. First, we'll create a
bos@124 233 repository with some simple changes.
bos@124 234 \interaction{backout.init}
bos@124 235
bos@124 236 The \hgcmd{backout} command takes a single changeset ID as its
bos@124 237 argument; this is the changeset to back out. Normally,
bos@124 238 \hgcmd{backout} will drop you into a text editor to write a commit
bos@124 239 message, so you can record why you're backing the change out. In this
bos@124 240 example, we provide a commit message on the command line using the
bos@124 241 \hgopt{backout}{-m} option.
bos@124 242
bos@124 243 \subsection{Backing out the tip changeset}
bos@124 244
bos@124 245 We're going to start by backing out the last changeset we committed.
bos@124 246 \interaction{backout.simple}
bos@124 247 You can see that the second line from \filename{myfile} is no longer
bos@124 248 present. Taking a look at the output of \hgcmd{log} gives us an idea
bos@124 249 of what the \hgcmd{backout} command has done.
bos@124 250 \interaction{backout.simple.log}
bos@124 251 Notice that the new changeset that \hgcmd{backout} has created is a
bos@124 252 child of the changeset we backed out. It's easier to see this in
bos@124 253 figure~\ref{fig:undo:backout}, which presents a graphical view of the
bos@124 254 change history. As you can see, the history is nice and linear.
bos@124 255
bos@124 256 \begin{figure}[htb]
bos@124 257 \centering
bos@124 258 \grafix{undo-simple}
bos@124 259 \caption{Backing out a change using the \hgcmd{backout} command}
bos@124 260 \label{fig:undo:backout}
bos@124 261 \end{figure}
bos@124 262
bos@124 263 \subsection{Backing out a non-tip change}
bos@124 264
bos@124 265 If you want to back out a change other than the last one you
bos@124 266 committed, pass the \hgopt{backout}{--merge} option to the
bos@124 267 \hgcmd{backout} command.
bos@124 268 \interaction{backout.non-tip.clone}
bos@124 269 This makes backing out any changeset a ``one-shot'' operation that's
bos@124 270 usually simple and fast.
bos@124 271 \interaction{backout.non-tip.backout}
bos@124 272
bos@124 273 If you take a look at the contents of \filename{myfile} after the
bos@124 274 backout finishes, you'll see that the first and third changes are
bos@124 275 present, but not the second.
bos@124 276 \interaction{backout.non-tip.cat}
bos@124 277
bos@124 278 As the graphical history in figure~\ref{fig:undo:backout-non-tip}
bos@124 279 illustrates, Mercurial actually commits \emph{two} changes in this
bos@124 280 kind of situation (the box-shaped nodes are the ones that Mercurial
bos@124 281 commits automatically). Before Mercurial begins the backout process,
bos@124 282 it first remembers what the current parent of the working directory
bos@124 283 is. It then backs out the target changeset, and commits that as a
bos@124 284 changeset. Finally, it merges back to the previous parent of the
bos@124 285 working directory, and commits the result of the merge.
bos@124 286
simon@313 287 % TODO: to me it looks like mercurial doesn't commit the second merge automatically!
simon@313 288
bos@124 289 \begin{figure}[htb]
bos@124 290 \centering
bos@124 291 \grafix{undo-non-tip}
bos@124 292 \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
bos@124 293 \label{fig:undo:backout-non-tip}
bos@124 294 \end{figure}
bos@124 295
bos@124 296 The result is that you end up ``back where you were'', only with some
bos@124 297 extra history that undoes the effect of the changeset you wanted to
bos@124 298 back out.
bos@124 299
bos@124 300 \subsubsection{Always use the \hgopt{backout}{--merge} option}
bos@124 301
bos@124 302 In fact, since the \hgopt{backout}{--merge} option will do the ``right
bos@124 303 thing'' whether or not the changeset you're backing out is the tip
bos@124 304 (i.e.~it won't try to merge if it's backing out the tip, since there's
bos@124 305 no need), you should \emph{always} use this option when you run the
bos@124 306 \hgcmd{backout} command.
bos@124 307
bos@124 308 \subsection{Gaining more control of the backout process}
bos@124 309
bos@124 310 While I've recommended that you always use the
bos@124 311 \hgopt{backout}{--merge} option when backing out a change, the
bos@124 312 \hgcmd{backout} command lets you decide how to merge a backout
bos@124 313 changeset. Taking control of the backout process by hand is something
bos@124 314 you will rarely need to do, but it can be useful to understand what
bos@124 315 the \hgcmd{backout} command is doing for you automatically. To
bos@124 316 illustrate this, let's clone our first repository, but omit the
bos@124 317 backout change that it contains.
bos@124 318
bos@124 319 \interaction{backout.manual.clone}
bos@124 320 As with our earlier example, We'll commit a third changeset, then back
bos@124 321 out its parent, and see what happens.
bos@124 322 \interaction{backout.manual.backout}
bos@124 323 Our new changeset is again a descendant of the changeset we backout
bos@124 324 out; it's thus a new head, \emph{not} a descendant of the changeset
bos@124 325 that was the tip. The \hgcmd{backout} command was quite explicit in
bos@124 326 telling us this.
bos@124 327 \interaction{backout.manual.log}
bos@124 328
bos@124 329 Again, it's easier to see what has happened by looking at a graph of
bos@124 330 the revision history, in figure~\ref{fig:undo:backout-manual}. This
bos@124 331 makes it clear that when we use \hgcmd{backout} to back out a change
bos@124 332 other than the tip, Mercurial adds a new head to the repository (the
bos@124 333 change it committed is box-shaped).
bos@124 334
bos@124 335 \begin{figure}[htb]
bos@124 336 \centering
bos@124 337 \grafix{undo-manual}
bos@124 338 \caption{Backing out a change using the \hgcmd{backout} command}
bos@124 339 \label{fig:undo:backout-manual}
bos@124 340 \end{figure}
bos@124 341
bos@124 342 After the \hgcmd{backout} command has completed, it leaves the new
bos@124 343 ``backout'' changeset as the parent of the working directory.
bos@124 344 \interaction{backout.manual.parents}
bos@124 345 Now we have two isolated sets of changes.
bos@124 346 \interaction{backout.manual.heads}
bos@124 347
bos@124 348 Let's think about what we expect to see as the contents of
bos@124 349 \filename{myfile} now. The first change should be present, because
bos@124 350 we've never backed it out. The second change should be missing, as
bos@124 351 that's the change we backed out. Since the history graph shows the
bos@124 352 third change as a separate head, we \emph{don't} expect to see the
bos@124 353 third change present in \filename{myfile}.
bos@124 354 \interaction{backout.manual.cat}
bos@124 355 To get the third change back into the file, we just do a normal merge
bos@124 356 of our two heads.
bos@124 357 \interaction{backout.manual.merge}
bos@124 358 Afterwards, the graphical history of our repository looks like
bos@124 359 figure~\ref{fig:undo:backout-manual-merge}.
bos@124 360
bos@124 361 \begin{figure}[htb]
bos@124 362 \centering
bos@124 363 \grafix{undo-manual-merge}
bos@124 364 \caption{Manually merging a backout change}
bos@124 365 \label{fig:undo:backout-manual-merge}
bos@124 366 \end{figure}
bos@124 367
bos@126 368 \subsection{Why \hgcmd{backout} works as it does}
bos@124 369
bos@124 370 Here's a brief description of how the \hgcmd{backout} command works.
bos@124 371 \begin{enumerate}
bos@124 372 \item It ensures that the working directory is ``clean'', i.e.~that
bos@124 373 the output of \hgcmd{status} would be empty.
bos@124 374 \item It remembers the current parent of the working directory. Let's
bos@124 375 call this changeset \texttt{orig}
bos@124 376 \item It does the equivalent of a \hgcmd{update} to sync the working
bos@124 377 directory to the changeset you want to back out. Let's call this
bos@124 378 changeset \texttt{backout}
bos@124 379 \item It finds the parent of that changeset. Let's call that
bos@124 380 changeset \texttt{parent}.
bos@124 381 \item For each file that the \texttt{backout} changeset affected, it
bos@124 382 does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
bos@124 383 to restore it to the contents it had before that changeset was
bos@124 384 committed.
bos@124 385 \item It commits the result as a new changeset. This changeset has
bos@124 386 \texttt{backout} as its parent.
bos@124 387 \item If you specify \hgopt{backout}{--merge} on the command line, it
bos@124 388 merges with \texttt{orig}, and commits the result of the merge.
bos@124 389 \end{enumerate}
bos@124 390
bos@124 391 An alternative way to implement the \hgcmd{backout} command would be
bos@124 392 to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
bos@124 393 the \cmdopt{patch}{--reverse} option to the \command{patch} command to
bos@124 394 reverse the effect of the change without fiddling with the working
bos@124 395 directory. This sounds much simpler, but it would not work nearly as
bos@124 396 well.
bos@124 397
bos@124 398 The reason that \hgcmd{backout} does an update, a commit, a merge, and
bos@124 399 another commit is to give the merge machinery the best chance to do a
bos@124 400 good job when dealing with all the changes \emph{between} the change
bos@124 401 you're backing out and the current tip.
bos@124 402
bos@124 403 If you're backing out a changeset that's~100 revisions back in your
bos@124 404 project's history, the chances that the \command{patch} command will
bos@124 405 be able to apply a reverse diff cleanly are not good, because
bos@124 406 intervening changes are likely to have ``broken the context'' that
bos@124 407 \command{patch} uses to determine whether it can apply a patch (if
bos@125 408 this sounds like gibberish, see \ref{sec:mq:patch} for a
bos@124 409 discussion of the \command{patch} command). Also, Mercurial's merge
bos@124 410 machinery will handle files and directories being renamed, permission
bos@124 411 changes, and modifications to binary files, none of which
bos@124 412 \command{patch} can deal with.
bos@124 413
bos@126 414 \section{Changes that should never have been}
bos@126 415 \label{sec:undo:aaaiiieee}
bos@126 416
bos@126 417 Most of the time, the \hgcmd{backout} command is exactly what you need
bos@126 418 if you want to undo the effects of a change. It leaves a permanent
bos@126 419 record of exactly what you did, both when committing the original
bos@126 420 changeset and when you cleaned up after it.
bos@126 421
bos@126 422 On rare occasions, though, you may find that you've committed a change
bos@126 423 that really should not be present in the repository at all. For
bos@126 424 example, it would be very unusual, and usually considered a mistake,
bos@126 425 to commit a software project's object files as well as its source
bos@126 426 files. Object files have almost no intrinsic value, and they're
bos@126 427 \emph{big}, so they increase the size of the repository and the amount
bos@126 428 of time it takes to clone or pull changes.
bos@126 429
bos@126 430 Before I discuss the options that you have if you commit a ``brown
bos@126 431 paper bag'' change (the kind that's so bad that you want to pull a
bos@126 432 brown paper bag over your head), let me first discuss some approaches
bos@126 433 that probably won't work.
bos@126 434
bos@126 435 Since Mercurial treats history as accumulative---every change builds
bos@126 436 on top of all changes that preceded it---you generally can't just make
bos@126 437 disastrous changes disappear. The one exception is when you've just
bos@126 438 committed a change, and it hasn't been pushed or pulled into another
bos@126 439 repository. That's when you can safely use the \hgcmd{rollback}
bos@126 440 command, as I detailed in section~\ref{sec:undo:rollback}.
bos@126 441
bos@126 442 After you've pushed a bad change to another repository, you
bos@126 443 \emph{could} still use \hgcmd{rollback} to make your local copy of the
bos@126 444 change disappear, but it won't have the consequences you want. The
bos@126 445 change will still be present in the remote repository, so it will
bos@126 446 reappear in your local repository the next time you pull.
bos@126 447
bos@126 448 If a situation like this arises, and you know which repositories your
bos@126 449 bad change has propagated into, you can \emph{try} to get rid of the
bos@126 450 changeefrom \emph{every} one of those repositories. This is, of
bos@126 451 course, not a satisfactory solution: if you miss even a single
bos@126 452 repository while you're expunging, the change is still ``in the
bos@126 453 wild'', and could propagate further.
bos@126 454
bos@126 455 If you've committed one or more changes \emph{after} the change that
bos@126 456 you'd like to see disappear, your options are further reduced.
bos@126 457 Mercurial doesn't provide a way to ``punch a hole'' in history,
bos@126 458 leaving changesets intact.
bos@126 459
bos@129 460 XXX This needs filling out. The \texttt{hg-replay} script in the
bos@129 461 \texttt{examples} directory works, but doesn't handle merge
bos@129 462 changesets. Kind of an important omission.
bos@129 463
bos@201 464 \subsection{Protect yourself from ``escaped'' changes}
bos@201 465
bos@201 466 If you've committed some changes to your local repository and they've
bos@201 467 been pushed or pulled somewhere else, this isn't necessarily a
bos@201 468 disaster. You can protect yourself ahead of time against some classes
bos@201 469 of bad changeset. This is particularly easy if your team usually
bos@201 470 pulls changes from a central repository.
bos@201 471
bos@201 472 By configuring some hooks on that repository to validate incoming
bos@201 473 changesets (see chapter~\ref{chap:hook}), you can automatically
bos@201 474 prevent some kinds of bad changeset from being pushed to the central
bos@201 475 repository at all. With such a configuration in place, some kinds of
bos@201 476 bad changeset will naturally tend to ``die out'' because they can't
bos@201 477 propagate into the central repository. Better yet, this happens
bos@201 478 without any need for explicit intervention.
bos@201 479
bos@201 480 For instance, an incoming change hook that verifies that a changeset
bos@201 481 will actually compile can prevent people from inadvertantly ``breaking
bos@201 482 the build''.
bos@201 483
bos@130 484 \section{Finding the source of a bug}
bos@200 485 \label{sec:undo:bisect}
bos@130 486
bos@130 487 While it's all very well to be able to back out a changeset that
bos@130 488 introduced a bug, this requires that you know which changeset to back
bos@282 489 out. Mercurial provides an invaluable command, called
bos@282 490 \hgcmd{bisect}, that helps you to automate this process and accomplish
bos@130 491 it very efficiently.
bos@130 492
bos@282 493 The idea behind the \hgcmd{bisect} command is that a changeset has
bos@130 494 introduced some change of behaviour that you can identify with a
bos@130 495 simple binary test. You don't know which piece of code introduced the
bos@130 496 change, but you know how to test for the presence of the bug. The
bos@282 497 \hgcmd{bisect} command uses your test to direct its search for the
bos@130 498 changeset that introduced the code that caused the bug.
bos@130 499
bos@282 500 Here are a few scenarios to help you understand how you might apply
bos@282 501 this command.
bos@130 502 \begin{itemize}
bos@130 503 \item The most recent version of your software has a bug that you
bos@130 504 remember wasn't present a few weeks ago, but you don't know when it
bos@130 505 was introduced. Here, your binary test checks for the presence of
bos@130 506 that bug.
bos@130 507 \item You fixed a bug in a rush, and now it's time to close the entry
bos@130 508 in your team's bug database. The bug database requires a changeset
bos@130 509 ID when you close an entry, but you don't remember which changeset
bos@130 510 you fixed the bug in. Once again, your binary test checks for the
bos@130 511 presence of the bug.
bos@130 512 \item Your software works correctly, but runs~15\% slower than the
bos@130 513 last time you measured it. You want to know which changeset
bos@130 514 introduced the performance regression. In this case, your binary
bos@130 515 test measures the performance of your software, to see whether it's
bos@130 516 ``fast'' or ``slow''.
bos@130 517 \item The sizes of the components of your project that you ship
bos@130 518 exploded recently, and you suspect that something changed in the way
bos@130 519 you build your project.
bos@130 520 \end{itemize}
bos@130 521
bos@282 522 From these examples, it should be clear that the \hgcmd{bisect}
bos@282 523 command is not useful only for finding the sources of bugs. You can
bos@130 524 use it to find any ``emergent property'' of a repository (anything
bos@130 525 that you can't find from a simple text search of the files in the
bos@130 526 tree) for which you can write a binary test.
bos@130 527
bos@130 528 We'll introduce a little bit of terminology here, just to make it
bos@130 529 clear which parts of the search process are your responsibility, and
bos@130 530 which are Mercurial's. A \emph{test} is something that \emph{you} run
bos@282 531 when \hgcmd{bisect} chooses a changeset. A \emph{probe} is what
bos@282 532 \hgcmd{bisect} runs to tell whether a revision is good. Finally,
bos@130 533 we'll use the word ``bisect'', as both a noun and a verb, to stand in
bos@282 534 for the phrase ``search using the \hgcmd{bisect} command.
bos@130 535
bos@130 536 One simple way to automate the searching process would be simply to
bos@130 537 probe every changeset. However, this scales poorly. If it took ten
bos@130 538 minutes to test a single changeset, and you had 10,000 changesets in
bos@130 539 your repository, the exhaustive approach would take on average~35
bos@130 540 \emph{days} to find the changeset that introduced a bug. Even if you
bos@130 541 knew that the bug was introduced by one of the last 500 changesets,
bos@130 542 and limited your search to those, you'd still be looking at over 40
bos@130 543 hours to find the changeset that introduced your bug.
bos@130 544
bos@282 545 What the \hgcmd{bisect} command does is use its knowledge of the
bos@130 546 ``shape'' of your project's revision history to perform a search in
bos@130 547 time proportional to the \emph{logarithm} of the number of changesets
bos@130 548 to check (the kind of search it performs is called a dichotomic
bos@130 549 search). With this approach, searching through 10,000 changesets will
bos@282 550 take less than three hours, even at ten minutes per test (the search
bos@282 551 will require about 14 tests). Limit your search to the last hundred
bos@282 552 changesets, and it will take only about an hour (roughly seven tests).
bos@282 553
bos@282 554 The \hgcmd{bisect} command is aware of the ``branchy'' nature of a
bos@130 555 Mercurial project's revision history, so it has no problems dealing
bos@130 556 with branches, merges, or multiple heads in a repoository. It can
bos@130 557 prune entire branches of history with a single probe, which is how it
bos@130 558 operates so efficiently.
bos@130 559
bos@282 560 \subsection{Using the \hgcmd{bisect} command}
bos@282 561
bos@282 562 Here's an example of \hgcmd{bisect} in action.
bos@282 563
bos@130 564 \begin{note}
bos@282 565 In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a
bos@282 566 core command: it was distributed with Mercurial as an extension.
bos@282 567 This section describes the built-in command, not the old extension.
bos@130 568 \end{note}
bos@130 569
bos@130 570 Now let's create a repository, so that we can try out the
bos@282 571 \hgcmd{bisect} command in isolation.
bos@130 572 \interaction{bisect.init}
bos@130 573 We'll simulate a project that has a bug in it in a simple-minded way:
bos@130 574 create trivial changes in a loop, and nominate one specific change
bab@267 575 that will have the ``bug''. This loop creates 35 changesets, each
bos@130 576 adding a single file to the repository. We'll represent our ``bug''
bos@130 577 with a file that contains the text ``i have a gub''.
bos@130 578 \interaction{bisect.commits}
bos@130 579
bos@130 580 The next thing that we'd like to do is figure out how to use the
bos@282 581 \hgcmd{bisect} command. We can use Mercurial's normal built-in help
bos@130 582 mechanism for this.
bos@130 583 \interaction{bisect.help}
bos@130 584
bos@282 585 The \hgcmd{bisect} command works in steps. Each step proceeds as follows.
bos@130 586 \begin{enumerate}
bos@130 587 \item You run your binary test.
bos@130 588 \begin{itemize}
bos@282 589 \item If the test succeeded, you tell \hgcmd{bisect} by running the
bos@130 590 \hgcmdargs{bisect}{good} command.
bos@282 591 \item If it failed, run the \hgcmdargs{bisect}{--bad} command.
bos@130 592 \end{itemize}
bos@282 593 \item The command uses your information to decide which changeset to
bos@130 594 test next.
bos@130 595 \item It updates the working directory to that changeset, and the
bos@130 596 process begins again.
bos@130 597 \end{enumerate}
bos@282 598 The process ends when \hgcmd{bisect} identifies a unique changeset
bos@130 599 that marks the point where your test transitioned from ``succeeding''
bos@130 600 to ``failing''.
bos@130 601
bos@282 602 To start the search, we must run the \hgcmdargs{bisect}{--reset} command.
bos@130 603 \interaction{bisect.search.init}
bos@130 604
bos@130 605 In our case, the binary test we use is simple: we check to see if any
bos@130 606 file in the repository contains the string ``i have a gub''. If it
bos@130 607 does, this changeset contains the change that ``caused the bug''. By
bos@130 608 convention, a changeset that has the property we're searching for is
bos@130 609 ``bad'', while one that doesn't is ``good''.
bos@130 610
bos@130 611 Most of the time, the revision to which the working directory is
bos@130 612 synced (usually the tip) already exhibits the problem introduced by
bos@130 613 the buggy change, so we'll mark it as ``bad''.
bos@130 614 \interaction{bisect.search.bad-init}
bos@130 615
bos@130 616 Our next task is to nominate a changeset that we know \emph{doesn't}
bos@282 617 have the bug; the \hgcmd{bisect} command will ``bracket'' its search
bos@130 618 between the first pair of good and bad changesets. In our case, we
bos@130 619 know that revision~10 didn't have the bug. (I'll have more words
bos@130 620 about choosing the first ``good'' changeset later.)
bos@130 621 \interaction{bisect.search.good-init}
bos@130 622
bos@130 623 Notice that this command printed some output.
bos@130 624 \begin{itemize}
bos@130 625 \item It told us how many changesets it must consider before it can
bos@130 626 identify the one that introduced the bug, and how many tests that
bos@130 627 will require.
bos@130 628 \item It updated the working directory to the next changeset to test,
bos@130 629 and told us which changeset it's testing.
bos@130 630 \end{itemize}
bos@130 631
bos@130 632 We now run our test in the working directory. We use the
bos@130 633 \command{grep} command to see if our ``bad'' file is present in the
bos@130 634 working directory. If it is, this revision is bad; if not, this
bos@130 635 revision is good.
bos@131 636 \interaction{bisect.search.step1}
bos@130 637
bos@130 638 This test looks like a perfect candidate for automation, so let's turn
bos@130 639 it into a shell function.
bos@131 640 \interaction{bisect.search.mytest}
bos@130 641 We can now run an entire test step with a single command,
bos@130 642 \texttt{mytest}.
bos@131 643 \interaction{bisect.search.step2}
bos@130 644 A few more invocations of our canned test step command, and we're
bos@130 645 done.
bos@131 646 \interaction{bisect.search.rest}
bos@130 647
bos@282 648 Even though we had~40 changesets to search through, the \hgcmd{bisect}
bos@282 649 command let us find the changeset that introduced our ``bug'' with
bos@282 650 only five tests. Because the number of tests that the \hgcmd{bisect}
simon@313 651 command performs grows logarithmically with the number of changesets to
bos@130 652 search, the advantage that it has over the ``brute force'' search
bos@130 653 approach increases with every changeset you add.
bos@130 654
bos@130 655 \subsection{Cleaning up after your search}
bos@130 656
bos@282 657 When you're finished using the \hgcmd{bisect} command in a
bos@130 658 repository, you can use the \hgcmdargs{bisect}{reset} command to drop
bos@282 659 the information it was using to drive your search. The command
bos@130 660 doesn't use much space, so it doesn't matter if you forget to run this
bos@282 661 command. However, \hgcmd{bisect} won't let you start a new search in
bos@130 662 that repository until you do a \hgcmdargs{bisect}{reset}.
bos@131 663 \interaction{bisect.search.reset}
bos@130 664
bos@130 665 \section{Tips for finding bugs effectively}
bos@130 666
bos@130 667 \subsection{Give consistent input}
bos@130 668
bos@282 669 The \hgcmd{bisect} command requires that you correctly report the
bos@130 670 result of every test you perform. If you tell it that a test failed
bos@130 671 when it really succeeded, it \emph{might} be able to detect the
bos@130 672 inconsistency. If it can identify an inconsistency in your reports,
bos@130 673 it will tell you that a particular changeset is both good and bad.
bos@130 674 However, it can't do this perfectly; it's about as likely to report
bos@130 675 the wrong changeset as the source of the bug.
bos@130 676
bos@130 677 \subsection{Automate as much as possible}
bos@130 678
bos@282 679 When I started using the \hgcmd{bisect} command, I tried a few times
bos@130 680 to run my tests by hand, on the command line. This is an approach
bos@130 681 that I, at least, am not suited to. After a few tries, I found that I
bos@130 682 was making enough mistakes that I was having to restart my searches
bos@282 683 several times before finally getting correct results.
bos@282 684
bos@282 685 My initial problems with driving the \hgcmd{bisect} command by hand
bos@130 686 occurred even with simple searches on small repositories; if the
bos@130 687 problem you're looking for is more subtle, or the number of tests that
bos@282 688 \hgcmd{bisect} must perform increases, the likelihood of operator
bos@130 689 error ruining the search is much higher. Once I started automating my
bos@130 690 tests, I had much better results.
bos@130 691
bos@130 692 The key to automated testing is twofold:
bos@130 693 \begin{itemize}
bos@130 694 \item always test for the same symptom, and
bos@130 695 \item always feed consistent input to the \hgcmd{bisect} command.
bos@130 696 \end{itemize}
bos@130 697 In my tutorial example above, the \command{grep} command tests for the
bos@130 698 symptom, and the \texttt{if} statement takes the result of this check
bos@130 699 and ensures that we always feed the same input to the \hgcmd{bisect}
bos@130 700 command. The \texttt{mytest} function marries these together in a
bos@130 701 reproducible way, so that every test is uniform and consistent.
bos@130 702
bos@130 703 \subsection{Check your results}
bos@130 704
bos@282 705 Because the output of a \hgcmd{bisect} search is only as good as the
bos@130 706 input you give it, don't take the changeset it reports as the
bos@130 707 absolute truth. A simple way to cross-check its report is to manually
bos@130 708 run your test at each of the following changesets:
bos@130 709 \begin{itemize}
bos@130 710 \item The changeset that it reports as the first bad revision. Your
bos@130 711 test should still report this as bad.
bos@130 712 \item The parent of that changeset (either parent, if it's a merge).
bos@130 713 Your test should report this changeset as good.
bos@130 714 \item A child of that changeset. Your test should report this
bos@130 715 changeset as bad.
bos@130 716 \end{itemize}
bos@130 717
bos@130 718 \subsection{Beware interference between bugs}
bos@130 719
bos@130 720 It's possible that your search for one bug could be disrupted by the
bos@130 721 presence of another. For example, let's say your software crashes at
bos@130 722 revision 100, and worked correctly at revision 50. Unknown to you,
bos@130 723 someone else introduced a different crashing bug at revision 60, and
bos@130 724 fixed it at revision 80. This could distort your results in one of
bos@130 725 several ways.
bos@130 726
bos@130 727 It is possible that this other bug completely ``masks'' yours, which
bos@130 728 is to say that it occurs before your bug has a chance to manifest
bos@130 729 itself. If you can't avoid that other bug (for example, it prevents
bos@130 730 your project from building), and so can't tell whether your bug is
bos@282 731 present in a particular changeset, the \hgcmd{bisect} command cannot
bos@282 732 help you directly. Instead, you can mark a changeset as untested by
bos@282 733 running \hgcmdargs{bisect}{--skip}.
bos@130 734
bos@130 735 A different problem could arise if your test for a bug's presence is
wbunaarfubss@248 736 not specific enough. If you check for ``my program crashes'', then
bos@130 737 both your crashing bug and an unrelated crashing bug that masks it
bos@282 738 will look like the same thing, and mislead \hgcmd{bisect}.
bos@282 739
bos@282 740 Another useful situation in which to use \hgcmdargs{bisect}{--skip} is
bos@282 741 if you can't test a revision because your project was in a broken and
bos@282 742 hence untestable state at that revision, perhaps because someone
bos@282 743 checked in a change that prevented the project from building.
bos@130 744
bos@130 745 \subsection{Bracket your search lazily}
bos@130 746
bos@130 747 Choosing the first ``good'' and ``bad'' changesets that will mark the
bos@130 748 end points of your search is often easy, but it bears a little
bos@282 749 discussion nevertheless. From the perspective of \hgcmd{bisect}, the
bos@130 750 ``newest'' changeset is conventionally ``bad'', and the older
bos@130 751 changeset is ``good''.
bos@130 752
bos@130 753 If you're having trouble remembering when a suitable ``good'' change
bos@282 754 was, so that you can tell \hgcmd{bisect}, you could do worse than
bos@130 755 testing changesets at random. Just remember to eliminate contenders
bos@130 756 that can't possibly exhibit the bug (perhaps because the feature with
bos@130 757 the bug isn't present yet) and those where another problem masks the
bos@130 758 bug (as I discussed above).
bos@130 759
bos@130 760 Even if you end up ``early'' by thousands of changesets or months of
bos@130 761 history, you will only add a handful of tests to the total number that
bos@282 762 \hgcmd{bisect} must perform, thanks to its logarithmic behaviour.
bos@130 763
bos@121 764 %%% Local Variables:
bos@121 765 %%% mode: latex
bos@121 766 %%% TeX-master: "00book"
bos@121 767 %%% End: