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