annotate en/ch09-undo.xml @ 681:5bfa0df6aaed

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