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