Mercurial > hgbook
annotate ja/mq.tex @ 331:110ebf968d3f
more mq.tex
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Sun, 30 Mar 2008 14:51:01 +0900 |
parents | cadfd8bf5f15 |
children | 9ad5d69c4a37 |
rev | line source |
---|---|
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1 %\chapter{Managing change with Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
2 \chapter{Mercurial Queues$B$GJQ99$r4IM}$9$k(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{chap:mq} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
5 %\section{The patch management problem} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
6 \section{$B%Q%C%A4IM}$NLdBj(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
7 \label{sec:mq:patch-mgmt} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
8 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
9 %Here is a common scenario: you need to install a software package from |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
10 %source, but you find a bug that you must fix in the source before you |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
11 %can start using the package. You make your changes, forget about the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
12 %package for a while, and a few months later you need to upgrade to a |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
13 %newer version of the package. If the newer version of the package |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
14 %still has the bug, you must extract your fix from the older source |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
15 %tree and apply it against the newer version. This is a tedious task, |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
16 %and it's easy to make mistakes. |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
17 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
18 $B$h$/$"$k%7%J%j%*!'%=!<%9$+$i%=%U%H%&%'%"%Q%C%1!<%8$r%$%s%9%H!<%k$9$kI,MW(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
19 $B$,$"$k!%$7$+$7%Q%C%1!<%8$r;H$&A0$K%=!<%9$+$iD>$9$Y$-%P%0$r8+$D$1$?!%JQ99(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
20 $B$r2C$($F!$;C$/%Q%C%1!<%8$N$3$H$OK:$l$F$$$k!%?t%v7n8e!$?7$7$$%P!<%8%g%s$r(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
21 $B%$%s%9%H!<%k$9$k$3$H$K$J$C$?!%$b$7?7$7$$%P!<%8%g%s$,!$0MA3$H$7$F$=$N%P%0(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
22 $B$r;}$C$F$$$?>l9g!$=$@5$r8E$$%=!<%9$+$iCj=P$7$F!$?7$7$$%P!<%8%g%s$KE,MQ$7(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
23 $B$J$1$l$P$J$i$J$$!%$3$l$OB`6~$G$7$+$b4V0c$$$d$9$$;E;v$@!%(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
24 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
25 %This is a simple case of the ``patch management'' problem. You have |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
26 %an ``upstream'' source tree that you can't change; you need to make |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
27 %some local changes on top of the upstream tree; and you'd like to be |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
28 %able to keep those changes separate, so that you can apply them to |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
29 %newer versions of the upstream source. |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
30 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
31 $B$3$l$,%Q%C%A4IM}LdBj$N%7%s%W%k$JNc$G$"$k!%$b$7$"$J$?$,JQ99$G$-$J$$>eN.$N(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
32 $B%=!<%9%D%j!<$,$"$l$P!$%"%C%W%9%H%j!<%`$N%D%j!<$N>e$G%m!<%+%k$JJQ99$r$7$J(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
33 $B$1$l$P$J$i$J$$!%$"$J$?$O%"%C%W%9%H%j!<%`%=!<%9$KE,MQ$G$-$k$h$&$K$-$C$H$3(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
34 $B$NJQ99$rJ,N%$7$F$*$-$?$$$H;W$&$O$:$@!%(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
35 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
36 %The patch management problem arises in many situations. Probably the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
37 %most visible is that a user of an open source software project will |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
38 %contribute a bug fix or new feature to the project's maintainers in the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
39 %form of a patch. |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
40 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
41 $B%Q%C%A4IM}LdBj$O$$$m$$$m$J>u67$G5/$3$k!%$*$=$i$/:G$bL@$i$+$J$N$O!$%*!<%W(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
42 $B%s%=!<%9%=%U%H%&%'%"%W%m%8%'%/%H$N%f!<%6$,!$%W%m%8%'%/%H$N%a%s%F%J$K%P%0(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
43 $B%U%#%C%/%9$d?75!G=$r%Q%C%A$N7A$G9W8%$9$k$3$H$G$"$m$&!%(B |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
45 %Distributors of operating systems that include open source software |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
46 %often need to make changes to the packages they distribute so that |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
47 %they will build properly in their environments. |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
48 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
49 $B%*!<%W%s%=%U%H%&%'%"$r4^$`%*%Z%l!<%F%#%s%0%7%9%F%`$NG[I[<T$O!$G[I[$9$k%Q%C(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
50 $B%1!<%8$,H`$i$N4D6-$G@5$7$/%S%k%I$G$-$k$h$&$K%Q%C%1!<%8$XJQ99$r2C$($k$3$H(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
51 $B$,B?$$!%(B |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
52 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
53 When you have few changes to maintain, it is easy to manage a single |
235
80f387d13bfe
Fix a few command references.
Bryan O'Sullivan <bos@serpentine.com>
parents:
234
diff
changeset
|
54 patch using the standard \command{diff} and \command{patch} programs |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
55 (see section~\ref{sec:mq:patch} for a discussion of these tools). |
285
814698eebbaf
fixed a typo and formatted the notify hook configuration example nicer.
Timo Paulssen <timonator@perpetuum-immobile.de>
parents:
283
diff
changeset
|
56 Once the number of changes grows, it starts to make sense to maintain |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
57 patches as discrete ``chunks of work,'' so that for example a single |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
58 patch will contain only one bug fix (the patch might modify several |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
59 files, but it's doing ``only one thing''), |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
60 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
61 and you may have a number |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
62 of such patches for different bugs you need fixed and local changes |
328 | 63 you require. |
64 | |
65 | |
66 | |
67 In this situation, if you submit a bug fix patch to the | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
68 upstream maintainers of a package and they include your fix in a |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
69 subsequent release, you can simply drop that single patch when you're |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
70 updating to the newer release. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
71 |
328 | 72 $B$b$7%a%s%F%J%s%9$7$F$$$kJQ99$,$4$/$o$:$+$J$i!$I8=`$N(B\command{diff}$B%3%^%s(B |
73 $B%I$H(B\command{patch}$B%3%^%s%I$r;H$C$FC10l$N%Q%C%A$r4IM}$9$k$N$,4JC1$@!%!J$3(B | |
74 $B$l$i$N%D!<%k$K$D$$$F$O(B~\ref{sec:mq:patch}$B$N@a$r;2>H!%!K(B | |
75 | |
76 $BJQ99$N?t$,A}$($F$/$k$H!$C10l$N%P%0%U%#%C%/%9$@$1$r4^$`8DJL$N%Q%C%A$r=89g(B | |
77 $B$H$7$F4IM}$9$k$3$H$,8=<BL#$rBS$S$F$/$k!%!J3F!9$N%Q%C%A$OJ#?t$N%U%!%$%k$r(B | |
78 $BJQ99$9$k$+$b$7$l$J$$$,!$L\E*$O(B1$B$D$-$j$G$"$k!%!K(B | |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
79 |
328 | 80 $B=$@5$7$?$$0[$J$k%P%0$HI,MW$J%m!<%+%k$JJQ99$N$?$a$N!$?tB?$/$N$=$N$h$&$J%Q%C(B |
81 $B%A$r;}$D$3$H$K$J$k$+$b$7$l$J$$!%(B | |
82 | |
83 $B$3$N>u67$G$O%"%C%W%9%H%j!<%`$N%a%s%F%J$K%P%0=$@5%Q%C%A$rAw$j!$H`$i$,$"$J(B | |
84 $B$?$N=$@5$r(B | |
85 | |
86 | |
87 | |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
88 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
89 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
90 |
329 | 91 %Maintaining a single patch against an upstream tree is a little |
92 %tedious and error-prone, but not difficult. However, the complexity | |
93 %of the problem grows rapidly as the number of patches you have to | |
94 %maintain increases.With more than a tiny number of patches in hand, | |
95 %understanding which ones you have applied and maintaining them moves | |
96 %from messy to overwhelming. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
97 |
329 | 98 $BC10l$N%Q%C%A$r%"%C%W%9%H%j!<%`$N%D%j!<$KBP$7$F%a%s%F%J%s%9$9$k$3$H$O$d$d(B |
99 $BLLE]$G!$4V0c$$$N85$K$J$j$,$A$G$"$k$,!$Fq$7$/$O$J$$!%$7$+$7!$%a%s%F%J%s%9(B | |
100 $B$9$k%Q%C%A$N?t$,A}$($k$K=>$C$FLdBj$NJ#;($5$,5^B.$KA}$7$F$$$/!%%Q%C%A$N?t(B | |
101 $B$,$"$kDxEY0J>eB?$/$J$k$H!$$I$N%Q%C%A$rE,MQ$7$?$+!$$I$N%Q%C%A$r4IM}$7$F$$(B | |
102 $B$k$N$+$NM}2r$,!$Lq2p$H$$$&>uBV$+$i05E]$5$l$k$F$$$k>uBV$K$J$k!%(B | |
103 | |
104 %Fortunately, Mercurial includes a powerful extension, Mercurial Queues | |
105 %(or simply ``MQ''), that massively simplifies the patch management | |
106 %problem. | |
107 | |
108 $B9,$$$K$b!$(BMercurial$B$O(BMercurial Queues$B!J$"$k$$$OC1$K(BMQ$B!K$H$$$&6/NO$J%(%/%9(B | |
109 $B%F%s%7%g%s$r$b$C$F$*$j!$%Q%C%A4IM}$NLdBj$rBgI}$KC1=c2=$9$k!%(B | |
110 | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
111 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
112 %\section{The prehistory of Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
113 \section{Mercurial Queues$BA0;K(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
114 \label{sec:mq:history} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
115 |
323 | 116 %During the late 1990s, several Linux kernel developers started to |
117 %maintain ``patch series'' that modified the behaviour of the Linux | |
118 %kernel. Some of these series were focused on stability, some on | |
119 %feature coverage, and others were more speculative. | |
120 | |
121 1990$BG/Be$N=*$o$j:"!$(BLinux$B%+!<%M%k$N3+H/<TC#$O!$(BLinux$B%+!<%M%k$r2~A1$9$k0l(B | |
122 $BO"$N%Q%C%A$N4IM}$r;O$a$?!%$=$l$i$N$&$A!$$"$k$b$N$O0BDj@-$K!$JL$N$b$N$OFC(B | |
123 $BDj$N5!G=$K!$$^$?JL$N$b$N$OLn?4E*$JFbMF$KFC2=$7$F$$$?!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
124 |
323 | 125 %The sizes of these patch series grew rapidly. In 2002, Andrew Morton |
126 %published some shell scripts he had been using to automate the task of | |
127 %managing his patch queues. Andrew was successfully using these | |
128 %scripts to manage hundreds (sometimes thousands) of patches on top of | |
129 %the Linux kernel. | |
130 | |
131 $B$3$l$i$N%Q%C%A%7%j!<%:$N%5%$%:$O$O$9$0$KKD$l>e$,$C$?!%(B2002$BG/$K(BAndrew | |
132 Morton$B$OH`$N%Q%C%A%-%e!<$N4IM}$r<+F02=$9$k$$$/$D$+$N%7%'%k%9%/%j%W%H$r8x(B | |
133 $BI=$7$?!%(BAndrew$B$O?tI4$+$i?t@i$N(BLinux$B%+!<%M%k%Q%C%A$r$3$l$i$N%9%/%j%W%H$G(B | |
134 $B4IM}$9$k$3$H$,$G$-$F$$$?!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
135 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
136 %\subsection{A patchwork quilt} |
323 | 137 \subsection{patchwork quilt} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
138 \label{sec:mq:quilt} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
139 |
323 | 140 %In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the |
141 %approach of Andrew's scripts and published a tool called ``patchwork | |
142 %quilt''~\cite{web:quilt}, or simply ``quilt'' | |
143 %(see~\cite{gruenbacher:2005} for a paper describing it). Because | |
144 %quilt substantially automated patch management, it rapidly gained a | |
145 %large following among open source software developers. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
146 |
323 | 147 2003$BG/$N;O$a!$(BAndreas Gruenbacher$B$H(BMartin Quinson$B$O(BAndrew$B$N%9%/%j%W%H$N$d(B |
148 $B$jJ}$r??;w$F!$(B``patchwork quilt''~\cite{web:quilt}$B$"$k$$$OC1$K(B``quilt''$B$H(B | |
149 $B8F$P$l$k%D!<%k$r%j%j!<%9$7$?!%!J>\$7$/$OO@J8(B~\cite{gruenbacher:2005}$B$r;2(B | |
150 $B>H$N$3$H!%!K(Bquilt$B$O==J,$K<+F02=$5$l$?%Q%C%A4IM}$rDs6!$7$F$$$?$N$G!$%=%U%H(B | |
151 $B%&%'%"3+H/<T$NBg$-$J;Y;}$r5^B.$K3MF@$7$F$$$C$?!%(B | |
152 | |
153 %Quilt manages a \emph{stack of patches} on top of a directory tree. | |
154 %To begin, you tell quilt to manage a directory tree, and tell it which | |
155 %files you want to manage; it stores away the names and contents of | |
156 %those files. To fix a bug, you create a new patch (using a single | |
157 %command), edit the files you need to fix, then ``refresh'' the patch. | |
158 | |
159 quilt$B$O%G%#%l%/%H%j%D%j!<>e$G(B\emph{$B%Q%C%A$N%9%?%C%/(B}$B$r4IM}$9$k!%%Q%C%A$N(B | |
160 $B4IM}$r;O$a$k$K$O!$(Bquilt$B$K4IM}$9$Y$-%G%#%l%/%H%j%D%j!<$H!$4IM}BP>]$N%U%!%$(B | |
161 $B%k$r;XDj$9$k!%(Bquilt$B$O$3$l$i$N%U%!%$%k$NL>A0$HCf?H$rJ]B8$9$k!%%P%0$r=$@5(B | |
162 $B$9$k>l9g$O!$$^$:?7$7$$%Q%C%A$r!J%3%^%s%I(B1$B$D$G!K:n@.$7!$I,MW$J%U%!%$%k$K(B | |
163 $B=$@5$r2C$($?8e!$%Q%C%A$r(B``$B%j%U%l%C%7%e(B''$B$9$l$P$h$$!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
164 |
323 | 165 %The refresh step causes quilt to scan the directory tree; it updates |
166 %the patch with all of the changes you have made. You can create | |
167 %another patch on top of the first, which will track the changes | |
168 %required to modify the tree from ``tree with one patch applied'' to | |
169 %``tree with two patches applied''. | |
170 | |
171 $B%j%U%l%C%7%e$G$O!$(Bquilt$B$O%G%#%l%/%H%j%D%j!<$r%9%-%c%s$7!$JQ99A4$F$rH?1G$5(B | |
172 $B$;$F%Q%C%A$r99?7$9$k!%(B``$B$"$k%Q%C%A$,E,MQ$5$l$?>uBV$N%D%j!<(B''$B$+$i(B``2$B$D$N%Q%C(B | |
173 $B%A$,E,MQ$5$l$?%D%j!<(B''$B$X99?7$9$k$N$KI,MW$JJQ99$rDI@W$7!$JL$N%Q%C%A$r:n$k(B | |
174 $B$3$H$b$G$-$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
175 |
323 | 176 %You can \emph{change} which patches are applied to the tree. If you |
177 %``pop'' a patch, the changes made by that patch will vanish from the | |
178 %directory tree. Quilt remembers which patches you have popped, | |
179 %though, so you can ``push'' a popped patch again, and the directory | |
180 %tree will be restored to contain the modifications in the patch.Most | |
181 %importantly, you can run the ``refresh'' command at any time, and the | |
182 %topmost applied patch will be updated. This means that you can, at | |
183 %any time, change both which patches are applied and what | |
184 %modifications those patches make. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
185 |
323 | 186 $B%f!<%6$O$I$N%Q%C%A$,%D%j!<$KE,MQ$5$l$k$+$r(B\emph{$BJQ99(B}$B$G$-$k!%$"$k%Q%C%A$r(B |
187 $B%]%C%W$9$k$H!$$3$N%Q%C%A$K$h$kJQ99$O%D%j!<$+$i>CLG$9$k!%(Bquilt$B$O$I$N%Q%C%A(B | |
188 $B$r%]%C%W$7$?$+5-21$7$F$*$j!$0lEY%]%C%W$7$?%U%!%$%k$r:F$S%W%C%7%e$7!$%G%#(B | |
189 $B%l%/%H%j%D%j!<$r%Q%C%A$K$h$kJQ99$,$J$5$l$?>uBV$KLa$9$3$H$,$G$-$k!%:G$b=E(B | |
190 $BMW$J$3$H$O!$$$$D$G$b(B``refresh''$B%3%^%s%I$r<B9T$7$F0lHV?7$7$/E,MQ$5$l$?%Q%C(B | |
191 $B%A$r99?7$G$-$k$3$H$G$"$k!%$3$l$O$9$J$o$A!$%Q%C%A$NE,MQ$5$l$?>uBV$H!$%Q%C(B | |
192 $B%A$=$l<+BN$r$$$D$G$b99?7$G$-$k$H$$$&$3$H$G$"$k!%(B | |
193 | |
194 %Quilt knows nothing about revision control tools, so it works equally | |
195 %well on top of an unpacked tarball or a Subversion working copy. | |
196 | |
197 quilt$B$O%j%S%8%g%s4IM}%D!<%k$K$D$$$F$OA4$/4XCN$7$J$$$?$a!$E83+$5$l$?(Btar$B%\!<(B | |
198 $B%k>e$G$b!$(BSubversion$B$N%o!<%-%s%0%3%T!<>e$G$bF1MM$KF0:n$9$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
199 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
200 %\subsection{From patchwork quilt to Mercurial Queues} |
323 | 201 \subsection{patchwork quilt$B$+$i(BMercurial Queues$B$X(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
202 \label{sec:mq:quilt-mq} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
203 |
324 | 204 %In mid-2005, Chris Mason took the features of quilt and wrote an |
205 %extension that he called Mercurial Queues, which added quilt-like | |
206 %behaviour to Mercurial. | |
207 | |
208 2005$BG/$NCf:"(BChris Mason$B$O!$(Bquilt$B$N5!G=$r<h$jF~$l$F!$(BMercurial$B$K(Bquilt$B$N$h(B | |
209 $B$&$JF0:n$rDI2C$9$k(BMercurial Queues$B$H$$$&%(%/%9%F%s%7%g%s$r=q$$$?!%(B | |
210 | |
211 %The key difference between quilt and MQ is that quilt knows nothing | |
212 %about revision control systems, while MQ is \emph{integrated} into | |
213 %Mercurial. Each patch that you push is represented as a Mercurial | |
214 %changeset. Pop a patch, and the changeset goes away. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
215 |
324 | 216 quilt$B$H(BMQ$B$N0c$$$O!$(Bquilt$B$O%j%S%8%g%s4IM}%7%9%F%`$K$D$$$F2?$b4XCN$7$J$$$N(B |
217 $B$KBP$7$F!$(BMQ$B$O(BMercurial$B$KE}9g$5$l$F$$$k$3$H$G$"$k!%%W%C%7%e$7$?8D!9$N%Q%C(B | |
218 $B%A$O(BMercurial$B$N%A%'%s%8%;%C%H$H$7$FI=8=$5$l$k!%%Q%C%A$r%]%C%W$9$k$H!$%A%'(B | |
219 $B%s%8%;%C%H$O>C$($F$J$/$J$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
220 |
324 | 221 %Because quilt does not care about revision control tools, it is still |
222 %a tremendously useful piece of software to know about for situations | |
223 %where you cannot use Mercurial and MQ. | |
224 | |
225 quilt$B$O%j%S%8%g%s4IM}%D!<%k$HL54X78$KMxMQ2DG=$J$?$a!$(BMercurial$B$H(BMQ$B$,;H$((B | |
226 $B$J$$>u67$G$O0MA3$H$7$FHs>o$KM-1W$J%D!<%k$G$"$k$3$H$O5-21$KN1$a$F$*$/$Y$-(B | |
227 $B$G$"$k!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
228 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
229 %\section{The huge advantage of MQ} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
230 \section{MQ$B$NBg$-$JMxE@(B} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
231 |
324 | 232 %I cannot overstate the value that MQ offers through the unification of |
233 %patches and revision control. | |
234 | |
235 MQ$B$,%Q%C%A$H%j%S%8%g%s%3%s%H%m!<%k$NE}9g$K$h$C$F$b$?$i$92ACM$r8XD%$9$k$o(B | |
236 $B$1$K$O$$$+$J$$!%(B | |
237 | |
238 %A major reason that patches have persisted in the free software and | |
239 %open source world---in spite of the availability of increasingly | |
240 %capable revision control tools over the years---is the \emph{agility} | |
241 %they offer. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
242 |
324 | 243 $B;~$rDI$&Kh$K%j%S%8%g%s%3%s%H%m!<%k%D!<%k$NMxMQ$,9-$,$C$F$$$k$K$b$+$+$o$i(B |
244 $B$:!$%U%j!<%=%U%H$H%*!<%W%s%=!<%9$N@$3&$K%Q%C%A$,B8:_$9$kBg$-$JM}M3$O$=$N(B | |
245 \emph{$B5!IR$5(B}$B$K$"$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
246 |
324 | 247 %Traditional revision control tools make a permanent, irreversible |
248 %record of everything that you do. While this has great value, it's | |
249 %also somewhat stifling. If you want to perform a wild-eyed | |
250 %experiment, you have to be careful in how you go about it, or you risk | |
251 %leaving unneeded---or worse, misleading or destabilising---traces of | |
252 %your missteps and errors in the permanent revision record. | |
253 | |
254 $BEAE}E*$J%j%S%8%g%s%3%s%H%m!<%k%D!<%k$O!$9T$J$C$?A`:n$N1J5WE*$GIT2D5UE*$J(B | |
255 $B5-O?$r;D$9!%$3$l$K$OBg$-$J2ACM$,$"$k0lJ}$G!$5g6~$K46$8$k$3$H$b$"$k!%$b$7(B | |
256 $B2a7c$J<B83$r$9$k$N$G$"$l$P!$$I$N$h$&$K?J$a$k$+?5=E$K$9$kI,MW$,$"$k!%$5$b(B | |
257 $B$J$1$l$P!$ITMW$J!$$"$k$$$O8m2r$r>7$$$?$j!$0BDj@-$rB;$J$&%H%l!<%9$H%(%i!<(B | |
258 $B$r1J5WE*$J%j%S%8%g%sMzNr$K;D$9$3$H$K$J$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
259 |
324 | 260 %By contrast, MQ's marriage of distributed revision control with |
261 %patches makes it much easier to isolate your work. Your patches live | |
262 %on top of normal revision history, and you can make them disappear or | |
263 %reappear at will. If you don't like a patch, you can drop it. If a | |
264 %patch isn't quite as you want it to be, simply fix it---as many times | |
265 %as you need to, until you have refined it into the form you desire. | |
266 | |
267 $BBP>NE*$K!$(BMQ$B$K$h$kJ,;6%j%S%8%g%s%3%s%H%m!<%k$H%Q%C%A$N7k9g$O!$:n6H$r3VN%(B | |
268 $B$9$k$3$H$rMZ$+$KMF0W$K$9$k!%%Q%C%A$ODL>o$N%j%S%8%g%sMzNr$N>e$K>h$C$F$*$j!$(B | |
269 $BK>$`$h$&$K>CLG$5$;$?$j:F8=$5$;$k$3$H$,$G$-$k!%%Q%C%A$r5$$KF~$i$J$1$l$P!$(B | |
270 $B$3$l$r4~5Q$9$k$3$H$b$G$-$k!%%Q%C%A$,$"$J$?$NK>$`$h$&$J$b$N$G$J$1$l$P!$4u(B | |
271 $BK>DL$j$K$J$k$^$G2?EY$G$b4JC1$K=$@5$9$k$3$H$,$G$-$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
272 |
324 | 273 %As an example, the integration of patches with revision control makes |
274 %understanding patches and debugging their effects---and their | |
275 %interplay with the code they're based on---\emph{enormously} easier. | |
276 %Since every applied patch has an associated changeset, you can use | |
277 %\hgcmdargs{log}{\emph{filename}} to see which changesets and patches | |
278 %affected a file. You can use the \hgext{bisect} command to | |
279 %binary-search through all changesets and applied patches to see where | |
280 %a bug got introduced or fixed. You can use the \hgcmd{annotate} | |
281 %command to see which changeset or patch modified a particular line of | |
282 %a source file. And so on. | |
283 | |
284 $BNc$($P!$%j%S%8%g%s%3%s%H%m!<%k$X$N%Q%C%A$NE}9g$O!$%Q%C%A$rM}2r$7!$$=$N1F(B | |
285 $B6A!$0M$C$FN)$D%Y!<%9%3!<%I$H$NAj8_:nMQ$r%G%P%C%0$9$k$3$H$r2DG=$K$9$k!%E,(B | |
286 $BMQ$5$l$?%Q%C%A$O!$4XO"$E$1$i$l$?%A%'%s%8%;%C%H$r;}$D$?$a!$(B | |
287 \hgcmdargs{log}{\emph{filename}}$B$K$h$C$F$I$N%A%'%s%8%;%C%H$H%Q%C%A$,%U%!(B | |
288 $B%$%k$K1F6A$rM?$($F$$$k$+D4$Y$k$3$H$,$G$-$k!%(B\hgext{bisect}$B%3%^%s%I$GA4$F(B | |
289 $B$N%A%'%s%8%;%C%H$HE,MQ$5$l$?%Q%C%A$KBP$7$F%P%$%J%j%5!<%A$r9T$J$$!$$I$3$G(B | |
290 $B%P%0$,:.F~$7$?$+!$$"$k$$$O=$@5$5$l$?$+$rD4$Y$k$3$H$,$G$-$k!%(B | |
291 \hgcmd{annotate}$B%3%^%s%I$G$I$N%A%'%s%8%;%C%H$+%Q%C%A$,%=!<%9%U%!%$%k$NFC(B | |
292 $BDj$N9T$rJQ99$7$?$+8+$k$3$H$,$G$-$k!%(B | |
293 | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
294 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
295 %\section{Understanding patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
296 \section{$B%Q%C%A$H$O2?$+(B} |
26 | 297 \label{sec:mq:patch} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
298 |
325 | 299 %Because MQ doesn't hide its patch-oriented nature, it is helpful to |
300 %understand what patches are, and a little about the tools that work | |
301 %with them. | |
302 | |
303 MQ$B$O%Q%C%A;X8~$G$"$k@-<A$r1#JC$7$F$$$J$$$N$G!$%Q%C%A$,2?$G$"$k$+!$%D!<%k(B | |
304 $B$,%Q%C%A$r$I$&07$&$+$rM}2r$9$k$N$O$?$d$9$$!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
305 |
325 | 306 %The traditional Unix \command{diff} command compares two files, and |
307 %prints a list of differences between them. The \command{patch} command | |
308 %understands these differences as \emph{modifications} to make to a | |
309 %file. Take a look at figure~\ref{ex:mq:diff} for a simple example of | |
310 %these commands in action. | |
311 | |
312 Unix$B$NEAE}E*$J(B\command{diff}$B%3%^%s%I$O(B2$B$D$N%U%!%$%k$rHf3S$7!$:9J,$N%j%9(B | |
313 $B%H$r=PNO$9$k!%(B\command{patch}$B%3%^%s%I$O$3$N:9J,$rJQ99$H2r<a$7!$%U%!%$%k(B | |
314 $B$K5Z$\$9!%?^(B~\ref{ex:mq:diff}$B$K$3$l$i$N%3%^%s%I$NF0:n$r<($9!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
315 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
316 \begin{figure}[ht] |
46
dd657c4d3a47
Rename mq.diff to mq.dodiff Emacs won't screw up the syntax highlighting.
Bryan O'Sullivan <bos@serpentine.com>
parents:
35
diff
changeset
|
317 \interaction{mq.dodiff.diff} |
325 | 318 % \caption{Simple uses of the \command{diff} and \command{patch} |
319 % commands} | |
320 \caption{\command{diff}$B%3%^%s%I$H(B\command{patch}$B%3%^%s%I$NC1=c$J;HMQNc(B} | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
321 \label{ex:mq:diff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
322 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
323 |
329 | 324 %The type of file that \command{diff} generates (and \command{patch} |
325 %takes as input) is called a ``patch'' or a ``diff''; there is no | |
326 %difference between a patch and a diff. (We'll use the term ``patch'', | |
327 %since it's more commonly used.) | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
328 |
329 | 329 \command{diff}$B$,@8@.$9$k!J$^$?(B\command{patch}$B$,F~NO$K<h$k!K%U%!%$%k$N<o(B |
330 $BN`$O(B``patch''$B$^$?$O(B``diff''$B$H8F$P$l!$$3$l$i$N4V$K$O0c$$$O$J$$!%!J0J2<$G(B | |
331 $B$O!$$h$jB?$/;H$o$l$F$$$k(B``patch''$B$H$$$&8@MU$r;H$&$3$H$K$9$k!%!K(B | |
325 | 332 |
329 | 333 %A patch file can start with arbitrary text; the \command{patch} |
334 %command ignores this text, but MQ uses it as the commit message when | |
335 %creating changesets. To find the beginning of the patch content, | |
336 %\command{patch} searches for the first line that starts with the | |
337 %string ``\texttt{diff~-}''. | |
325 | 338 |
329 | 339 $B%Q%C%A%U%!%$%k$OG$0U$N%F%-%9%H$G;O$^$k!%(B\command{patch}$B%3%^%s%I$O$3$N%F(B |
340 $B%-%9%H$rL5;k$9$k$,!$(BMQ$B$O%A%'%s%8%;%C%H$r:n$k:]$N%3%_%C%H%a%C%;!<%8$H$7$F(B | |
341 $BMxMQ$9$k!%%Q%C%AFbMF$N@hF,$r8+$D$1$k$?$a$K(B\command{patch}$B$O(B | |
342 ``\texttt{diff~-}''$B$G;O$^$k:G=i$N9T$r%5!<%A$9$k!%(B | |
325 | 343 |
329 | 344 %MQ works with \emph{unified} diffs (\command{patch} can accept several |
345 %other diff formats, but MQ doesn't). A unified diff contains two | |
346 %kinds of header. The \emph{file header} describes the file being | |
347 %modified; it contains the name of the file to modify. When | |
348 %\command{patch} sees a new file header, it looks for a file with that | |
349 %name to start modifying. | |
350 | |
351 MQ\emph{unified} diffs$B7A<0$r;H$&!%!J(B\command{patch}$B%3%^%s%I$O$3$l0J30$K2?(B | |
352 $B<oN`$+$N(Bdiff$B%U%)!<%^%C%H$r<u$1IU$1$k$,!$(BMQ$B$G$OMxMQ$G$-$J$$!%!K(Bunified | |
353 diff$B$O(B2$B<oN`$N%X%C%@$r;}$D!%(B\emph{file $B%X%C%@(B}$B$OJQ99$5$l$F$$$k%U%!%$%k$r5-(B | |
354 $B=R$9$k!%(B\command{patch}$B%3%^%s%I$O!$?7$7$$%U%!%$%k%X%C%@$r8+$D$1$k$H!$$=$3(B | |
355 $B$K5-=R$5$l$F$$$k%U%!%$%kL>$r;}$D%U%!%$%k$rC5$9!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
356 |
329 | 357 %After the file header comes a series of \emph{hunks}. Each hunk starts |
358 %with a header; this identifies the range of line numbers within the file | |
359 %that the hunk should modify. Following the header, a hunk starts and | |
360 %ends with a few (usually three) lines of text from the unmodified file; | |
361 %these are called the \emph{context} for the hunk.If | |
362 %there's only a small amount of context between successive hunks, | |
363 %\command{diff} doesn't print a new hunk header; it just runs the hunks | |
364 %together, with a few lines of context between modifications. | |
365 | |
366 $B%U%!%$%k%X%C%@$N8e$K$O0lO"$N(B\emph{hunks}$B$,B3$/!%3F!9$N(Bhunk$B$O%X%C%@$G;O$^(B | |
367 $B$k!%$3$N%X%C%@$O%U%!%$%kFb$G(Bhunk$B$,2~JQ$9$Y$-9THV9f$NHO0O$r<1JL$9$k$N$K;H(B | |
368 $B$o$l$k!%%X%C%@$KB3$-!$(Bhunk$B$O?t9T!JDL>o(B3$B!K$N2~JQ$5$l$F$$$J$$%U%!%$%k$+$i$N(B | |
369 $B9T$,$"$k!%$3$l$i$O(Bhunk$B$N(B\emph{$B%3%s%F%-%9%H(B}$B$H8F$P$l$k!%$b$7O"B3$9$k(Bhunk$B$N(B | |
370 $B4V$K%3%s%F%-%9%H$,>/$7$7$+$J$1$l$P!$(B\command{diff}$B$O?7$?$J(Bhunk$B%X%C%@$r=P(B | |
371 $BNO$;$:!$3F!9$N(Bhunk$B$H4V$N%3%s%F%-%9%H$r9g$o$;$F=PNO$9$k!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
372 |
329 | 373 %Each line of context begins with a space character. Within the hunk, |
374 %a line that begins with ``\texttt{-}'' means ``remove this line,'' | |
375 %while a line that begins with ``\texttt{+}'' means ``insert this | |
376 %line.'' For example, a line that is modified is represented by one | |
377 %deletion and one insertion. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
378 |
329 | 379 $B%3%s%F%-%9%H$N3F9T$O!$6uGrJ8;z$G;O$^$k!%(Bhunk$BFb$G$O9T$O(B``\texttt{-}''$B$G;O(B |
380 $B$^$k!%$3$l$O(B``$B$3$N9T$r:o=|$;$h(B''$B$r0UL#$9$k!%(B | |
381 $B0lJ}!$(B``\texttt{+}''$B$G;O$^$k9T$O!$(B``$B$3$N9T$rA^F~$;$h(B''$B$r0UL#$9$k!%Nc$r5s(B | |
382 $B$2$k$H!$JQ99$5$l$?9T$O(B1$B$D$N:o=|$H(B1$B$D$NA^F~$GI=$5$l$k!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
383 |
329 | 384 %We will return to some of the more subtle aspects of patches later (in |
385 %section~\ref{sec:mq:adv-patch}), but you should have enough information | |
386 %now to use MQ. | |
387 | |
388 $B%Q%C%A$N:3:Y$JE@$K$D$$$F$O8e$G!J(B~\ref{sec:mq:adv-patch}$B!K$^$??($l$k$,!$(B | |
389 $B$3$l$^$G$G!$(BMQ$B$r;H$&$N$K==J,$J>pJs$O=R$Y$?!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
390 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
391 %\section{Getting started with Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
392 \section{Mercurial Queues$B$r;H$C$F$_$k(B} |
2 | 393 \label{sec:mq:start} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
394 |
330 | 395 %Because MQ is implemented as an extension, you must explicitly enable |
396 %before you can use it. (You don't need to download anything; MQ ships | |
397 %with the standard Mercurial distribution.) To enable MQ, edit your | |
398 %\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. | |
399 | |
400 MQ$B$O%(%/%9%F%s%7%g%s$H$7$F<BAu$5$l$F$$$k$N$G!$;H$&A0$KL@<(E*$KM-8z$K$9$k(B | |
401 $BI,MW$,$"$k!%!J2?$b%@%&%s%m!<%I$9$kI,MW$O$J$$!%(BMQ$B$ODL>o$N(BMercurial$B$KF1:-$5(B | |
402 $B$l$F$$$k!K(BMQ$B$rM-8z$K$9$k$K$O(B\tildefile{.hgrc}$B%U%!%$%k$rJT=8$7!$(B | |
403 $B?^(B~\ref{ex:mq:config}$B$N$h$&$K@_Dj$rDI2C$9$k!%(B | |
2 | 404 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
405 \begin{figure}[ht] |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
406 \begin{codesample4} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
407 [extensions] |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
408 hgext.mq = |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
409 \end{codesample4} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
410 \label{ex:mq:config} |
330 | 411 % \caption{Contents to add to \tildefile{.hgrc} to enable the MQ |
412 % extension} | |
413 \caption{MQ$B%(%/%9%F%s%7%g%s$rM-8z$K$9$k$?$a$K(B\tildefile{.hgrc}$B$KDI2C$9$kFbMF(B} | |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
414 \end{figure} |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
415 |
330 | 416 %Once the extension is enabled, it will make a number of new commands |
417 %available. To verify that the extension is working, you can use | |
418 %\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see | |
419 %the example in figure~\ref{ex:mq:enabled}. | |
420 | |
421 $B%(%/%9%F%s%7%g%s$,M-8z2=$5$l$k$H0lO"$N%3%^%s%I$,MxMQ2DG=$K$J$k!%%(%/%9%F(B | |
422 $B%s%7%g%s$,M-8z$G$"$k$3$H$r3NG'$9$k$?$a$K$O!$(B\hgcmd{help}$B$G(B | |
423 \hgxcmd{mq}{qinit}$B$,$"$k$3$H$r3NG'$9$k!%?^(B~\ref{ex:mq:enabled}$B$NNc$r;2>H(B | |
424 $B$5$l$?$$!%(B | |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
425 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
426 \begin{figure}[ht] |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
427 \interaction{mq.qinit-help.help} |
330 | 428 % \caption{How to verify that MQ is enabled} |
429 \caption{MQ$B$,M-8z$G$"$k$3$H$N3NG'K!(B} | |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
430 \label{ex:mq:enabled} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
431 \end{figure} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
432 |
330 | 433 %You can use MQ with \emph{any} Mercurial repository, and its commands |
434 %only operate within that repository. To get started, simply prepare | |
435 %the repository using the \hgxcmd{mq}{qinit} command (see | |
436 %figure~\ref{ex:mq:qinit}). This command creates an empty directory | |
437 %called \sdirname{.hg/patches}, where MQ will keep its metadata. As | |
438 %with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing | |
439 %if it succeeds. | |
440 | |
441 MQ$B$O(B\emph{$B$"$i$f$k(B}Mercurial$B%j%]%8%H%j$G;H$&$3$H$,$G$-!$$=$N%3%^%s%I$O3F!9(B | |
442 $B$N%j%]%8%H%j$NCf$K$@$1:nMQ$9$k!%;O$a$k$?$a$K(B\hgxcmd{mq}{qinit}$B%3%^%s%I$G(B | |
443 $B%j%]%8%H%j$rMQ0U$9$k!%!J?^(B~\ref{ex:mq:qinit}$B$r;2>H!K(B $B$3$N%3%^%s%I$O(BMQ$B$,%a(B | |
444 $B%?%G!<%?$rJ]B8$9$k$?$a$N(B\sdirname{.hg/patches}$B$H$$$&L>A0$N6u$N%G%#%l%/%H(B | |
445 $B%j$r:n@.$9$k!%B>$N(BMercurial$B%3%^%s%I$HF1MM$K!$(B\hgxcmd{mq}{qinit}$B%3%^%s%I(B | |
446 $B$b@.8y$9$k$H2?$bI=<($7$J$$!%(B | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
447 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
448 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
449 \interaction{mq.tutorial.qinit} |
330 | 450 % \caption{Preparing a repository for use with MQ} |
451 \caption{MQ$B$r;H$&$?$a$K%j%]%8%H%j$r=`Hw$9$k(B} | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
452 \label{ex:mq:qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
453 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
454 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
455 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
456 \interaction{mq.tutorial.qnew} |
330 | 457 % \caption{Creating a new patch} |
458 \caption{$B?7$7$$%Q%C%A$N:n@.(B} | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
459 \label{ex:mq:qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
460 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
461 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
462 %\subsection{Creating a new patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
463 \subsection{$B?7$7$$%Q%C%A$N:n@.(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
464 |
331 | 465 %To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This |
466 %command takes one argument, the name of the patch to create. MQ will | |
467 %use this as the name of an actual file in the \sdirname{.hg/patches} | |
468 %directory, as you can see in figure~\ref{ex:mq:qnew}. | |
469 | |
470 $B?7$7$$%Q%C%A$r07$&;~$O(B\hgxcmd{mq}{qnew}$B%3%^%s%I$r;H$&!%$3$N%3%^%s%I$O:n@.(B | |
471 $B$5$l$k%Q%C%A$NL>A0$H$7$F0z?t$r(B1$B$D<h$k!%?^(B~\ref{ex:mq:qnew}$B$N$h$&$K!$(BMQ$B$O(B | |
472 $B$3$l$r(B\sdirname{.hg/patches} $B%G%#%l%/%H%jFb$N<B:]$N%U%!%$%kL>$H$7$FMxMQ$9(B | |
473 $B$k!%(B | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
474 |
331 | 475 %Also newly present in the \sdirname{.hg/patches} directory are two |
476 %other files, \sfilename{series} and \sfilename{status}. The | |
477 %\sfilename{series} file lists all of the patches that MQ knows about | |
478 %for this repository, with one patch per line.Mercurial uses the | |
479 %\sfilename{status} file for internal book-keeping; it tracks all of the | |
480 %patches that MQ has \emph{applied} in this repository. | |
481 | |
482 \sdirname{.hg/patches}$B%G%#%l%/%H%j$NCf$K$O!$(B\sfilename{series}$B$H(B | |
483 \sfilename{status}$B$H$$$&(B2$B$D$N%U%!%$%k$b?7$7$/:n$i$l$k!%(B | |
484 \sfilename{series}$B$U$!$$$k$O(BMQ$B$,4XCN$9$k!$$3$N%j%]%8%H%jFb$NA4$F$N%Q%C%A(B | |
485 $B$N%j%9%H$,$"$j!$0l9T$K0l$D$N%Q%C%A$,5-=R$5$l$F$$$k!%(BMercurial$B$O(B | |
486 \sfilename{status}$B%U%!%$%k$rFbIt$N4IM}$KMQ$$$k!%$3$N%U%!%$%k$O%j%]%8%H%j(B | |
487 $BFb$G(BMQ$B$,E,MQ$7$?A4$F$N%Q%C%A$,5-O?$5$l$F$$$k!%(B | |
488 | |
489 %\begin{note} | |
490 % You may sometimes want to edit the \sfilename{series} file by hand; | |
491 % for example, to change the sequence in which some patches are | |
492 % applied. However, manually editing the \sfilename{status} file is | |
493 % almost always a bad idea, as it's easy to corrupt MQ's idea of what | |
494 % is happening. | |
495 %\end{note} | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
496 |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
497 \begin{note} |
331 | 498 $BNc$($P!$J#?t$N%Q%C%A$,E,MQ$5$l$k<j=g$rJQ99$9$k$J$I$NL\E*$G(B |
499 \sfilename{series}$B%U%!%$%k$r<j$GJT=8$7$?$/$J$k$3$H$,$"$k$+$b$7$l$J$$!%(B | |
500 $B$7$+$7(B\sfilename{status}$B$r<j$GJT=8$9$k$N$O$[$H$s$I$N>l9gNI$/$J$$9M$($G!$(B | |
501 MQ$B$N>uBVDI@W$r4JC1$K68$o$;$F$7$^$&!%(B | |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
502 \end{note} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
503 |
331 | 504 %Once you have created your new patch, you can edit files in the |
505 %working directory as you usually would. All of the normal Mercurial | |
506 %commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as | |
507 %they did before. | |
508 | |
509 $B?7$7$$%Q%C%A$r:n$C$?8e!$%o!<%-%s%0%G%#%l%/%H%jFb$N%U%!%$%k$rDL>oDL$jJT=8(B | |
510 $B$9$k$3$H$,$G$-$k!%(B\hgcmd{diff}$B$d(B\hgcmd{annotate}$B$N$h$&$JA4$F$NDL>o$N(B | |
511 Mercurial$B%3%^%s%I$,A4$/F1$8$h$&$K;H$($k!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
512 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
513 %\subsection{Refreshing a patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
514 \subsection{$B%Q%C%A$N:F@8(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
515 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
516 When you reach a point where you want to save your work, use the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
517 \hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
518 you are working on. This command folds the changes you have made in |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
519 the working directory into your patch, and updates its corresponding |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
520 changeset to contain those changes. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
521 |
331 | 522 |
523 | |
524 | |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
525 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
526 \interaction{mq.tutorial.qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
527 \caption{Refreshing a patch} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
528 \label{ex:mq:qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
529 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
530 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
531 You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way |
13 | 532 to ``checkpoint'' your work. Refresh your patch at an opportune |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
533 time; try an experiment; and if the experiment doesn't work out, |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
534 \hgcmd{revert} your modifications back to the last time you refreshed. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
535 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
536 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
537 \interaction{mq.tutorial.qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
538 \caption{Refresh a patch many times to accumulate changes} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
539 \label{ex:mq:qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
540 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
541 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
542 %\subsection{Stacking and tracking patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
543 \subsection{$B%Q%C%A$N=8@Q$HDI@W(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
544 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
545 Once you have finished working on a patch, or need to work on another, |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
546 you can use the \hgxcmd{mq}{qnew} command again to create a new patch. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
547 Mercurial will apply this patch on top of your existing patch. See |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
548 figure~\ref{ex:mq:qnew2} for an example. Notice that the patch |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
549 contains the changes in our prior patch as part of its context (you |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
550 can see this more clearly in the output of \hgcmd{annotate}). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
551 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
552 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
553 \interaction{mq.tutorial.qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
554 \caption{Stacking a second patch on top of the first} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
555 \label{ex:mq:qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
556 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
557 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
558 So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
559 been careful to only use regular Mercurial commands. However, MQ |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
560 provides many commands that are easier to use when you are thinking |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
561 about patches, as illustrated in figure~\ref{ex:mq:qseries}: |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
562 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
563 \begin{itemize} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
564 \item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
565 about in this repository, from oldest to newest (most recently |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
566 \emph{created}). |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
567 \item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
568 \emph{applied} in this repository, again from oldest to newest (most |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
569 recently applied). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
570 \end{itemize} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
571 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
572 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
573 \interaction{mq.tutorial.qseries} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
574 \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
575 \hgxcmd{mq}{qapplied}} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
576 \label{ex:mq:qseries} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
577 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
578 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
579 %\subsection{Manipulating the patch stack} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
580 \subsection{$B%Q%C%A%9%?%C%/$NA`:n(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
581 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
582 The previous discussion implied that there must be a difference |
11 | 583 between ``known'' and ``applied'' patches, and there is. MQ can |
584 manage a patch without it being applied in the repository. | |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
585 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
586 An \emph{applied} patch has a corresponding changeset in the |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
587 repository, and the effects of the patch and changeset are visible in |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
588 the working directory. You can undo the application of a patch using |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
589 the \hgxcmd{mq}{qpop} command. MQ still \emph{knows about}, or manages, a |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
590 popped patch, but the patch no longer has a corresponding changeset in |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
591 the repository, and the working directory does not contain the changes |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
592 made by the patch. Figure~\ref{fig:mq:stack} illustrates the |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
593 difference between applied and tracked patches. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
594 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
595 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
596 \centering |
35
e68f4a96c16e
Fixed the \grafix macro to work for PDFs again.
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
30
diff
changeset
|
597 \grafix{mq-stack} |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
598 \caption{Applied and unapplied patches in the MQ patch stack} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
599 \label{fig:mq:stack} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
600 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
601 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
602 You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
603 command. This creates a new changeset to correspond to the patch, and |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
604 the patch's changes once again become present in the working |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
605 directory. See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop} |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
606 and \hgxcmd{mq}{qpush} in action. Notice that once we have popped a patch |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
607 or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
608 that of \hgxcmd{mq}{qapplied} has changed. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
609 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
610 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
611 \interaction{mq.tutorial.qpop} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
612 \caption{Modifying the stack of applied patches} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
613 \label{ex:mq:qpop} |
11 | 614 \end{figure} |
615 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
616 %\subsection{Pushing and popping many patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
617 \subsection{$B%Q%C%A$N%W%C%7%e$H%]%C%W(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
618 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
619 While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
620 a time by default, you can push and pop many patches in one go. The |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
621 \hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
622 unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
623 causes it to pop all applied patches. (For some more ways to push and |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
624 pop many patches, see section~\ref{sec:mq:perf} below.) |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
625 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
626 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
627 \interaction{mq.tutorial.qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
628 \caption{Pushing all unapplied patches} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
629 \label{ex:mq:qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
630 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
631 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
632 %\subsection{Safety checks, and overriding them} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
633 \subsection{$B0BA4@-%A%'%C%/$H%*!<%P%i%$%I(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
634 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
635 Several MQ commands check the working directory before they do |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
636 anything, and fail if they find any modifications. They do this to |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
637 ensure that you won't lose any changes that you have made, but not yet |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
638 incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this; |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
639 the \hgxcmd{mq}{qnew} command will not create a new patch if there are |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
640 outstanding changes, caused in this case by the \hgcmd{add} of |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
641 \filename{file3}. |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
642 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
643 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
644 \interaction{mq.tutorial.add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
645 \caption{Forcibly creating a patch} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
646 \label{ex:mq:add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
647 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
648 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
649 Commands that check the working directory all take an ``I know what |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
650 I'm doing'' option, which is always named \option{-f}. The exact |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
651 meaning of \option{-f} depends on the command. For example, |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
652 \hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
653 changes into the new patch it creates, but |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
654 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
655 files affected by the patch that it is popping. Be sure to read the |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
656 documentation for a command's \option{-f} option before you use it! |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
657 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
658 %\subsection{Working on several patches at once} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
659 \subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} |
13 | 660 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
661 The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} |
13 | 662 applied patch. This means that you can suspend work on one patch (by |
663 refreshing it), pop or push to make a different patch the top, and | |
664 work on \emph{that} patch for a while. | |
665 | |
666 Here's an example that illustrates how you can use this ability. | |
667 Let's say you're developing a new feature as two patches. The first | |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
668 is a change to the core of your software, and the second---layered on |
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
669 top of the first---changes the user interface to use the code you just |
13 | 670 added to the core. If you notice a bug in the core while you're |
671 working on the UI patch, it's easy to fix the core. Simply | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
672 \hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
673 \hgxcmd{mq}{qpop} down to the core patch. Fix the core bug, |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
674 \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI |
13 | 675 patch to continue where you left off. |
676 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
677 %\section{More about patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
678 \section{$B$5$i$K%Q%C%A$K$D$$$F(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
679 \label{sec:mq:adv-patch} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
680 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
681 MQ uses the GNU \command{patch} command to apply patches, so it's |
26 | 682 helpful to know a few more detailed aspects of how \command{patch} |
683 works, and about patches themselves. | |
684 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
685 %\subsection{The strip count} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
686 \subsection{$B%9%H%j%C%W%+%&%s%H(B} |
26 | 687 |
688 If you look at the file headers in a patch, you will notice that the | |
689 pathnames usually have an extra component on the front that isn't | |
690 present in the actual path name. This is a holdover from the way that | |
691 people used to generate patches (people still do this, but it's | |
692 somewhat rare with modern revision control tools). | |
693 | |
694 Alice would unpack a tarball, edit her files, then decide that she | |
695 wanted to create a patch. So she'd rename her working directory, | |
696 unpack the tarball again (hence the need for the rename), and use the | |
697 \cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to | |
698 recursively generate a patch between the unmodified directory and the | |
699 modified one. The result would be that the name of the unmodified | |
700 directory would be at the front of the left-hand path in every file | |
701 header, and the name of the modified directory would be at the front | |
702 of the right-hand path. | |
703 | |
704 Since someone receiving a patch from the Alices of the net would be | |
705 unlikely to have unmodified and modified directories with exactly the | |
706 same names, the \command{patch} command has a \cmdopt{patch}{-p} | |
707 option that indicates the number of leading path name components to | |
708 strip when trying to apply a patch. This number is called the | |
709 \emph{strip count}. | |
710 | |
711 An option of ``\texttt{-p1}'' means ``use a strip count of one''. If | |
712 \command{patch} sees a file name \filename{foo/bar/baz} in a file | |
713 header, it will strip \filename{foo} and try to patch a file named | |
714 \filename{bar/baz}. (Strictly speaking, the strip count refers to the | |
715 number of \emph{path separators} (and the components that go with them | |
716 ) to strip. A strip count of one will turn \filename{foo/bar} into | |
717 \filename{bar}, but \filename{/foo/bar} (notice the extra leading | |
718 slash) into \filename{foo/bar}.) | |
719 | |
720 The ``standard'' strip count for patches is one; almost all patches | |
721 contain one leading path name component that needs to be stripped. | |
722 Mercurial's \hgcmd{diff} command generates path names in this form, | |
723 and the \hgcmd{import} command and MQ expect patches to have a strip | |
724 count of one. | |
725 | |
726 If you receive a patch from someone that you want to add to your patch | |
727 queue, and the patch needs a strip count other than one, you cannot | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
728 just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet |
26 | 729 have a \texttt{-p} option (see~\bug{311}). Your best bet is to |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
730 \hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} |
26 | 731 to apply their patch, followed by \hgcmd{addremove} to pick up any |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
732 files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. |
26 | 733 This complexity may become unnecessary; see~\bug{311} for details. |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
734 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
735 %\subsection{Strategies for applying a patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
736 \subsection{$B%Q%C%AE,MQ$N$?$a$N@oN,(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
737 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
738 When \command{patch} applies a hunk, it tries a handful of |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
739 successively less accurate strategies to try to make the hunk apply. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
740 This falling-back technique often makes it possible to take a patch |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
741 that was generated against an old version of a file, and apply it |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
742 against a newer version of that file. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
743 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
744 First, \command{patch} tries an exact match, where the line numbers, |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
745 the context, and the text to be modified must apply exactly. If it |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
746 cannot make an exact match, it tries to find an exact match for the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
747 context, without honouring the line numbering information. If this |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
748 succeeds, it prints a line of output saying that the hunk was applied, |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
749 but at some \emph{offset} from the original line number. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
750 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
751 If a context-only match fails, \command{patch} removes the first and |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
752 last lines of the context, and tries a \emph{reduced} context-only |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
753 match. If the hunk with reduced context succeeds, it prints a message |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
754 saying that it applied the hunk with a \emph{fuzz factor} (the number |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
755 after the fuzz factor indicates how many lines of context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
756 \command{patch} had to trim before the patch applied). |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
757 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
758 When neither of these techniques works, \command{patch} prints a |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
759 message saying that the hunk in question was rejected. It saves |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
760 rejected hunks (also simply called ``rejects'') to a file with the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
761 same name, and an added \sfilename{.rej} extension. It also saves an |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
762 unmodified copy of the file with a \sfilename{.orig} extension; the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
763 copy of the file without any extensions will contain any changes made |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
764 by hunks that \emph{did} apply cleanly. If you have a patch that |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
765 modifies \filename{foo} with six hunks, and one of them fails to |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
766 apply, you will have: an unmodified \filename{foo.orig}, a |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
767 \filename{foo.rej} containing one hunk, and \filename{foo}, containing |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
768 the changes made by the five successful five hunks. |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
769 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
770 %\subsection{Some quirks of patch representation} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
771 \subsection{$B%Q%C%AI=8=$N4qL/$JE@(B} |
25
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
772 |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
773 There are a few useful things to know about how \command{patch} works |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
774 with files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
775 \begin{itemize} |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
776 \item This should already be obvious, but \command{patch} cannot |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
777 handle binary files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
778 \item Neither does it care about the executable bit; it creates new |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
779 files as readable, but not executable. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
780 \item \command{patch} treats the removal of a file as a diff between |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
781 the file to be removed and the empty file. So your idea of ``I |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
782 deleted this file'' looks like ``every line of this file was |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
783 deleted'' in a patch. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
784 \item It treats the addition of a file as a diff between the empty |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
785 file and the file to be added. So in a patch, your idea of ``I |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
786 added this file'' looks like ``every line of this file was added''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
787 \item It treats a renamed file as the removal of the old name, and the |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
788 addition of the new name. This means that renamed files have a big |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
789 footprint in patches. (Note also that Mercurial does not currently |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
790 try to infer when files have been renamed or copied in a patch.) |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
791 \item \command{patch} cannot represent empty files, so you cannot use |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
792 a patch to represent the notion ``I added this empty file to the |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
793 tree''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
794 \end{itemize} |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
795 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
796 %\subsection{Beware the fuzz} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
797 \subsection{$B[#Kf$JE@$K$D$$$F(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
798 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
799 While applying a hunk at an offset, or with a fuzz factor, will often |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
800 be completely successful, these inexact techniques naturally leave |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
801 open the possibility of corrupting the patched file. The most common |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
802 cases typically involve applying a patch twice, or at an incorrect |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
803 location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
804 mentions an offset or fuzz factor, you should make sure that the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
805 modified files are correct afterwards. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
806 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
807 It's often a good idea to refresh a patch that has applied with an |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
808 offset or fuzz factor; refreshing the patch generates new context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
809 information that will make it apply cleanly. I say ``often,'' not |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
810 ``always,'' because sometimes refreshing a patch will make it fail to |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
811 apply against a different revision of the underlying files. In some |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
812 cases, such as when you're maintaining a patch that must sit on top of |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
813 multiple versions of a source tree, it's acceptable to have a patch |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
814 apply with some fuzz, provided you've verified the results of the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
815 patching process in such cases. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
816 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
817 %\subsection{Handling rejection} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
818 \subsection{$B%j%8%'%/%H$N<h$j07$$(B} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
819 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
820 If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
821 message and exit. If it has left \sfilename{.rej} files behind, it is |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
822 usually best to fix up the rejected hunks before you push more patches |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
823 or do any further work. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
824 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
825 If your patch \emph{used to} apply cleanly, and no longer does because |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
826 you've changed the underlying code that your patches are based on, |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
827 Mercurial Queues can help; see section~\ref{sec:mq:merge} for details. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
828 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
829 Unfortunately, there aren't any great techniques for dealing with |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
830 rejected hunks. Most often, you'll need to view the \sfilename{.rej} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
831 file and edit the target file, applying the rejected hunks by hand. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
832 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
833 If you're feeling adventurous, Neil Brown, a Linux kernel hacker, |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
834 wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
835 vigorous than \command{patch} in its attempts to make a patch apply. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
836 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
837 Another Linux kernel hacker, Chris Mason (the author of Mercurial |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
838 Queues), wrote a similar tool called |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
839 \command{mpatch}~\cite{web:mpatch}, which takes a simple approach to |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
840 automating the application of hunks rejected by \command{patch}. The |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
841 \command{mpatch} command can help with four common reasons that a hunk |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
842 may be rejected: |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
843 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
844 \begin{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
845 \item The context in the middle of a hunk has changed. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
846 \item A hunk is missing some context at the beginning or end. |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
847 \item A large hunk might apply better---either entirely or in |
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
848 part---if it was broken up into smaller hunks. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
849 \item A hunk removes lines with slightly different content than those |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
850 currently present in the file. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
851 \end{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
852 |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
853 If you use \command{wiggle} or \command{mpatch}, you should be doubly |
55 | 854 careful to check your results when you're done. In fact, |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
855 \command{mpatch} enforces this method of double-checking the tool's |
55 | 856 output, by automatically dropping you into a merge program when it has |
857 done its job, so that you can verify its work and finish off any | |
858 remaining merges. | |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
859 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
860 %\section{Getting the best performance out of MQ} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
861 \section{MQ$B$r:GBg8B$K3hMQ$9$k(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
862 \label{sec:mq:perf} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
863 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
864 MQ is very efficient at handling a large number of patches. I ran |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
865 some performance experiments in mid-2006 for a talk that I gave at the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
866 2006 EuroPython conference~\cite{web:europython}. I used as my data |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
867 set the Linux 2.6.17-mm1 patch series, which consists of 1,738 |
66 | 868 patches. I applied these on top of a Linux kernel repository |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
869 containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
870 2.6.17. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
871 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
872 On my old, slow laptop, I was able to |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
873 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes, |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
874 and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds. (On a |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
875 newer laptop, the time to push all patches dropped to two minutes.) I |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
876 could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
877 lines of changes to 287 files) in 6.6 seconds. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
878 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
879 Clearly, MQ is well suited to working in large trees, but there are a |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
880 few tricks you can use to get the best performance of it. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
881 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
882 First of all, try to ``batch'' operations together. Every time you |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
883 run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
884 directory once to make sure you haven't made some changes and then |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
885 forgotten to run \hgxcmd{mq}{qrefresh}. On a small tree, the time that |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
886 this scan takes is unnoticeable. However, on a medium-sized tree |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
887 (containing tens of thousands of files), it can take a second or more. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
888 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
889 The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
890 multiple patches at a time. You can identify the ``destination |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
891 patch'' that you want to end up at. When you \hgxcmd{mq}{qpush} with a |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
892 destination specified, it will push patches until that patch is at the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
893 top of the applied stack. When you \hgxcmd{mq}{qpop} to a destination, MQ |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
894 will pop patches until the destination patch is at the top. |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
895 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
896 You can identify a destination patch using either the name of the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
897 patch, or by number. If you use numeric addressing, patches are |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
898 counted from zero; this means that the first patch is zero, the second |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
899 is one, and so on. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
900 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
901 %\section{Updating your patches when the underlying code changes} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
902 \section{$B2<0L%3!<%I$NJQ2=$K9g$o$;$F%Q%C%A$r99?7$9$k(B} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
903 \label{sec:mq:merge} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
904 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
905 It's common to have a stack of patches on top of an underlying |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
906 repository that you don't modify directly. If you're working on |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
907 changes to third-party code, or on a feature that is taking longer to |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
908 develop than the rate of change of the code beneath, you will often |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
909 need to sync up with the underlying code, and fix up any hunks in your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
910 patches that no longer apply. This is called \emph{rebasing} your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
911 patch series. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
912 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
913 The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
914 your patches, then \hgcmd{pull} changes into the underlying |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
915 repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
916 patches again. MQ will stop pushing any time it runs across a patch |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
917 that fails to apply during conflicts, allowing you to fix your |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
918 conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
919 until you have fixed your entire stack. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
920 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
921 This approach is easy to use and works well if you don't expect |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
922 changes to the underlying code to affect how well your patches apply. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
923 If your patch stack touches code that is modified frequently or |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
924 invasively in the underlying repository, however, fixing up rejected |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
925 hunks by hand quickly becomes tiresome. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
926 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
927 It's possible to partially automate the rebasing process. If your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
928 patches apply cleanly against some revision of the underlying repo, MQ |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
929 can use this information to help you to resolve conflicts between your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
930 patches and a different revision. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
931 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
932 The process is a little involved. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
933 \begin{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
934 \item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
935 the revision where you know that they apply cleanly. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
936 \item Save a backup copy of your patch directory using |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
937 \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. This prints |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
938 the name of the directory that it has saved the patches in. It will |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
939 save the patches to a directory called |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
940 \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
941 integer. It also commits a ``save changeset'' on top of your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
942 applied patches; this is for internal book-keeping, and records the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
943 states of the \sfilename{series} and \sfilename{status} files. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
944 \item Use \hgcmd{pull} to bring new changes into the underlying |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
945 repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.) |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
946 \item Update to the new tip revision, using |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
947 \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
948 have pushed. |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
949 \item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
950 \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
951 tells MQ to perform a three-way merge if the patch fails to apply. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
952 \end{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
953 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
954 During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
955 \sfilename{series} file is applied normally. If a patch applies with |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
956 fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
957 performs a three-way merge with the corresponding changeset. This |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
958 merge uses Mercurial's normal merge machinery, so it may pop up a GUI |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
959 merge tool to help you to resolve problems. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
960 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
961 When you finish resolving the effects of a patch, MQ refreshes your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
962 patch based on the result of the merge. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
963 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
964 At the end of this process, your repository will have one extra head |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
965 from the old patch queue, and a copy of the old patch queue will be in |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
966 \sdirname{.hg/patches.\emph{N}}. You can remove the extra head using |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
967 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
968 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
969 you are sure that you no longer need it as a backup. |
13 | 970 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
971 %\section{Identifying patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
972 \section{$B%Q%C%A$N<1JL(B} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
973 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
974 MQ commands that work with patches let you refer to a patch either by |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
975 using its name or by a number. By name is obvious enough; pass the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
976 name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will |
55 | 977 push patches until \filename{foo.patch} is applied. |
978 | |
979 As a shortcut, you can refer to a patch using both a name and a | |
980 numeric offset; \texttt{foo.patch-2} means ``two patches before | |
981 \texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches | |
982 after \texttt{bar.patch}''. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
983 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
984 Referring to a patch by index isn't much different. The first patch |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
985 printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
986 of those start-at-zero counting systems); the second is patch one; and |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
987 so on |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
988 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
989 MQ also makes it easy to work with patches when you are using normal |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
990 Mercurial commands. Every command that accepts a changeset ID will |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
991 also accept the name of an applied patch. MQ augments the tags |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
992 normally in the repository with an eponymous one for each applied |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
993 patch. In addition, the special tags \index{tags!special tag |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
994 names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
995 names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
996 topmost applied patches, respectively. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
997 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
998 These additions to Mercurial's normal tagging capabilities make |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
999 dealing with patches even more of a breeze. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1000 \begin{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1001 \item Want to patchbomb a mailing list with your latest series of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1002 changes? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1003 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1004 hg email qbase:qtip |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1005 \end{codesample4} |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
1006 (Don't know what ``patchbombing'' is? See |
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
1007 section~\ref{sec:hgext:patchbomb}.) |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1008 \item Need to see all of the patches since \texttt{foo.patch} that |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1009 have touched files in a subdirectory of your tree? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1010 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1011 hg log -r foo.patch:qtip \emph{subdir} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1012 \end{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1013 \end{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1014 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1015 Because MQ makes the names of patches available to the rest of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1016 Mercurial through its normal internal tag machinery, you don't need to |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1017 type in the entire name of a patch when you want to identify it by |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1018 name. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1019 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1020 \begin{figure}[ht] |
155
914babdc99c8
run-example: better error if bogus section name found.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
1021 \interaction{mq.id.output} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1022 \caption{Using MQ's tag features to work with patches} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1023 \label{ex:mq:id} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1024 \end{figure} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1025 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1026 Another nice consequence of representing patch names as tags is that |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1027 when you run the \hgcmd{log} command, it will display a patch's name |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1028 as a tag, simply as part of its normal output. This makes it easy to |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1029 visually distinguish applied patches from underlying ``normal'' |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1030 revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1031 commands in use with applied patches. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1032 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1033 %\section{Useful things to know about} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1034 \section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} |
26 | 1035 |
1036 There are a number of aspects of MQ usage that don't fit tidily into | |
1037 sections of their own, but that are good to know. Here they are, in | |
1038 one place. | |
1039 | |
1040 \begin{itemize} | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1041 \item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it |
26 | 1042 again, the changeset that represents the patch after the pop/push |
1043 will have a \emph{different identity} than the changeset that | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
1044 represented the hash beforehand. See |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
1045 section~\ref{sec:mqref:cmd:qpush} for information as to why this is. |
26 | 1046 \item It's not a good idea to \hgcmd{merge} changes from another |
1047 branch with a patch changeset, at least if you want to maintain the | |
1048 ``patchiness'' of that changeset and changesets below it on the | |
1049 patch stack. If you try to do this, it will appear to succeed, but | |
1050 MQ will become confused. | |
1051 \end{itemize} | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1052 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1053 %\section{Managing patches in a repository} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1054 \section{$B%j%]%8%H%jFb$G$N%Q%C%A$N4IM}(B} |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
1055 \label{sec:mq:repo} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1056 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1057 Because MQ's \sdirname{.hg/patches} directory resides outside a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1058 Mercurial repository's working directory, the ``underlying'' Mercurial |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1059 repository knows nothing about the management or presence of patches. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1060 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1061 This presents the interesting possibility of managing the contents of |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1062 the patch directory as a Mercurial repository in its own right. This |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1063 can be a useful way to work. For example, you can work on a patch for |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1064 a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1065 the patch. This lets you ``roll back'' to that version of the patch |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1066 later on. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1067 |
26 | 1068 You can then share different versions of the same patch stack among |
1069 multiple underlying repositories. I use this when I am developing a | |
1070 Linux kernel feature. I have a pristine copy of my kernel sources for | |
1071 each of several CPU architectures, and a cloned repository under each | |
1072 that contains the patches I am working on. When I want to test a | |
1073 change on a different architecture, I push my current patches to the | |
1074 patch repository associated with that kernel tree, pop and push all of | |
1075 my patches, and build and test that kernel. | |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1076 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1077 Managing patches in a repository makes it possible for multiple |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1078 developers to work on the same patch series without colliding with |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1079 each other, all on top of an underlying source base that they may or |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1080 may not control. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1081 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1082 %\subsection{MQ support for patch repositories} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1083 \subsection{MQ$B$K$h$k%Q%C%A%j%]%8%H%j%5%]!<%H(B} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1084 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1085 MQ helps you to work with the \sdirname{.hg/patches} directory as a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1086 repository; when you prepare a repository for working with patches |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1087 using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1088 create the \sdirname{.hg/patches} directory as a Mercurial repository. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1089 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1090 \begin{note} |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1091 If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1092 into the \sdirname{.hg/patches} directory at any time and run |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1093 \hgcmd{init}. Don't forget to add an entry for the |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
1094 \sfilename{status} file to the \sfilename{.hgignore} file, though |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
66
diff
changeset
|
1095 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1096 (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
1097 automatically); you \emph{really} don't want to manage the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
1098 \sfilename{status} file. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1099 \end{note} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1100 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1101 As a convenience, if MQ notices that the \dirname{.hg/patches} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1102 directory is a repository, it will automatically \hgcmd{add} every |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1103 patch that you create and import. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1104 |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1105 MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1106 \hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1107 some bothersome typing. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1108 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1109 Finally, as a convenience to manage the patch directory, you can |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1110 define the alias \command{mq} on Unix systems. For example, on Linux |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1111 systems using the \command{bash} shell, you can include the following |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1112 snippet in your \tildefile{.bashrc}. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1113 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1114 \begin{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1115 alias mq=`hg -R \$(hg root)/.hg/patches' |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1116 \end{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1117 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1118 You can then issue commands of the form \cmdargs{mq}{pull} from |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1119 the main repository. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1120 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1121 %\subsection{A few things to watch out for} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1122 \subsection{$B4F;k$7$F$*$/$Y$-$$$/$D$+$NE@(B} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1123 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1124 MQ's support for working with a repository full of patches is limited |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1125 in a few small respects. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1126 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1127 MQ cannot automatically detect changes that you make to the patch |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1128 directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1129 changes to patches or the \sfilename{series} file, you will have to |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1130 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1131 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
1132 see those changes show up there. If you forget to do this, you can |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
1133 confuse MQ's idea of which patches are applied. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1134 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1135 %\section{Third party tools for working with patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1136 \section{$B%Q%C%A8~$1%5!<%I%Q!<%F%#%D!<%k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1137 \label{sec:mq:tools} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1138 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1139 Once you've been working with patches for a while, you'll find |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1140 yourself hungry for tools that will help you to understand and |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1141 manipulate the patches you're dealing with. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1142 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1143 The \command{diffstat} command~\cite{web:diffstat} generates a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1144 histogram of the modifications made to each file in a patch. It |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
1145 provides a good way to ``get a sense of'' a patch---which files it |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1146 affects, and how much change it introduces to each file and as a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1147 whole. (I find that it's a good idea to use \command{diffstat}'s |
241
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
1148 \cmdopt{diffstat}{-p} option as a matter of course, as otherwise it |
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
1149 will try to do clever things with prefixes of file names that |
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
1150 inevitably confuse at least me.) |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1151 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1152 \begin{figure}[ht] |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1153 \interaction{mq.tools.tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1154 \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1155 \label{ex:mq:tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1156 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1157 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1158 The \package{patchutils} package~\cite{web:patchutils} is invaluable. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1159 It provides a set of small utilities that follow the ``Unix |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1160 philosophy;'' each does one useful thing with a patch. The |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1161 \package{patchutils} command I use most is \command{filterdiff}, which |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1162 extracts subsets from a patch file. For example, given a patch that |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1163 modifies hundreds of files across dozens of directories, a single |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1164 invocation of \command{filterdiff} can generate a smaller patch that |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
1165 only touches files whose names match a particular glob pattern. See |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
1166 section~\ref{mq-collab:tips:interdiff} for another example. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1167 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1168 %\section{Good ways to work with patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1169 \section{$B9%$^$7$$%Q%C%A<h$j07$$J}K!(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1170 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1171 Whether you are working on a patch series to submit to a free software |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1172 or open source project, or a series that you intend to treat as a |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1173 sequence of regular changesets when you're done, you can use some |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1174 simple techniques to keep your work well organised. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1175 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1176 Give your patches descriptive names. A good name for a patch might be |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1177 \filename{rework-device-alloc.patch}, because it will immediately give |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1178 you a hint what the purpose of the patch is. Long names shouldn't be |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1179 a problem; you won't be typing the names often, but you \emph{will} be |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1180 running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1181 Good naming becomes especially important when you have a number of |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1182 patches to work with, or if you are juggling a number of different |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1183 tasks and your patches only get a fraction of your attention. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1184 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1185 Be aware of what patch you're working on. Use the \hgxcmd{mq}{qtop} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1186 command and skim over the text of your patches frequently---for |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1187 example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1188 you stand. I have several times worked on and \hgxcmd{mq}{qrefresh}ed a |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1189 patch other than the one I intended, and it's often tricky to migrate |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1190 changes into the right patch after making them in the wrong one. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1191 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1192 For this reason, it is very much worth investing a little time to |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1193 learn how to use some of the third-party tools I described in |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1194 section~\ref{sec:mq:tools}, particularly \command{diffstat} and |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1195 \command{filterdiff}. The former will give you a quick idea of what |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1196 changes your patch is making, while the latter makes it easy to splice |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1197 hunks selectively out of one patch and into another. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1198 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1199 %\section{MQ cookbook} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1200 \section{MQ$B%/%C%/%V%C%/(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1201 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1202 %\subsection{Manage ``trivial'' patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1203 \subsection{``$B%H%j%S%"%k(B''$B$J%Q%C%A$N4IM}(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1204 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1205 Because the overhead of dropping files into a new Mercurial repository |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1206 is so low, it makes a lot of sense to manage patches this way even if |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1207 you simply want to make a few changes to a source tarball that you |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1208 downloaded. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1209 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1210 Begin by downloading and unpacking the source tarball, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1211 and turning it into a Mercurial repository. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1212 \interaction{mq.tarball.download} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1213 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1214 Continue by creating a patch stack and making your changes. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1215 \interaction{mq.tarball.qinit} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1216 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1217 Let's say a few weeks or months pass, and your package author releases |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1218 a new version. First, bring their changes into the repository. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1219 \interaction{mq.tarball.newsource} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1220 The pipeline starting with \hgcmd{locate} above deletes all files in |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1221 the working directory, so that \hgcmd{commit}'s |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1222 \hgopt{commit}{--addremove} option can actually tell which files have |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1223 really been removed in the newer version of the source. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1224 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1225 Finally, you can apply your patches on top of the new tree. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1226 \interaction{mq.tarball.repush} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1227 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1228 %\subsection{Combining entire patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1229 \subsection{$B%Q%C%AF1;N$r7k9g$9$k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1230 \label{sec:mq:combine} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1231 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1232 MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire |
55 | 1233 patches. This ``folds'' the patches you name, in the order you name |
1234 them, into the topmost applied patch, and concatenates their | |
1235 descriptions onto the end of its description. The patches that you | |
1236 fold must be unapplied before you fold them. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1237 |
55 | 1238 The order in which you fold patches matters. If your topmost applied |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1239 patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and |
55 | 1240 \texttt{quux} into it, you will end up with a patch that has the same |
1241 effect as if you applied first \texttt{foo}, then \texttt{bar}, | |
1242 followed by \texttt{quux}. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1243 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1244 %\subsection{Merging part of one patch into another} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1245 \subsection{$B%Q%C%A$N0lItJ,$rJL$N%Q%C%A$X%^!<%8$9$k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1246 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1247 Merging \emph{part} of one patch into another is more difficult than |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1248 combining entire patches. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1249 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1250 If you want to move changes to entire files, you can use |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1251 \command{filterdiff}'s \cmdopt{filterdiff}{-i} and |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1252 \cmdopt{filterdiff}{-x} options to choose the modifications to snip |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1253 out of one patch, concatenating its output onto the end of the patch |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1254 you want to merge into. You usually won't need to modify the patch |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1255 you've merged the changes from. Instead, MQ will report some rejected |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1256 hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1257 other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1258 the duplicate hunks. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1259 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1260 If you have a patch that has multiple hunks modifying a file, and you |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1261 only want to move a few of those hunks, the job becomes more messy, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1262 but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1263 print some metadata about the patch. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1264 \interaction{mq.tools.lsdiff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1265 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1266 This command prints three different kinds of number: |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1267 \begin{itemize} |
26 | 1268 \item (in the first column) a \emph{file number} to identify each file |
1269 modified in the patch; | |
1270 \item (on the next line, indented) the line number within a modified | |
1271 file where a hunk starts; and | |
1272 \item (on the same line) a \emph{hunk number} to identify that hunk. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1273 \end{itemize} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1274 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1275 You'll have to use some visual inspection, and reading of the patch, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1276 to identify the file and hunk numbers you'll want, but you can then |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1277 pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1278 and \cmdopt{filterdiff}{--hunks} options, to select exactly the file |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1279 and hunk you want to extract. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1280 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1281 Once you have this hunk, you can concatenate it onto the end of your |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1282 destination patch and continue with the remainder of |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1283 section~\ref{sec:mq:combine}. |
26 | 1284 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1285 %\section{Differences between quilt and MQ} |
325 | 1286 \section{quilt$B$H(BMQ$B$N0c$$(B} |
26 | 1287 |
325 | 1288 %If you are already familiar with quilt, MQ provides a similar command |
1289 %set. There are a few differences in the way that it works. | |
1290 | |
1291 $B$9$G$K(Bquilt$B$KFk@w$s$G$$$k%f!<%6$N$?$a$K!$(BMQ$B$OF1MM$N%3%^%s%I%;%C%H$rMQ0U(B | |
1292 $B$7$F$$$k!%%3%^%s%I$N5sF0$K$O2?E@$+0c$$$,$"$k!%(B | |
26 | 1293 |
325 | 1294 %You will already have noticed that most quilt commands have MQ |
1295 %counterparts that simply begin with a ``\texttt{q}''. The exceptions | |
1296 %are quilt's \texttt{add} and \texttt{remove} commands, the | |
1297 %counterparts for which are the normal Mercurial \hgcmd{add} and | |
1298 %\hgcmd{remove} commands. There is no MQ equivalent of the quilt | |
1299 %\texttt{edit} command. | |
1300 | |
1301 $B$9$G$K$[$H$s$I$N(Bquilt$B%3%^%s%I$K$O!$BP1~$9$k(B``\texttt{q}''$B$G;O$^$k(BMQ$B%3%^%s(B | |
1302 $B%I$,$"$k$3$H$K5$$E$$$F$$$k$3$H$H;W$&!%Nc30$O!$(Bquilt$B$N(B\texttt{add}$B%3%^%s%I(B | |
1303 $B$H(B\texttt{remove}$B%3%^%s%I$G!$$3$l$i$K$O$=$l$>$lDL>o$N(BMercurial$B%3%^%s%I$N(B | |
1304 \hgcmd{add}$B$H(B\hgcmd{remove}$B$,BP1~$9$k!%$^$?!$(Bquilt$B$N(B\texttt{edit}$B%3%^%s%I(B | |
1305 $B$KBP1~$9$k(BMQ$B%3%^%s%I$O$J$$!%(B | |
1306 | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1307 |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1308 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
1309 %%% mode: yatex |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1310 %%% TeX-master: "00book" |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1311 %%% End: |