Mercurial > hgbook
annotate ja/mq-collab.tex @ 353:89a903605c74
more mq-collab.tex
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Tue, 19 Aug 2008 19:32:28 +0900 |
parents | f3fa98815193 |
children | 4991d84ba9d6 |
rev | line source |
---|---|
349 | 1 %\chapter{Advanced uses of Mercurial Queues} |
2 \chapter{Mercurial Queues$B$N9bEY$J;H$$J}(B} | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
107
diff
changeset
|
3 \label{chap:mq-collab} |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
349 | 5 %While it's easy to pick up straightforward uses of Mercurial Queues, |
6 %use of a little discipline and some of MQ's less frequently used | |
7 %capabilities makes it possible to work in complicated development | |
8 %environments. | |
9 | |
10 Mercurial Queues$B$NC1=c$J;H$$J}$r<h$j>e$2$?0lJ}!$>/!9$NE}@)$H(BMQ$B$N$"$^$jMQ(B | |
11 $B$$$i$l$J$$5!G=$rMQ$$$k$3$H$GJ#;($J3+H/4D6-$G$N:n6H$,2DG=$H$J$k!%(B | |
12 | |
13 %In this chapter, I will use as an example a technique I have used to | |
14 %manage the development of an Infiniband device driver for the Linux | |
15 %kernel. The driver in question is large (at least as drivers go), | |
16 %with 25,000 lines of code spread across 35 source files. It is | |
17 %maintained by a small team of developers. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
18 |
349 | 19 $B$3$N>O$G$O!$(BLinux$B%+!<%M%kMQ(BInfiniband$B%G%P%$%9%I%i%$%P$N3+H/$r4IM}$9$k$N$K(B |
20 $BMQ$$$?%F%/%K%C%/$rNc$H$7$FMQ$$$k!%$3$N%I%i%$%P$O!J%I%i%$%P$H$7$F$O!KBg5,(B | |
21 $BLO$G!$(B35$B$N%=!<%9%U%!%$%k$K$o$?$k(B25000$B9T$+$i$J$k!%$3$N%=!<%9$O>.5,LO$J3+H/(B | |
22 $B<T$N%A!<%`$K$h$C$F$$;~4IM}$5$l$F$$$k!%(B | |
23 | |
24 %While much of the material in this chapter is specific to Linux, the | |
25 %same principles apply to any code base for which you're not the | |
26 %primary owner, and upon which you need to do a lot of development. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
27 |
349 | 28 $B$3$N>O$G$NAG:`$O(BLinux$B$KFC2=$7$F$$$k$,!$F1$886B'$O$$$+$J$k%3!<%I%Y!<%9$KBP(B |
29 $B$7$F$bE,MQ2DG=$G!$<+J,<+?H$G=jM-$7$F$$$J$$$,!$B?$/$N3+H/$r9T$&I,MW$N$"$k(B | |
30 $B%3!<%I$J$I$K$bE,MQ$G$-$k!%(B | |
31 | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
32 |
349 | 33 %\section{The problem of many targets} |
34 \section{$B%?!<%2%C%H$,J#?t$"$k$H$$$&LdBj(B} | |
35 | |
36 %The Linux kernel changes rapidly, and has never been internally | |
37 %stable; developers frequently make drastic changes between releases. | |
38 %This means that a version of the driver that works well with a | |
39 %particular released version of the kernel will not even \emph{compile} | |
40 %correctly against, typically, any other version. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
41 |
349 | 42 Linux$B%+!<%M%k$O5^B.$KJQ2=$7!$$=$NFbIt$O7h$7$F0lDj$G$O$J$$!%3+H/<T$?$A$OIQ(B |
43 $BHK$K%j%j!<%94V$G7`E*$JJQ99$r9T$&!%$3$N$?$a!$FCDj$N%j%j!<%9%P!<%8%g%s$GNI(B | |
44 $B$/F0$$$?%I%i%$%P$,!$Nc$($PJL$N%P!<%8%g%s$G$O@5$7$/%3%s%Q%$%k$9$k$3$H$9$i(B | |
45 $B$G$-$J$/$J$k$H$$$&$3$H$r0UL#$9$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
46 |
349 | 47 %To maintain a driver, we have to keep a number of distinct versions of |
48 %Linux in mind. | |
49 | |
50 $B%I%i%$%P$r0];}$9$k$?$a$K!$3+H/<T$O$$$/$D$b$NJL$N%P!<%8%g%s$N(BLinux$B$rA[Dj(B | |
51 $B$7$J$1$l$P$J$i$J$$!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
52 \begin{itemize} |
349 | 53 %\item One target is the main Linux kernel development tree. |
54 | |
55 % Maintenance of the code is in this case partly shared by other | |
56 % developers in the kernel community, who make ``drive-by'' | |
57 % modifications to the driver as they develop and refine kernel | |
58 % subsystems. | |
59 \item $B0l$D$N%?!<%2%C%H$O(BLinux$B%+!<%M%k$N3+H/%D%j!<$G$"$k!%$3$N>l9g!$%3!<%I(B | |
60 $B$N0];}4IM}$O%+!<%M%k%3%_%e%K%F%#$NB>$N3+H/<T!J$3$l$O%+!<%M%k$N%5%V(B | |
61 $B%7%9%F%`$r2~NI$9$k$?$a$K%I%i%$%P$r(B``$BDI$$N)$F$k(B''$BJQ99$r9T$&3+H/<T$G(B | |
62 $B$"$k!K$HItJ,E*$K6&M-$5$l$F$$$k!%(B | |
63 %\item We also maintain a number of ``backports'' to older versions of | |
64 % the Linux kernel, to support the needs of customers who are running | |
65 % older Linux distributions that do not incorporate our drivers. (To | |
66 % \emph{backport} a piece of code is to modify it to work in an older | |
67 % version of its target environment than the version it was developed | |
68 % for.) | |
69 \item $B3+H/<T$O2f!9$N%I%i%$%P$,AH$_9~$^$l$F$$$J$$8E$$(BLinux$B%G%#%9%H%j%S%e!<(B | |
70 $B%7%g%s$r;H$C$F$$$k8\5R$r%5%]!<%H$9$k$?$a$K!$8E$$%P!<%8%g%s$N(BLinux$B%+!<(B | |
71 $B%M%k$X$N(B``$B%P%C%/%]!<%H(B''$B$rJz$($F$$$k!%%3!<%I$N0lIt$r(B\emph{$B%P%C%/%]!<(B | |
72 $B%H(B}$B$9$k$3$H$O!$%I%i%$%P$,3+H/$5$l$?%P!<%8%g%s$h$j$b8E$$%P!<%8%g%s(B | |
73 $B$N4D6-$GF0$/$h$&$K$9$k$3$H$r0UL#$9$k!%(B | |
74 %\item Finally, we make software releases on a schedule that is | |
75 % necessarily not aligned with those used by Linux distributors and | |
76 % kernel developers, so that we can deliver new features to customers | |
77 % without forcing them to upgrade their entire kernels or | |
78 % distributions. | |
79 \item $B:G=*E*$K(BLinux$B%G%#%9%H%j%S%e!<%?$d%+!<%M%k3+H/<T$rBT$?$;$k$3$H$J$/%9(B | |
80 $B%1%8%e!<%kDL$j$K%=%U%H%&%'%"$r%j%j!<%9$9$k$3$H$,I,MW$G$"$j!$$3$l$K$h$C$F(B | |
81 $B8\5R$K%+!<%M%k$d%G%#%9%H%j%S%e!<%7%g%sA4BN$r%"%C%W%0%l!<%I$5$;$k$3$H$J$/(B | |
82 $B?75!G=$r8\5R$KFO$1$i$l$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
83 \end{itemize} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
84 |
349 | 85 %\subsection{Tempting approaches that don't work well} |
86 \subsection{$B$d$C$F$7$^$$$,$A$J4V0c$C$?J}K!(B} | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
87 |
350 | 88 %There are two ``standard'' ways to maintain a piece of software that |
89 %has to target many different environments. | |
90 | |
91 $B$5$^$6$^$J4D6-$r%?!<%2%C%H$K$7$?%=%U%H%&%'%"$r4IM}$9$k(B2$B$D$NI8=`E*$JJ}K!(B | |
92 $B$,$"$k!%(B | |
93 | |
94 %The first is to maintain a number of branches, each intended for a | |
95 %single target. The trouble with this approach is that you must | |
96 %maintain iron discipline in the flow of changes between repositories. | |
97 %A new feature or bug fix must start life in a ``pristine'' repository, | |
98 %then percolate out to every backport repository. Backport changes are | |
99 %more limited in the branches they should propagate to; a backport | |
100 %change that is applied to a branch where it doesn't belong will | |
101 %probably stop the driver from compiling. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
102 |
350 | 103 $BBh(B1$B$NJ}K!$O!$C10l$N%?!<%2%C%H8~$1$NJ#?t$N%V%i%s%A$r0];}$9$k$3$H$G$"$k!%$3(B |
104 $B$NJ}K!$NLdBjE@$O!$%j%]%8%H%j4V$G$NJQ99$NN.$l$K$D$$$F873J$J5,N'$r0];}$7$J(B | |
105 $B$1$l$P$J$i$J$$$3$H$G$"$k!%?75!G=$d%P%0=$@5$O!$$-$l$$$J>uBV$N%j%]%8%H%j$G(B | |
106 $B3+;O$7!$%P%C%/%]!<%H%j%]%8%H%j$K?;F)$9$kI,MW$,$"$k!%%P%C%/%]!<%HJQ99$OGH(B | |
107 $B5Z$9$Y$-%V%i%s%AFb$K8BDj$5$l$F$$$J$1$l$P$J$i$J$$!%I,MW$N$J$$%V%i%s%A$X$N(B | |
108 $B%P%C%/%]!<%H$NGH5Z$O$*$=$i$/%I%i%$%P$r%3%s%Q%$%kITG=$K$7$F$7$^$&$@$m$&!%(B | |
109 | |
110 %The second is to maintain a single source tree filled with conditional | |
111 %statements that turn chunks of code on or off depending on the | |
112 %intended target. Because these ``ifdefs'' are not allowed in the | |
113 %Linux kernel tree, a manual or automatic process must be followed to | |
114 %strip them out and yield a clean tree. A code base maintained in this | |
115 %fashion rapidly becomes a rat's nest of conditional blocks that are | |
116 %difficult to understand and maintain. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
117 |
350 | 118 $BBh(B2$B$NJ}K!$O!$%A%c%s%/$d%3!<%I$r!$L\E*$H$9$k%?!<%2%C%HKh$K(Bon/off$B$9$k>r7oJ8(B |
119 $B$rDI2C$7$?C10l$N%=!<%9%D%j!<$r0];}$9$kJ}K!$G$"$k!%$3$l$i$N(B``ifdef''$B$O(B | |
120 linux$B%+!<%M%k%D%j!<$G$O5v$5$l$F$$$J$$$?$a!$<jF0$^$?$O<+F0$G$3$l$i$N%3!<%I(B | |
121 $B$r=|5n$7!$%/%j!<%s$J%D%j!<$r:n$k%W%m%;%9$,I,MW$K$J$k!%$3$N$h$&$J$d$jJ}$G(B | |
122 $B4IM}$5$l$?%3!<%I%Y!<%9$O$9$0$K>r7o@a$NAc7"$H2=$7!"M}2r$d4IM}$NK8$2$H$J$k!#(B | |
123 | |
124 %Neither of these approaches is well suited to a situation where you | |
125 %don't ``own'' the canonical copy of a source tree. In the case of a | |
126 | |
127 %Linux driver that is distributed with the standard kernel, Linus's | |
128 %tree contains the copy of the code that will be treated by the world | |
129 %as canonical. The upstream version of ``my'' driver can be modified | |
130 %by people I don't know, without me even finding out about it until | |
131 %after the changes show up in Linus's tree. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
132 |
350 | 133 $B$"$J$?$,@5<0$J%=!<%9%D%j!<$r=jM-$7$F$$$k$N$G$J$1$l$P!"$3$l$i$N$d$jJ}$N$I(B |
134 $B$A$i$b$=$0$o$J$$$@$m$&!#I8=`$N(Blinux$B%+!<%M%k$KF1:-$5$l$F$$$k%I%i%$%P$N>l(B | |
135 $B9g!$(BLinus$B$N%D%j!<$O@$3&Cf$G@5<0$J%3!<%I$H$7$F07$o$l$k%3%T!<$r4^$s$G$$$k!%(B | |
136 ``$B;d(B''$B$N%I%i%$%P$N>eN.HG$O!$CN$i$J$$?M$K$h$C$FJQ99$5$lF@$k$7!$<+J,$NJQ99(B | |
137 $B$,(BLinus$B$N%D%j!<$KF~$C$?$"$H$G$5$($bJQ99$5$lF@$k!%(B | |
138 | |
139 %These approaches have the added weakness of making it difficult to | |
140 %generate well-formed patches to submit upstream. | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
141 |
350 | 142 $B$3$l$i$N%"%W%m!<%A$O!$$&$^$/=q$+$l$?%Q%C%A$r>eN.$XDs=P$9$k$3$H$r:$Fq$K$7(B |
143 $B$F$7$^$&!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
144 |
350 | 145 %In principle, Mercurial Queues seems like a good candidate to manage a |
146 %development scenario such as the above. While this is indeed the | |
147 %case, MQ contains a few added features that make the job more | |
148 %pleasant. | |
149 | |
150 Mercurial Queues$B$O>e5-$N$h$&$J3+H/%7%J%j%*$r4IM}$9$k$h$$8uJd$N0l$D$G$"$k(B | |
151 $B$H$$$($k!%$3$N$h$&$J>l9g$N$?$a$K(BMQ$B$K$O:n6H$r$h$j2wE,$K$9$k$$$/$D$+$N5!G=(B | |
152 $B$,$"$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 |
349 | 154 %\section{Conditionally applying patches with guards} |
155 \section{$B%,!<%I$r;H$C$?%Q%C%A$N>r7oE*$JE,MQ(B} | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
156 |
350 | 157 %Perhaps the best way to maintain sanity with so many targets is to be |
158 %able to choose specific patches to apply for a given situation. MQ | |
159 %provides a feature called ``guards'' (which originates with quilt's | |
160 %\texttt{guards} command) that does just this. To start off, let's | |
161 %create a simple repository for experimenting in. | |
162 %\interaction{mq.guards.init} | |
163 %This gives us a tiny repository that contains two patches that don't | |
164 %have any dependencies on each other, because they touch different files. | |
165 | |
351
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
166 $BB?$/$N%?!<%2%C%H$rBP>]$H$7$J$,$i@5>o$KJ]$D0lHVNI$$J}J}$O!$>u67$K1~$8$FFC(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
167 $BDj$N%Q%C%A$rA*$Y$k$h$&$K$9$k$3$H$G$"$k!%(BMQ$B$O$3$NL\E*$N$?$a$K(Bquilt$B$N(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
168 \texttt{guards}$B%3%^%s%I$KN`;w$7$?(B``guards''$B$H8F$P$l$k5!G=$rDs6!$7$F$$$k!%(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
169 $B3+;O$KEv$?$C$F!$<B83$N$?$a$KC1=c$J%j%]%8%H%j$r:n@.$9$k!%(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
170 \interaction{mq.guards.init} |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
171 $B>.$5$J%j%]%8%H%j$r:n$j!$JL!9$N%U%!%$%k$rA`:n$9$k8_$$$K0MB8@-$N$J$$(B2$B$D$N%Q%C(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
172 $B%A$rCV$/!%(B |
350 | 173 |
351
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
174 %The idea behind conditional application is that you can ``tag'' a |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
175 %patch with a \emph{guard}, which is simply a text string of your |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
176 %choosing, then tell MQ to select specific guards to use when applying |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
177 %patches. MQ will then either apply, or skip over, a guarded patch, |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
178 %depending on the guards that you have selected. |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
179 |
351
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
180 $B>r7oIU$-$G%Q%C%A%Q%C%A$NE,MQ$r%3%s%H%m!<%k$9$kJ}K!$NGX8e$K$"$k$N(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
181 $B$O!$(B\emph{guard}$B$K$h$C$F%Q%C%A$KIU$1$i$l$?(B``$B%?%0(B''$B$G$"$k!%%?%0$O<+M3$KA*(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
182 $B$s$@C1=c$J%F%-%9%H$G!$(BMQ$B$,%Q%C%A$rE,MQ$9$k$H$-$KMQ$$$kFCDj$N%,!<%I$r;XDj(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
183 $B$9$k!%(BMQ$B$O%,!<%I%Q%C%A$NE,MQ$^$?$O%9%-%C%W$r!$;XDj$5$l$?%,!<%I$K$h$C$F7h(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
184 $BDj$9$k!%(B |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
185 |
351
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
186 %A patch can have an arbitrary number of guards; |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
187 %each one is \emph{positive} (``apply this patch if this guard is |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
188 %selected'') or \emph{negative} (``skip this patch if this guard is |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
189 %selected''). A patch with no guards is always applied. |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
190 |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
191 $B%Q%C%A$OG$0U$N?t$N%,!<%I$r;}$D$3$H$,$G$-$k!%3F!9$N%,!<%I(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
192 $B$O!$(B\emph{positive}$B!J$3$N%,!<%I$,A*Br$5$l$F$$$k$H$-$K$3$N%Q%C%A$rE,MQ!K$^(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
193 $B$?$O(B\emph{negative}$B!J$3$N%,!<%I$,A*Br$5$l$F$$$k$H$-$K$3$N%Q%C%A$r%9%-%C(B |
f3fa98815193
a bit more mq-collab.tex
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
350
diff
changeset
|
194 $B%W!K$G$"$k!%%,!<%I$r;}$?$J$$%Q%C%A$O>o$KE,MQ$5$l$k!%(B |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
195 |
349 | 196 %\section{Controlling the guards on a patch} |
197 \section{$B%Q%C%AFb$N%,!<%I$rA`:n$9$k(B} | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
198 |
353 | 199 %The \hgxcmd{mq}{qguard} command lets you determine which guards should |
200 %apply to a patch, or display the guards that are already in effect. | |
201 %Without any arguments, it displays the guards on the current topmost | |
202 %patch. | |
203 %\interaction{mq.guards.qguard} | |
204 %To set a positive guard on a patch, prefix the name of the guard with | |
205 %a ``\texttt{+}''. | |
206 %\interaction{mq.guards.qguard.pos} | |
207 %To set a negative guard on a patch, prefix the name of the guard with | |
208 %a ``\texttt{-}''. | |
209 %\interaction{mq.guards.qguard.neg} | |
210 | |
211 \hgxcmd{mq}{qguard}$B%3%^%s%I$G$I$N%,!<%I$,%Q%C%A$KE,MQ$5$l$k$+$r;XDj$7$?(B | |
212 $B$j!$$9$G$KM-8z$K$J$C$F$$$k%,!<%I$rI=<($5$;$k$3$H$,$G$-$k!%0z?t$J$7$G$3$N(B | |
213 $B%3%^%s%I$r;H$&$H!$8=:_$N:G>e0L$N%Q%C%A$N%,!<%I$rI=<($9$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
214 \interaction{mq.guards.qguard} |
353 | 215 $B%Q%C%A$K%]%8%F%#%V%,!<%I$r@_Dj$9$k$K$O!$%,!<%IL>$NA0$K(B``\texttt{+}''$B$r$D(B |
216 $B$1$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
217 \interaction{mq.guards.qguard.pos} |
353 | 218 $B%Q%C%A$K%M%,%F%#%V%,!<%I$r@_Dj$9$k$K$O!$%,!<%IL>$NA0$K(B``\texttt{-}''$B$r$D(B |
219 $B$1$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
220 \interaction{mq.guards.qguard.neg} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
221 |
353 | 222 %\begin{note} |
223 % The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it | |
224 % doesn't \emph{modify} them. What this means is that if you run | |
225 % \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on | |
226 % the same patch, the \emph{only} guard that will be set on it | |
227 % afterwards is \texttt{+c}. | |
228 %\end{note} | |
229 | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
230 \begin{note} |
353 | 231 \hgxcmd{mq}{qguard} $B%3%^%s%I$O%Q%C%A$K%,!<%I$r(B\emph{$B@_Dj$9$k(B}$B$,%Q%C%A<+(B |
232 $BBN$r(B\emph{$BJQ99$7$J$$(B}$BE@$KCm0U$5$l$?$$!%%Q%C%A$KBP$7$F(B | |
233 \hgcmdargs{qguard}{+a +b}$B$r<B9T$7!$F1$8%Q%C%A$K(B\hgcmdargs{qguard}{+c}$B$r(B | |
234 $B<B9T$9$k$H!$$3$N%Q%C%A$X$N%,!<%I$O(B\texttt{+c}$B$N$_$K$J$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
235 \end{note} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
236 |
353 | 237 %Mercurial stores guards in the \sfilename{series} file; the form in |
238 %which they are stored is easy both to understand and to edit by hand. | |
239 %(In other words, you don't have to use the \hgxcmd{mq}{qguard} command if | |
240 %you don't want to; it's okay to simply edit the \sfilename{series} | |
241 %file.) | |
242 %\interaction{mq.guards.series} | |
243 | |
244 Mercurial$B$O%,!<%I$r(B\sfilename{series}$B%U%!%$%k$KJ]B8$9$k!%=q<0$OM}2r$7$d(B | |
245 $B$9$/!$<j$GJQ99$9$k$N$b4JC1$G$"$k!%!J$D$^$j!$(B\hgxcmd{mq}{qguard}$B%3%^%s%I(B | |
246 $B$r;H$$$?$/$J$1$l$P!$D>@\(B\sfilename{series}$B$rJT=8$7$F:Q$^$9$3$H$b$G$-$k!%!K(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
247 \interaction{mq.guards.series} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
248 |
349 | 249 %\section{Selecting the guards to use} |
250 \section{$B;HMQ$9$k%,!<%I$rA*$V(B} | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
251 |
353 | 252 %The \hgxcmd{mq}{qselect} command determines which guards are active at a |
253 %given time. The effect of this is to determine which patches MQ will | |
254 %apply the next time you run \hgxcmd{mq}{qpush}. It has no other effect; in | |
255 %particular, it doesn't do anything to patches that are already | |
256 %applied. | |
257 | |
258 \hgxcmd{mq}{qselect}$B%3%^%s%I$r<B9T$9$k$3$H$G!$$=$N;~E@$G%"%/%F%#%V$J%,!<(B | |
259 $B%I$r;XDj$9$k$3$H$,$G$-$k!%$3$N%3%^%s%I$K$h$C$F!$<!$K(B\hgxcmd{mq}{qpush}$B$,(B | |
260 $B<B9T$5$l$?$H$-$K$I$N%Q%C%A$,(BMQ$B$K$h$C$FE,MQ$5$l$k$+$,;XDj$5$l$k!%$=$l0J30(B | |
261 $B$N8z2L$O$J$/!$FC$K$9$G$KE,MQ$5$l$F$$$k%Q%C%A$KBP$7$F$O2?$b9T$o$J$$!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
262 |
353 | 263 %With no arguments, the \hgxcmd{mq}{qselect} command lists the guards |
264 %currently in effect, one per line of output. Each argument is treated | |
265 %as the name of a guard to apply. | |
266 %\interaction{mq.guards.qselect.foo} | |
267 %In case you're interested, the currently selected guards are stored in | |
268 %the \sfilename{guards} file. | |
269 %\interaction{mq.guards.qselect.cat} | |
270 %We can see the effect the selected guards have when we run | |
271 %\hgxcmd{mq}{qpush}. | |
272 %\interaction{mq.guards.qselect.qpush} | |
273 | |
274 $B0z?t$J$7$G(B\hgxcmd{mq}{qselect}$B%3%^%s%I$r<B9T$9$k$H!$8=:_M-8z$J%,!<%I$N%j(B | |
275 $B%9%H$r(B1$B9T$K(B1$B$D$:$DI=<($9$k!%3F!9$N0z?t$OE,MQ$5$l$k%,!<%I$NL>A0$H$7$F2r<a(B | |
276 $B$5$l$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
277 \interaction{mq.guards.qselect.foo} |
353 | 278 $B8=:_A*Br$5$l$F$$$k%,!<%I$K6=L#$,$"$k>l9g!$$3$l$O(B\sfilename{guards}$B%U%!%$(B |
279 $B%k$KJ]B8$5$l$F$$$k!%(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
280 \interaction{mq.guards.qselect.cat} |
353 | 281 $BA*Br$5$l$?%,!<%I$N8z2L$O(B\hgxcmd{mq}{qpush}$B$N<B9T;~$K8+$k$3$H$,$G$-$k!%(B |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
282 \interaction{mq.guards.qselect.qpush} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
283 |
353 | 284 %A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' |
285 %character. The name of a guard must not contain white space, but most | |
286 %othter characters are acceptable. If you try to use a guard with an | |
287 %invalid name, MQ will complain: | |
288 %\interaction{mq.guards.qselect.error} | |
289 %Changing the selected guards changes the patches that are applied. | |
290 %\interaction{mq.guards.qselect.quux} | |
291 %You can see in the example below that negative guards take precedence | |
292 %over positive guards. | |
293 %\interaction{mq.guards.qselect.foobar} | |
294 | |
295 $B%,!<%I$r(B``\texttt{+}''$B$d(B``\texttt{-}''$B$NJ8;z$G;O$a$k$3$H$O$G$-$J$$!%%,!<(B | |
296 $B%IL>$O6uGr$r4^$s$G$O$J$i$J$$$,!$$=$NB>$NKX$s$I$NJ8;z$r4^$`$3$H$,$G$-$k!%(B | |
297 $B$b$7;HMQIT2D$NJ8;z$r4^$`>l9g$O!"(BMQ$B$,7Y9p$rI=<($9$k!#(B | |
298 \interaction{mq.guards.qselect.error} | |
299 $BA*Br$5$l$?%,!<%I$rJQ99$9$k$3$H$O!"E,MQ$5$l$k%Q%C%A$NJQ99$r0UL#$9$k!#(B | |
300 \interaction{mq.guards.qselect.quux} | |
301 $B2<$NNc$G%M%,%F%#%V%,!<%I$,%]%8%F%#%V%,!<%I$h$j$bM%@hEY$r;}$D$3$H$,$o$+$k!#(B | |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
302 \interaction{mq.guards.qselect.foobar} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
303 |
349 | 304 %\section{MQ's rules for applying patches} |
305 \section{MQ$B$N%Q%C%AE,MQ%k!<%k(B} | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
306 |
353 | 307 %The rules that MQ uses when deciding whether to apply a patch |
308 %are as follows. | |
309 MQ$B$,E,MQ$9$k%Q%C%A$r7hDj$9$k5,B'$O2<5-$N$H$*$j$G$"$k!#(B | |
310 %\begin{itemize} | |
311 %\item A patch that has no guards is always applied. | |
312 %\item If the patch has any negative guard that matches any currently | |
313 % selected guard, the patch is skipped. | |
314 %\item If the patch has any positive guard that matches any currently | |
315 % selected guard, the patch is applied. | |
316 %\item If the patch has positive or negative guards, but none matches | |
317 % any currently selected guard, the patch is skipped. | |
318 %\end{itemize} | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
319 \begin{itemize} |
353 | 320 \item $B%,!<%I$N$J$$%Q%C%A$O>o$KE,MQ$9$k(B |
321 \item $B%Q%C%A$K8=:_A*Br$5$l$F$$$k%,!<%I$K%^%C%A$9$k%M%,%F%#%V%,!<%I$,$"$l(B | |
322 $B$P!"$=$N%Q%C%A$r%9%-%C%W$9$k(B | |
323 \item $B%Q%C%A$K8=:_A*Br$5$l$F$$$k%,!<%I$K%^%C%A$9$k%]%8%F%#%V%,!<%I$,$"$l(B | |
324 $B$P!"$=$N%Q%C%A$rE,MQ$9$k(B | |
325 \item $B%Q%C%A$,%]%8%F%#%V!&%M%,%F%#%V$$$:$l$+$N%,!<%I$r;}$D$,!"8=:_A*Br$5(B | |
326 $B$l$F$$$k%,!<%I$H%^%C%A$9$k$b$N$,$J$1$l$P!"$=$N%Q%C%A$r%9%-%C%W$9$k(B | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
327 \end{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
328 |
349 | 329 %\section{Trimming the work environment} |
330 \section{$B:n6H4D6-$r=L>.$9$k(B} | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
331 |
353 | 332 %In working on the device driver I mentioned earlier, I don't apply the |
333 %patches to a normal Linux kernel tree. Instead, I use a repository | |
334 %that contains only a snapshot of the source files and headers that are | |
335 %relevant to Infiniband development. This repository is~1\% the size | |
336 %of a kernel repository, so it's easier to work with. | |
337 | |
338 $B0JA08@5Z$7$?%G%P%$%9%I%i%$%P$G$N:n6H$G$O!"(BLinux$B%+!<%M%k%D%j!<$K%Q%C%A$rE,(B | |
339 $BMQ$7$F$$$J$+$C$?!%$=$NBe$o$j!$(BInfiniband$B%I%i%$%P$N3+H/$K4XO"$7$?%=!<%9$H(B | |
340 $B%X%C%@%U%!%$%k$@$1$r;}$D%j%]%8%H%j$rMQ$$$?!%$3$N%j%]%8%H%j$O%+!<%M%k%j%](B | |
341 $B%8%H%j$N(B~1\%$B$[$I$N%5%$%:$G!$:n6H$,MF0W$G$"$k!%(B | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
342 |
353 | 343 %I then choose a ``base'' version on top of which the patches are |
344 %applied. This is a snapshot of the Linux kernel tree as of a revision | |
345 %of my choosing. When I take the snapshot, I record the changeset ID | |
346 %from the kernel repository in the commit message. Since the snapshot | |
347 %preserves the ``shape'' and content of the relevant parts of the | |
348 %kernel tree, I can apply my patches on top of either my tiny | |
349 %repository or a normal kernel tree. | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
350 |
353 | 351 $B$3$3$G%Q%C%A$rE,MQ$9$k$?$a$N(B``base''$B%P!<%8%g%s$rA*$V!%$3$l$OG$0U$KA*$s$@(B |
352 Linux$B%+!<%M%k%D%j!<$N%9%J%C%W%7%g%C%H$G!$:n@.$9$k:]!$%+!<%M%k%j%]%8%H%j$N(B | |
353 $B%A%'%s%8%;%C%H(BID$B$r%3%_%C%H%a%C%;!<%8$K5-O?$7$F$*$/!%%9%J%C%W%7%g%C%H$O%+!<(B | |
354 $B%M%k%D%j!<$N4XO"$9$kItJ,$N867?$rJ]$C$F$$$k$?$a!$<+J,$N%Q%C%A$r3+H/MQ$N8D(B | |
355 $BJL$N%j%]%8%H%j$KE,MQ$9$k$N$HF1MM$KDL>o$N%+!<%M%k%D%j!<$KE,MQ$9$k$3$H$,$G(B | |
356 $B$-$k!%(B | |
357 | |
358 %Normally, the base tree atop which the patches apply should be a | |
359 %snapshot of a very recent upstream tree. This best facilitates the | |
360 %development of patches that can easily be submitted upstream with few | |
361 %or no modifications. | |
362 | |
363 $BDL>o!$%Q%C%A$,E,MQ$5$l$k%Y!<%9%D%j!<$O>eN.$N%D%j!<$N$4$/:G6a$N%9%J%C%W(B | |
364 $B%7%g%C%H$G$"$k$Y$-$@!%$3$&$9$k$3$H$G!$3+H/$7$?%Q%C%A$r=$@5$9$k$3$H$J$/!$(B | |
365 $B$"$k$$$O$4$/6O$+$J=$@5$N$_$G!$>eN.$XDs=P$9$k$3$H$,2DG=$K$J$k!%(B | |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
366 |
349 | 367 %\section{Dividing up the \sfilename{series} file} |
353 | 368 \section{\sfilename{series}$B%U%!%$%k$rJ,3d$9$k(B} |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
369 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
370 I categorise the patches in the \sfilename{series} file into a number |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
371 of logical groups. Each section of like patches begins with a block |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
372 of comments that describes the purpose of the patches that follow. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
373 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
374 The sequence of patch groups that I maintain follows. The ordering of |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
375 these groups is important; I'll describe why after I introduce the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
376 groups. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
377 \begin{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
378 \item The ``accepted'' group. Patches that the development team has |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
379 submitted to the maintainer of the Infiniband subsystem, and which |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
380 he has accepted, but which are not present in the snapshot that the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
381 tiny repository is based on. These are ``read only'' patches, |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
382 present only to transform the tree into a similar state as it is in |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
383 the upstream maintainer's repository. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
384 \item The ``rework'' group. Patches that I have submitted, but that |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
385 the upstream maintainer has requested modifications to before he |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
386 will accept them. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
387 \item The ``pending'' group. Patches that I have not yet submitted to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
388 the upstream maintainer, but which we have finished working on. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
389 These will be ``read only'' for a while. If the upstream maintainer |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
390 accepts them upon submission, I'll move them to the end of the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
391 ``accepted'' group. If he requests that I modify any, I'll move |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
392 them to the beginning of the ``rework'' group. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
393 \item The ``in progress'' group. Patches that are actively being |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
394 developed, and should not be submitted anywhere yet. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
395 \item The ``backport'' group. Patches that adapt the source tree to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
396 older versions of the kernel tree. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
397 \item The ``do not ship'' group. Patches that for some reason should |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
398 never be submitted upstream. For example, one such patch might |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
399 change embedded driver identification strings to make it easier to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
400 distinguish, in the field, between an out-of-tree version of the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
401 driver and a version shipped by a distribution vendor. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
402 \end{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
403 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
404 Now to return to the reasons for ordering groups of patches in this |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
405 way. We would like the lowest patches in the stack to be as stable as |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
406 possible, so that we will not need to rework higher patches due to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
407 changes in context. Putting patches that will never be changed first |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
408 in the \sfilename{series} file serves this purpose. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
409 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
410 We would also like the patches that we know we'll need to modify to be |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
411 applied on top of a source tree that resembles the upstream tree as |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
412 closely as possible. This is why we keep accepted patches around for |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
413 a while. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
414 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
415 The ``backport'' and ``do not ship'' patches float at the end of the |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
416 \sfilename{series} file. The backport patches must be applied on top |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
417 of all other patches, and the ``do not ship'' patches might as well |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
418 stay out of harm's way. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
419 |
349 | 420 %\section{Maintaining the patch series} |
421 \section{$B%Q%C%A%7%j!<%:$r4IM}$9$k(B} | |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
422 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
423 In my work, I use a number of guards to control which patches are to |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
424 be applied. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
425 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
426 \begin{itemize} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
427 \item ``Accepted'' patches are guarded with \texttt{accepted}. I |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
428 enable this guard most of the time. When I'm applying the patches |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
429 on top of a tree where the patches are already present, I can turn |
271 | 430 this patch off, and the patches that follow it will apply cleanly. |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
431 \item Patches that are ``finished'', but not yet submitted, have no |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
432 guards. If I'm applying the patch stack to a copy of the upstream |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
433 tree, I don't need to enable any guards in order to get a reasonably |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
434 safe source tree. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
435 \item Those patches that need reworking before being resubmitted are |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
436 guarded with \texttt{rework}. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
437 \item For those patches that are still under development, I use |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
438 \texttt{devel}. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
439 \item A backport patch may have several guards, one for each version |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
440 of the kernel to which it applies. For example, a patch that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
441 backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
442 \end{itemize} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
443 This variety of guards gives me considerable flexibility in |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
444 qdetermining what kind of source tree I want to end up with. For most |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
445 situations, the selection of appropriate guards is automated during |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
446 the build process, but I can manually tune the guards to use for less |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
447 common circumstances. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
448 |
349 | 449 %\subsection{The art of writing backport patches} |
450 \subsection{$B%P%C%/%]!<%H%Q%C%A$r=q$/5;=Q(B} | |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
451 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
452 Using MQ, writing a backport patch is a simple process. All such a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
453 patch has to do is modify a piece of code that uses a kernel feature |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
454 not present in the older version of the kernel, so that the driver |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
455 continues to work correctly under that older version. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
456 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
457 A useful goal when writing a good backport patch is to make your code |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
458 look as if it was written for the older version of the kernel you're |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
459 targeting. The less obtrusive the patch, the easier it will be to |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
460 understand and maintain. If you're writing a collection of backport |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
461 patches to avoid the ``rat's nest'' effect of lots of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
462 \texttt{\#ifdef}s (hunks of source code that are only used |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
463 conditionally) in your code, don't introduce version-dependent |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
464 \texttt{\#ifdef}s into the patches. Instead, write several patches, |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
465 each of which makes unconditional changes, and control their |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
466 application using guards. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
467 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
468 There are two reasons to divide backport patches into a distinct |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
469 group, away from the ``regular'' patches whose effects they modify. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
470 The first is that intermingling the two makes it more difficult to use |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
471 a tool like the \hgext{patchbomb} extension to automate the process of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
472 submitting the patches to an upstream maintainer. The second is that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
473 a backport patch could perturb the context in which a subsequent |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
474 regular patch is applied, making it impossible to apply the regular |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
475 patch cleanly \emph{without} the earlier backport patch already being |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
476 applied. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
477 |
349 | 478 %\section{Useful tips for developing with MQ} |
479 \section{MQ$B$K$h$k3+H/$N(Btips} | |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
480 |
349 | 481 %\subsection{Organising patches in directories} |
482 \subsection{$B%G%#%l%/%H%jFb$G%Q%C%A$r4IM}$9$k(B} | |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
483 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
484 If you're working on a substantial project with MQ, it's not difficult |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
485 to accumulate a large number of patches. For example, I have one |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
486 patch repository that contains over 250 patches. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
487 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
488 If you can group these patches into separate logical categories, you |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
489 can if you like store them in different directories; MQ has no |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
490 problems with patch names that contain path separators. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
491 |
349 | 492 %\subsection{Viewing the history of a patch} |
493 \subsection{$B%Q%C%A$N%R%9%H%j$r8+$k(B} | |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
494 \label{mq-collab:tips:interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
495 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
496 If you're developing a set of patches over a long time, it's a good |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
497 idea to maintain them in a repository, as discussed in |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
498 section~\ref{sec:mq:repo}. If you do so, you'll quickly discover that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
499 using the \hgcmd{diff} command to look at the history of changes to a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
500 patch is unworkable. This is in part because you're looking at the |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
501 second derivative of the real code (a diff of a diff), but also |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
502 because MQ adds noise to the process by modifying time stamps and |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
503 directory names when it updates a patch. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
504 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
505 However, you can use the \hgext{extdiff} extension, which is bundled |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
506 with Mercurial, to turn a diff of two versions of a patch into |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
507 something readable. To do this, you will need a third-party package |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
508 called \package{patchutils}~\cite{web:patchutils}. This provides a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
509 command named \command{interdiff}, which shows the differences between |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
510 two diffs as a diff. Used on two versions of the same diff, it |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
511 generates a diff that represents the diff from the first to the second |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
512 version. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
513 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
514 You can enable the \hgext{extdiff} extension in the usual way, by |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
515 adding a line to the \rcsection{extensions} section of your \hgrc. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
516 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
517 [extensions] |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
518 extdiff = |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
519 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
520 The \command{interdiff} command expects to be passed the names of two |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
521 files, but the \hgext{extdiff} extension passes the program it runs a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
522 pair of directories, each of which can contain an arbitrary number of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
523 files. We thus need a small program that will run \command{interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
524 on each pair of files in these two directories. This program is |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
525 available as \sfilename{hg-interdiff} in the \dirname{examples} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
526 directory of the source code repository that accompanies this book. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
527 \excode{hg-interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
528 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
529 With the \sfilename{hg-interdiff} program in your shell's search path, |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
530 you can run it as follows, from inside an MQ patch directory: |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
531 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
532 hg extdiff -p hg-interdiff -r A:B my-change.patch |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
533 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
534 Since you'll probably want to use this long-winded command a lot, you |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
535 can get \hgext{hgext} to make it available as a normal Mercurial |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
536 command, again by editing your \hgrc. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
537 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
538 [extdiff] |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
539 cmd.interdiff = hg-interdiff |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
540 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
541 This directs \hgext{hgext} to make an \texttt{interdiff} command |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
542 available, so you can now shorten the previous invocation of |
238 | 543 \hgxcmd{extdiff}{extdiff} to something a little more wieldy. |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
544 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
545 hg interdiff -r A:B my-change.patch |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
546 \end{codesample2} |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
547 |
107
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
548 \begin{note} |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
549 The \command{interdiff} command works well only if the underlying |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
550 files against which versions of a patch are generated remain the |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
551 same. If you create a patch, modify the underlying files, and then |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
552 regenerate the patch, \command{interdiff} may not produce useful |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
553 output. |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
554 \end{note} |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
555 |
240
4119e57679f7
Twiddle wording trivially.
Bryan O'Sullivan <bos@serpentine.com>
parents:
239
diff
changeset
|
556 The \hgext{extdiff} extension is useful for more than merely improving |
239
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
557 the presentation of MQ~patches. To read more about it, go to |
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
558 section~\ref{sec:hgext:extdiff}. |
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
559 |
349 | 560 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
561 %%% mode: yatex |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
562 %%% TeX-master: "00book" |
349 | 563 %%% End: |