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