rev |
line source |
bos@121
|
1 \chapter{Finding and fixing your mistakes}
|
bos@121
|
2 \label{chap:undo}
|
bos@121
|
3
|
bos@121
|
4 To err might be human, but to really handle the consequences well
|
bos@121
|
5 takes a top-notch revision control system. In this chapter, we'll
|
bos@121
|
6 discuss some of the techniques you can use when you find that a
|
bos@121
|
7 problem has crept into your project. Mercurial has some highly
|
bos@121
|
8 capable features that will help you to isolate the sources of
|
bos@121
|
9 problems, and to handle them appropriately.
|
bos@121
|
10
|
bos@122
|
11 \section{Erasing local history}
|
bos@121
|
12
|
bos@121
|
13 \subsection{The accidental commit}
|
bos@121
|
14
|
bos@121
|
15 I have the occasional but persistent problem of typing rather more
|
bos@121
|
16 quickly than I can think, which sometimes results in me committing a
|
bos@121
|
17 changeset that is either incomplete or plain wrong. In my case, the
|
bos@121
|
18 usual kind of incomplete changeset is one in which I've created a new
|
bos@121
|
19 source file, but forgotten to \hgcmd{add} it. A ``plain wrong''
|
bos@121
|
20 changeset is not as common, but no less annoying.
|
bos@121
|
21
|
bos@121
|
22 \subsection{Rolling back a transaction}
|
bos@121
|
23
|
bos@121
|
24 In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
|
bos@121
|
25 each modification of a repository as a \emph{transaction}. Every time
|
bos@121
|
26 you commit a changeset or pull changes from another repository,
|
bos@121
|
27 Mercurial remembers what you did. You can undo, or \emph{roll back},
|
bos@121
|
28 exactly one of these actions using the \hgcmd{rollback} command.
|
bos@121
|
29
|
bos@121
|
30 Here's a mistake that I often find myself making: committing a change
|
bos@121
|
31 in which I've created a new file, but forgotten to \hgcmd{add} it.
|
bos@121
|
32 \interaction{rollback.commit}
|
bos@121
|
33 Looking at the output of \hgcmd{status} after the commit immediately
|
bos@121
|
34 confirms the error.
|
bos@121
|
35 \interaction{rollback.status}
|
bos@121
|
36 The commit captured the changes to the file \filename{a}, but not the
|
bos@121
|
37 new file \filename{b}. If I were to push this changeset to a
|
bos@121
|
38 repository that I shared with a colleague, the chances are high that
|
bos@121
|
39 something in \filename{a} would refer to \filename{b}, which would not
|
bos@121
|
40 be present in their repository when they pulled my changes. I would
|
bos@121
|
41 thus become the object of some indignation.
|
bos@121
|
42
|
bos@121
|
43 However, luck is with me---I've caught my error before I pushed the
|
bos@121
|
44 changeset. I use the \hgcmd{rollback} command, and Mercurial makes
|
bos@121
|
45 that last changeset vanish.
|
bos@121
|
46 \interaction{rollback.rollback}
|
bos@121
|
47 Notice that the changeset is no longer present in the repository's
|
bos@121
|
48 history, and the working directory once again thinks that the file
|
bos@122
|
49 \filename{a} is modified. The commit and rollback have left the
|
bos@122
|
50 working directory exactly as it was prior to the commit; the changeset
|
bos@122
|
51 has been completely erased. I can now safely \hgcmd{add} the file
|
bos@122
|
52 \filename{b}, and rerun my commit.
|
bos@121
|
53 \interaction{rollback.add}
|
bos@121
|
54
|
bos@121
|
55 \subsection{The erroneous pull}
|
bos@121
|
56
|
bos@121
|
57 It's common practice with Mercurial to maintain separate development
|
bos@121
|
58 branches of a project in different repositories. Your development
|
bos@121
|
59 team might have one shared repository for your project's ``0.9''
|
bos@121
|
60 release, and another, containing different changes, for the ``1.0''
|
bos@121
|
61 release.
|
bos@121
|
62
|
bos@121
|
63 Given this, you can imagine that the consequences could be messy if
|
bos@121
|
64 you had a local ``0.9'' repository, and accidentally pulled changes
|
bos@121
|
65 from the shared ``1.0'' repository into it. At worst, you could be
|
bos@121
|
66 paying insufficient attention, and push those changes into the shared
|
bos@121
|
67 ``0.9'' tree, confusing your entire team (but don't worry, we'll
|
bos@121
|
68 return to this horror scenario later). However, it's more likely that
|
bos@121
|
69 you'll notice immediately, because Mercurial will display the URL it's
|
bos@121
|
70 pulling from, or you will see it pull a suspiciously large number of
|
bos@121
|
71 changes into the repository.
|
bos@121
|
72
|
bos@121
|
73 The \hgcmd{rollback} command will work nicely to expunge all of the
|
bos@121
|
74 changesets that you just pulled. Mercurial groups all changes from
|
bos@121
|
75 one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
|
bos@121
|
76 all you need to undo this mistake.
|
bos@121
|
77
|
bos@121
|
78 \subsection{Rolling back is useless once you've pushed}
|
bos@121
|
79
|
bos@121
|
80 The value of the \hgcmd{rollback} command drops to zero once you've
|
bos@121
|
81 pushed your changes to another repository. Rolling back a change
|
bos@121
|
82 makes it disappear entirely, but \emph{only} in the repository in
|
bos@121
|
83 which you perform the \hgcmd{rollback}. Because a rollback eliminates
|
bos@121
|
84 history, there's no way for the disappearance of a change to propagate
|
bos@121
|
85 between repositories.
|
bos@121
|
86
|
bos@121
|
87 If you've pushed a change to another repository---particularly if it's
|
bos@121
|
88 a shared repository---it has essentially ``escaped into the wild,''
|
bos@121
|
89 and you'll have to recover from your mistake in a different way. What
|
bos@121
|
90 will happen if you push a changeset somewhere, then roll it back, then
|
bos@121
|
91 pull from the repository you pushed to, is that the changeset will
|
bos@121
|
92 reappear in your repository.
|
bos@121
|
93
|
bos@121
|
94 (If you absolutely know for sure that the change you want to roll back
|
bos@121
|
95 is the most recent change in the repository that you pushed to,
|
bos@121
|
96 \emph{and} you know that nobody else could have pulled it from that
|
bos@121
|
97 repository, you can roll back the changeset there, too, but you really
|
bos@121
|
98 should really not rely on this working reliably. If you do this,
|
bos@121
|
99 sooner or later a change really will make it into a repository that
|
bos@121
|
100 you don't directly control (or have forgotten about), and come back to
|
bos@121
|
101 bite you.)
|
bos@121
|
102
|
bos@121
|
103 \subsection{You can only roll back once}
|
bos@121
|
104
|
bos@121
|
105 Mercurial stores exactly one transaction in its transaction log; that
|
bos@121
|
106 transaction is the most recent one that occurred in the repository.
|
bos@121
|
107 This means that you can only roll back one transaction. If you expect
|
bos@121
|
108 to be able to roll back one transaction, then its predecessor, this is
|
bos@121
|
109 not the behaviour you will get.
|
bos@121
|
110 \interaction{rollback.twice}
|
bos@121
|
111 Once you've rolled back one transaction in a repository, you can't
|
bos@121
|
112 roll back again in that repository until you perform another commit or
|
bos@121
|
113 pull.
|
bos@121
|
114
|
bos@122
|
115 \section{Reverting the mistaken change}
|
bos@122
|
116
|
bos@122
|
117 If you make a modification to a file, and decide that you really
|
bos@122
|
118 didn't want to change the file at all, the \hgcmd{revert} command is
|
bos@122
|
119 the one you'll need. It looks at the changeset that's the parent of
|
bos@122
|
120 the working directory, and restores the contents of the file to their
|
bos@122
|
121 state as of that changeset. (That's a long-winded way of saying that,
|
bos@122
|
122 in the normal case, it undoes your modifications.)
|
bos@122
|
123
|
bos@122
|
124 Let's illustrate how the \hgcmd{revert} command works with yet another
|
bos@122
|
125 small example. We'll begin by modifying a file that Mercurial is
|
bos@122
|
126 already tracking.
|
bos@122
|
127 \interaction{daily.revert.modify}
|
bos@122
|
128 If we don't want that change, we can simply \hgcmd{revert} the file.
|
bos@122
|
129 \interaction{daily.revert.unmodify}
|
bos@122
|
130 The \hgcmd{revert} command provides us with an extra degree of safety
|
bos@122
|
131 by saving our modified file with a \filename{.orig} extension.
|
bos@122
|
132 \interaction{daily.revert.status}
|
bos@122
|
133
|
bos@122
|
134 \subsection{File management errors}
|
bos@122
|
135 \label{sec:undo:mgmt}
|
bos@122
|
136
|
bos@122
|
137 The \hgcmd{revert} command is useful for more than just modified
|
bos@122
|
138 files. It lets you reverse the results of all of Mercurial's file
|
bos@122
|
139 management commands---\hgcmd{add}, \hgcmd{remove}, and so on.
|
bos@122
|
140
|
bos@122
|
141 If you \hgcmd{add} a file, then decide that in fact you don't want
|
bos@122
|
142 Mercurial to track it, use \hgcmd{revert} to undo the add. Don't
|
bos@122
|
143 worry; Mercurial will not modify the file in any way. It will just
|
bos@122
|
144 ``unmark'' the file.
|
bos@122
|
145 \interaction{daily.revert.add}
|
bos@122
|
146
|
bos@122
|
147 Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
|
bos@122
|
148 \hgcmd{revert} to restore it to the contents it had as of the parent
|
bos@122
|
149 of the working directory.
|
bos@122
|
150 \interaction{daily.revert.remove}
|
bos@122
|
151 This works just as well for a file that you deleted by hand, without
|
bos@122
|
152 telling Mercurial (recall that in Mercurial terminology, this kind of
|
bos@122
|
153 file is called ``missing'').
|
bos@122
|
154 \interaction{daily.revert.missing}
|
bos@122
|
155
|
bos@122
|
156 If you revert a \hgcmd{copy}, the copied-to file remains in your
|
bos@123
|
157 working directory afterwards, untracked. Since a copy doesn't affect
|
bos@123
|
158 the copied-from file in any way, Mercurial doesn't do anything with
|
bos@123
|
159 the copied-from file.
|
bos@122
|
160 \interaction{daily.revert.copy}
|
bos@122
|
161
|
bos@122
|
162 \subsubsection{A slightly special case: reverting a rename}
|
bos@122
|
163
|
bos@122
|
164 If you \hgcmd{rename} a file, there is one small detail that
|
bos@122
|
165 you should remember. When you \hgcmd{revert} a rename, it's not
|
bos@122
|
166 enough to provide the name of the renamed-to file, as you can see
|
bos@122
|
167 here.
|
bos@122
|
168 \interaction{daily.revert.rename}
|
bos@122
|
169 As you can see from the output of \hgcmd{status}, the renamed-to file
|
bos@122
|
170 is no longer identified as added, but the renamed-\emph{from} file is
|
bos@122
|
171 still removed! This is counter-intuitive (at least to me), but at
|
bos@122
|
172 least it's easy to deal with.
|
bos@122
|
173 \interaction{daily.revert.rename-orig}
|
bos@122
|
174 So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
|
bos@122
|
175 the source and destination names.
|
bos@122
|
176
|
bos@122
|
177 (By the way, if you rename a file, then modify the renamed-to file,
|
bos@122
|
178 then revert both components of the rename, when Mercurial restores the
|
bos@122
|
179 file that was removed as part of the rename, it will be unmodified.
|
bos@122
|
180 If you need the modifications in the renamed-to file to show up in the
|
bos@122
|
181 renamed-from file, don't forget to copy them over.)
|
bos@122
|
182
|
bos@123
|
183 These fiddly aspects of reverting a rename arguably constitute a small
|
bos@122
|
184 bug in Mercurial.
|
bos@122
|
185
|
bos@121
|
186 %%% Local Variables:
|
bos@121
|
187 %%% mode: latex
|
bos@121
|
188 %%% TeX-master: "00book"
|
bos@121
|
189 %%% End:
|