| 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@121
|
11 \section{Easily recovered errors}
|
|
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@121
|
49 \filename{a} is modified. The changeset has been completely erased.
|
|
bos@121
|
50 I can now safely \hgcmd{add} the file \filename{b}, and rerun my
|
|
bos@121
|
51 commit.
|
|
bos@121
|
52 \interaction{rollback.add}
|
|
bos@121
|
53
|
|
bos@121
|
54 \subsection{The erroneous pull}
|
|
bos@121
|
55
|
|
bos@121
|
56 It's common practice with Mercurial to maintain separate development
|
|
bos@121
|
57 branches of a project in different repositories. Your development
|
|
bos@121
|
58 team might have one shared repository for your project's ``0.9''
|
|
bos@121
|
59 release, and another, containing different changes, for the ``1.0''
|
|
bos@121
|
60 release.
|
|
bos@121
|
61
|
|
bos@121
|
62 Given this, you can imagine that the consequences could be messy if
|
|
bos@121
|
63 you had a local ``0.9'' repository, and accidentally pulled changes
|
|
bos@121
|
64 from the shared ``1.0'' repository into it. At worst, you could be
|
|
bos@121
|
65 paying insufficient attention, and push those changes into the shared
|
|
bos@121
|
66 ``0.9'' tree, confusing your entire team (but don't worry, we'll
|
|
bos@121
|
67 return to this horror scenario later). However, it's more likely that
|
|
bos@121
|
68 you'll notice immediately, because Mercurial will display the URL it's
|
|
bos@121
|
69 pulling from, or you will see it pull a suspiciously large number of
|
|
bos@121
|
70 changes into the repository.
|
|
bos@121
|
71
|
|
bos@121
|
72 The \hgcmd{rollback} command will work nicely to expunge all of the
|
|
bos@121
|
73 changesets that you just pulled. Mercurial groups all changes from
|
|
bos@121
|
74 one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
|
|
bos@121
|
75 all you need to undo this mistake.
|
|
bos@121
|
76
|
|
bos@121
|
77 \subsection{Rolling back is useless once you've pushed}
|
|
bos@121
|
78
|
|
bos@121
|
79 The value of the \hgcmd{rollback} command drops to zero once you've
|
|
bos@121
|
80 pushed your changes to another repository. Rolling back a change
|
|
bos@121
|
81 makes it disappear entirely, but \emph{only} in the repository in
|
|
bos@121
|
82 which you perform the \hgcmd{rollback}. Because a rollback eliminates
|
|
bos@121
|
83 history, there's no way for the disappearance of a change to propagate
|
|
bos@121
|
84 between repositories.
|
|
bos@121
|
85
|
|
bos@121
|
86 If you've pushed a change to another repository---particularly if it's
|
|
bos@121
|
87 a shared repository---it has essentially ``escaped into the wild,''
|
|
bos@121
|
88 and you'll have to recover from your mistake in a different way. What
|
|
bos@121
|
89 will happen if you push a changeset somewhere, then roll it back, then
|
|
bos@121
|
90 pull from the repository you pushed to, is that the changeset will
|
|
bos@121
|
91 reappear in your repository.
|
|
bos@121
|
92
|
|
bos@121
|
93 (If you absolutely know for sure that the change you want to roll back
|
|
bos@121
|
94 is the most recent change in the repository that you pushed to,
|
|
bos@121
|
95 \emph{and} you know that nobody else could have pulled it from that
|
|
bos@121
|
96 repository, you can roll back the changeset there, too, but you really
|
|
bos@121
|
97 should really not rely on this working reliably. If you do this,
|
|
bos@121
|
98 sooner or later a change really will make it into a repository that
|
|
bos@121
|
99 you don't directly control (or have forgotten about), and come back to
|
|
bos@121
|
100 bite you.)
|
|
bos@121
|
101
|
|
bos@121
|
102 \subsection{You can only roll back once}
|
|
bos@121
|
103
|
|
bos@121
|
104 Mercurial stores exactly one transaction in its transaction log; that
|
|
bos@121
|
105 transaction is the most recent one that occurred in the repository.
|
|
bos@121
|
106 This means that you can only roll back one transaction. If you expect
|
|
bos@121
|
107 to be able to roll back one transaction, then its predecessor, this is
|
|
bos@121
|
108 not the behaviour you will get.
|
|
bos@121
|
109 \interaction{rollback.twice}
|
|
bos@121
|
110 Once you've rolled back one transaction in a repository, you can't
|
|
bos@121
|
111 roll back again in that repository until you perform another commit or
|
|
bos@121
|
112 pull.
|
|
bos@121
|
113
|
|
bos@121
|
114 %%% Local Variables:
|
|
bos@121
|
115 %%% mode: latex
|
|
bos@121
|
116 %%% TeX-master: "00book"
|
|
bos@121
|
117 %%% End:
|
