annotate ja/mq-collab.tex @ 835:8a3041e6f3cb

reflect comments by Hiroshi Someya.

%\chapter{Advanced uses of Mercurial Queues}
\chapter{Mercurial Queues$B$N9bEY$J;H$$J}(B}
\label{chap:mq-collab}

%While it's easy to pick up straightforward uses of Mercurial Queues,
%use of a little discipline and some of MQ's less frequently used
%capabilities makes it possible to work in complicated development
%environments.

Mercurial Queues$B$NC1=c$J;H$$J}$r<h$j>e$2$?0lJ}!$>/!9$NE}@)$H(BMQ$B$N$"$^$jMQ(B
$B$$$i$l$J$$5!G=$rMQ$$$k$3$H$GJ#;($J3+H/4D6-$G$N:n6H$,2DG=$H$J$k!%(B

%In this chapter, I will use as an example a technique I have used to
%manage the development of an Infiniband device driver for the Linux
%kernel.  The driver in question is large (at least as drivers go),
%with 25,000 lines of code spread across 35 source files.  It is
%maintained by a small team of developers.

$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
$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
$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
$B<T$N%A!<%`$K$h$C$F0];}4IM}$5$l$F$$$k!%(B

%While much of the material in this chapter is specific to Linux, the
%same principles apply to any code base for which you're not the
%primary owner, and upon which you need to do a lot of development.

$B$3$N>O$G$NAG:`$O(BLinux$B$KFC2=$7$F$$$k$,!$F1$886B'$O$$$+$J$k%3!<%I%Y!<%9$KBP(B
$B$7$F$bE,MQ2DG=$G!$<+J,<+?H$G=jM-$7$F$$$J$$$,!$B?$/$N3+H/$r9T$&I,MW$N$"$k(B
$B%3!<%I$J$I$K$bE,MQ$G$-$k!%(B


%\section{The problem of many targets}
\section{$B%?!<%2%C%H$,J#?t$"$k$H$$$&LdBj(B}

%The Linux kernel changes rapidly, and has never been internally
%stable; developers frequently make drastic changes between releases.
%This means that a version of the driver that works well with a
%particular released version of the kernel will not even \emph{compile}
%correctly against, typically, any other version.

Linux$B%+!<%M%k$O5^B.$KJQ2=$7!$$=$NFbIt$O7h$7$F0lDj$G$O$J$$!%3+H/<T$?$A$OIQ(B
$BHK$K%j%j!<%94V$G7`E*$JJQ99$r9T$&!%$3$N$?$a!$FCDj$N%j%j!<%9%P!<%8%g%s$GNI(B
$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
$B$G$-$J$/$J$k$H$$$&$3$H$r0UL#$9$k!%(B

%To maintain a driver, we have to keep a number of distinct versions of
%Linux in mind.

$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
$B$7$J$1$l$P$J$i$J$$!%(B
\begin{itemize}
%\item One target is the main Linux kernel development tree.

%  Maintenance of the code is in this case partly shared by other
%  developers in the kernel community, who make ``drive-by''
%  modifications to the driver as they develop and refine kernel
%  subsystems.
\item $B0l$D$N%?!<%2%C%H$O(BLinux$B%+!<%M%k$N3+H/%D%j!<$G$"$k!%$3$N>l9g!$%3!<%I(B
      $B$N0];}4IM}$O%+!<%M%k%3%_%e%K%F%#$NB>$N3+H/<T!J$3$l$O%+!<%M%k$N%5%V(B
      $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
      $B$"$k!K$HItJ,E*$K6&M-$5$l$F$$$k!%(B
%\item We also maintain a number of ``backports'' to older versions of
%  the Linux kernel, to support the needs of customers who are running
%  older Linux distributions that do not incorporate our drivers.  (To
%  \emph{backport} a piece of code is to modify it to work in an older
%  version of its target environment than the version it was developed
%  for.)
\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
      $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
      $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
      $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
      $B$N4D6-$GF0$/$h$&$K$9$k$3$H$r0UL#$9$k!%(B
%\item Finally, we make software releases on a schedule that is
%  necessarily not aligned with those used by Linux distributors and
%  kernel developers, so that we can deliver new features to customers
%  without forcing them to upgrade their entire kernels or
%  distributions.
\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
$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
$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
$B?75!G=$r8\5R$KFO$1$i$l$k!%(B
\end{itemize}

%\subsection{Tempting approaches that don't work well}
\subsection{$B$d$C$F$7$^$$$,$A$J4V0c$C$?J}K!(B}

%There are two ``standard'' ways to maintain a piece of software that
%has to target many different environments.

$B$5$^$6$^$J4D6-$r%?!<%2%C%H$K$7$?%=%U%H%&%'%"$r4IM}$9$k(B2$B$D$NI8=`E*$JJ}K!(B
$B$,$"$k!%(B

%The first is to maintain a number of branches, each intended for a
%single target.  The trouble with this approach is that you must
%maintain iron discipline in the flow of changes between repositories.
%A new feature or bug fix must start life in a ``pristine'' repository,
%then percolate out to every backport repository.  Backport changes are
%more limited in the branches they should propagate to; a backport
%change that is applied to a branch where it doesn't belong will
%probably stop the driver from compiling.

$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
$B$NJ}K!$NLdBjE@$O!$%j%]%8%H%j4V$G$NJQ99$NN.$l$K$D$$$F873J$J5,N'$r0];}$7$J(B
$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
$B3+;O$7!$%P%C%/%]!<%H%j%]%8%H%j$K?;F)$9$kI,MW$,$"$k!%%P%C%/%]!<%HJQ99$OGH(B
$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
$B%P%C%/%]!<%H$NGH5Z$O$*$=$i$/%I%i%$%P$r%3%s%Q%$%kITG=$K$7$F$7$^$&$@$m$&!%(B

%The second is to maintain a single source tree filled with conditional
%statements that turn chunks of code on or off depending on the
%intended target.  Because these ``ifdefs'' are not allowed in the
%Linux kernel tree, a manual or automatic process must be followed to
%strip them out and yield a clean tree.  A code base maintained in this
%fashion rapidly becomes a rat's nest of conditional blocks that are
%difficult to understand and maintain.

$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
$B$rDI2C$7$?C10l$N%=!<%9%D%j!<$r0];}$9$kJ}K!$G$"$k!%$3$l$i$N(B``ifdef''$B$O(B
linux$B%+!<%M%k%D%j!<$G$O5v$5$l$F$$$J$$$?$a!$<jF0$^$?$O<+F0$G$3$l$i$N%3!<%I(B
$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
$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

%Neither of these approaches is well suited to a situation where you
%don't ``own'' the canonical copy of a source tree.  In the case of a

%Linux driver that is distributed with the standard kernel, Linus's
%tree contains the copy of the code that will be treated by the world
%as canonical.  The upstream version of ``my'' driver can be modified
%by people I don't know, without me even finding out about it until
%after the changes show up in Linus's tree.

$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
$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
$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
``$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
$B$,(BLinus$B$N%D%j!<$KF~$C$?$"$H$G$5$($bJQ99$5$lF@$k!%(B

%These approaches have the added weakness of making it difficult to
%generate well-formed patches to submit upstream.

$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
$B$F$7$^$&!%(B

%In principle, Mercurial Queues seems like a good candidate to manage a
%development scenario such as the above.  While this is indeed the
%case, MQ contains a few added features that make the job more
%pleasant.

Mercurial Queues$B$O>e5-$N$h$&$J3+H/%7%J%j%*$r4IM}$9$k$h$$8uJd$N0l$D$G$"$k(B
$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
$B$,$"$k!%(B

%\section{Conditionally applying patches with guards}
\section{$B%,!<%I$r;H$C$?%Q%C%A$N>r7oE*$JE,MQ(B}

%Perhaps the best way to maintain sanity with so many targets is to be
%able to choose specific patches to apply for a given situation.  MQ
%provides a feature called ``guards'' (which originates with quilt's
%\texttt{guards} command) that does just this.  To start off, let's
%create a simple repository for experimenting in.
%\interaction{mq.guards.init}
%This gives us a tiny repository that contains two patches that don't
%have any dependencies on each other, because they touch different files.

$BB?$/$N%?!<%2%C%H$rBP>]$H$7$J$,$i@5>o$KJ]$D0lHVNI$$J}K!$O!$>u67$K1~$8$FFC(B
$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
\texttt{guards}$B%3%^%s%I$KN`;w$7$?(B``guards''$B$H8F$P$l$k5!G=$rDs6!$7$F$$$k!%(B
$B3+;O$KEv$?$C$F!$<B83$N$?$a$KC1=c$J%j%]%8%H%j$r:n@.$9$k!%(B
\interaction{mq.guards.init}$B>.$5$J%j%]%8%H%j$r:n$j!$JL!9$N%U%!%$%k$rA`:n(B
$B$9$k8_$$$K0MB8@-$N$J$$(B2$B$D$N%Q%C%A$rCV$/!%(B

%The idea behind conditional application is that you can ``tag'' a
%patch with a \emph{guard}, which is simply a text string of your
%choosing, then tell MQ to select specific guards to use when applying
%patches.  MQ will then either apply, or skip over, a guarded patch,
%depending on the guards that you have selected.

$B>r7oIU$-$G%Q%C%A$NE,MQ$r@)8f$9$kJ}K!$G$O!$(B\emph{guard}$B$K$h$C$F%Q%C%A$KIU(B
$B$1$i$l$?(B``$B%?%0(B''$B$r3hMQ$9$k!%%?%0$O<+M3$KA*$s$@C1=c$J%F%-%9%H$G!$(BMQ$B$,%Q%C(B
$B%A$rE,MQ$9$k$H$-$KMQ$$$kFCDj$N%,!<%I$r;XDj$9$k!%(BMQ$B$O%,!<%I%Q%C%A$NE,MQ$^(B
$B$?$O%9%-%C%W$r!$;XDj$5$l$?%,!<%I$K$h$C$F7hDj$9$k!%(B

%A patch can have an arbitrary number of guards;
%each one is \emph{positive} (``apply this patch if this guard is
%selected'') or \emph{negative} (``skip this patch if this guard is
%selected'').  A patch with no guards is always applied.

$B%Q%C%A$OG$0U$N?t$N%,!<%I$r;}$D$3$H$,$G$-$k!%3F!9$N%,!<%I(B
$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
$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
$B%W!K$G$"$k!%%,!<%I$r;}$?$J$$%Q%C%A$O>o$KE,MQ$5$l$k!%(B

%\section{Controlling the guards on a patch}
\section{$B%Q%C%AFb$N%,!<%I$rA`:n$9$k(B}

%The \hgxcmd{mq}{qguard} command lets you determine which guards should
%apply to a patch, or display the guards that are already in effect.
%Without any arguments, it displays the guards on the current topmost
%patch.
%\interaction{mq.guards.qguard}
%To set a positive guard on a patch, prefix the name of the guard with
%a ``\texttt{+}''.
%\interaction{mq.guards.qguard.pos}
%To set a negative guard on a patch, prefix the name of the guard with
%a ``\texttt{-}''.
%\interaction{mq.guards.qguard.neg}

\hgxcmd{mq}{qguard}$B%3%^%s%I$G$I$N%,!<%I$,%Q%C%A$KE,MQ$5$l$k$+$r;XDj$7$?(B
$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
$B%3%^%s%I$r;H$&$H!$8=:_$N:G>e0L$N%Q%C%A$N%,!<%I$rI=<($9$k!%(B
\interaction{mq.guards.qguard}
$B%Q%C%A$K%]%8%F%#%V%,!<%I$r@_Dj$9$k$K$O!$%,!<%IL>$NA0$K(B``\texttt{+}''$B$r$D(B
$B$1$k!%(B
\interaction{mq.guards.qguard.pos}
$B%Q%C%A$K%M%,%F%#%V%,!<%I$r@_Dj$9$k$K$O!$%,!<%IL>$NA0$K(B``\texttt{-}''$B$r$D(B
$B$1$k!%(B
\interaction{mq.guards.qguard.neg}

%\begin{note}
%  The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it
%  doesn't \emph{modify} them.  What this means is that if you run
%  \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on
%  the same patch, the \emph{only} guard that will be set on it
%  afterwards is \texttt{+c}.
%\end{note}

\begin{note}
 \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
 $BBN$r(B\emph{$BJQ99$7$J$$(B}$BE@$KCm0U$5$l$?$$!%%Q%C%A$KBP$7$F(B
 \hgcmdargs{qguard}{+a +b}$B$r<B9T$7!$F1$8%Q%C%A$K(B\hgcmdargs{qguard}{+c}$B$r(B
 $B<B9T$9$k$H!$$3$N%Q%C%A$X$N%,!<%I$O(B\texttt{+c}$B$N$_$K$J$k!%(B
\end{note}

%Mercurial stores guards in the \sfilename{series} file; the form in
%which they are stored is easy both to understand and to edit by hand.
%(In other words, you don't have to use the \hgxcmd{mq}{qguard} command if
%you don't want to; it's okay to simply edit the \sfilename{series}
%file.)
%\interaction{mq.guards.series}

Mercurial$B$O%,!<%I$r(B\sfilename{series}$B%U%!%$%k$KJ]B8$9$k!%=q<0$OM}2r$7$d(B
$B$9$/!$<j$GJQ99$9$k$N$b4JC1$G$"$k!%!J$D$^$j!$(B\hgxcmd{mq}{qguard}$B%3%^%s%I(B
$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
\interaction{mq.guards.series}

%\section{Selecting the guards to use}
\section{$B;HMQ$9$k%,!<%I$rA*$V(B}

%The \hgxcmd{mq}{qselect} command determines which guards are active at a
%given time.  The effect of this is to determine which patches MQ will
%apply the next time you run \hgxcmd{mq}{qpush}.  It has no other effect; in
%particular, it doesn't do anything to patches that are already
%applied.

\hgxcmd{mq}{qselect}$B%3%^%s%I$r<B9T$9$k$3$H$G!$$=$N;~E@$G%"%/%F%#%V$J%,!<(B
$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
$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
$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

%With no arguments, the \hgxcmd{mq}{qselect} command lists the guards
%currently in effect, one per line of output.  Each argument is treated
%as the name of a guard to apply.
%\interaction{mq.guards.qselect.foo}
%In case you're interested, the currently selected guards are stored in
%the \sfilename{guards} file.
%\interaction{mq.guards.qselect.cat}
%We can see the effect the selected guards have when we run
%\hgxcmd{mq}{qpush}.
%\interaction{mq.guards.qselect.qpush}

$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
$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
$B$5$l$k!%(B
\interaction{mq.guards.qselect.foo}
$B8=:_A*Br$5$l$F$$$k%,!<%I$K6=L#$,$"$k>l9g!$$3$l$O(B\sfilename{guards}$B%U%!%$(B
$B%k$KJ]B8$5$l$F$$$k!%(B
\interaction{mq.guards.qselect.cat}
$BA*Br$5$l$?%,!<%I$N8z2L$O(B\hgxcmd{mq}{qpush}$B$N<B9T;~$K8+$k$3$H$,$G$-$k!%(B
\interaction{mq.guards.qselect.qpush}

%A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}''
%character.  The name of a guard must not contain white space, but most
%othter characters are acceptable.  If you try to use a guard with an
%invalid name, MQ will complain:
%\interaction{mq.guards.qselect.error}
%Changing the selected guards changes the patches that are applied.
%\interaction{mq.guards.qselect.quux}
%You can see in the example below that negative guards take precedence
%over positive guards.
%\interaction{mq.guards.qselect.foobar}

$B%,!<%I$r(B``\texttt{+}''$B$d(B``\texttt{-}''$B$NJ8;z$G;O$a$k$3$H$O$G$-$J$$!%%,!<(B
$B%IL>$O6uGr$r4^$s$G$O$J$i$J$$$,!$$=$NB>$NKX$s$I$NJ8;z$r4^$`$3$H$,$G$-$k!%(B
$B$b$7;HMQIT2D$NJ8;z$r4^$`>l9g$O!"(BMQ$B$,7Y9p$rI=<($9$k!#(B
\interaction{mq.guards.qselect.error}
$BA*Br$5$l$?%,!<%I$rJQ99$9$k$3$H$O!"E,MQ$5$l$k%Q%C%A$NJQ99$r0UL#$9$k!#(B
\interaction{mq.guards.qselect.quux}
$B2<$NNc$G%M%,%F%#%V%,!<%I$,%]%8%F%#%V%,!<%I$h$j$bM%@hEY$r;}$D$3$H$,$o$+$k!#(B
\interaction{mq.guards.qselect.foobar}

%\section{MQ's rules for applying patches}
\section{MQ$B$N%Q%C%AE,MQ%k!<%k(B}

%The rules that MQ uses when deciding whether to apply a patch
%are as follows.
MQ$B$,E,MQ$9$k%Q%C%A$r7hDj$9$k5,B'$O2<5-$N$H$*$j$G$"$k!#(B
%\begin{itemize}
%\item A patch that has no guards is always applied.
%\item If the patch has any negative guard that matches any currently
%  selected guard, the patch is skipped.
%\item If the patch has any positive guard that matches any currently
%  selected guard, the patch is applied.
%\item If the patch has positive or negative guards, but none matches
%  any currently selected guard, the patch is skipped.
%\end{itemize}
\begin{itemize}
\item $B%,!<%I$N$J$$%Q%C%A$O>o$KE,MQ$9$k(B
\item $B%Q%C%A$K8=:_A*Br$5$l$F$$$k%,!<%I$K%^%C%A$9$k%M%,%F%#%V%,!<%I$,$"$l(B
      $B$P!"$=$N%Q%C%A$r%9%-%C%W$9$k(B
\item $B%Q%C%A$K8=:_A*Br$5$l$F$$$k%,!<%I$K%^%C%A$9$k%]%8%F%#%V%,!<%I$,$"$l(B
      $B$P!"$=$N%Q%C%A$rE,MQ$9$k(B
\item $B%Q%C%A$,%]%8%F%#%V!&%M%,%F%#%V$$$:$l$+$N%,!<%I$r;}$D$,!"8=:_A*Br$5(B
      $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
\end{itemize}

%\section{Trimming the work environment}
\section{$B:n6H4D6-$r=L>.$9$k(B}

%In working on the device driver I mentioned earlier, I don't apply the
%patches to a normal Linux kernel tree.  Instead, I use a repository
%that contains only a snapshot of the source files and headers that are
%relevant to Infiniband development.  This repository is~1\% the size
%of a kernel repository, so it's easier to work with.

$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
$BMQ$7$F$$$J$+$C$?!%$=$NBe$o$j!$(BInfiniband$B%I%i%$%P$N3+H/$K4XO"$7$?%=!<%9$H(B
$B%X%C%@%U%!%$%k$@$1$r;}$D%j%]%8%H%j$rMQ$$$?!%$3$N%j%]%8%H%j$O%+!<%M%k%j%](B
$B%8%H%j$N(B~1\%$B$[$I$N%5%$%:$G!$:n6H$,MF0W$G$"$k!%(B

%I then choose a ``base'' version on top of which the patches are
%applied.  This is a snapshot of the Linux kernel tree as of a revision
%of my choosing.  When I take the snapshot, I record the changeset ID
%from the kernel repository in the commit message.  Since the snapshot
%preserves the ``shape'' and content of the relevant parts of the
%kernel tree, I can apply my patches on top of either my tiny
%repository or a normal kernel tree.

$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
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
$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
$B%M%k%D%j!<$N4XO"$9$kItJ,$N867?$rJ]$C$F$$$k$?$a!$<+J,$N%Q%C%A$r3+H/MQ$N8D(B
$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
$B$-$k!%(B

%Normally, the base tree atop which the patches apply should be a
%snapshot of a very recent upstream tree.  This best facilitates the
%development of patches that can easily be submitted upstream with few
%or no modifications.

$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
$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
$B$"$k$$$O$4$/6O$+$J=$@5$N$_$G!$>eN.$XDs=P$9$k$3$H$,2DG=$K$J$k!%(B

%\section{Dividing up the \sfilename{series} file}
\section{\sfilename{series}$B%U%!%$%k$rJ,3d$9$k(B}

%I categorise the patches in the \sfilename{series} file into a number
%of logical groups.  Each section of like patches begins with a block
%of comments that describes the purpose of the patches that follow.

$BI.<T$O(B\sfilename{series}$B%U%!%$%k$N%Q%C%A$r$$$/$D$+$NO@M}E*$J%0%k!<%W$K%+(B
$B%F%4%i%$%:$7$F$$$k!%%Q%C%A$N$=$l$>$l$N%;%/%7%g%s$O$"$H$KB3$/%Q%C%A$,2?$G(B
$B$"$k$+@bL@$9$k%3%a%s%H%V%m%C%/$G;O$^$C$F$$$k!%(B

%The sequence of patch groups that I maintain follows.  The ordering of
%these groups is important; I'll describe why after I introduce the
%groups.
$B$=$N8e$K%a%s%F%J%s%9$7$F$$$k%Q%C%A%0%k!<%W$,O"$J$k!%%0%k!<%W$r@0M}$9$k$3(B
$B$H$O=EMW$G$"$k!%$^$:%0%k!<%W$K$D$$$F@bL@$7$?8e!$$3$NM}M3$K?($l$k!%(B

\begin{itemize}
%\item The ``accepted'' group.  Patches that the development team has
%  submitted to the maintainer of the Infiniband subsystem, and which
%  he has accepted, but which are not present in the snapshot that the
%  tiny repository is based on.  These are ``read only'' patches,
%  present only to transform the tree into a similar state as it is in
%  the upstream maintainer's repository.
\item ``accepted''$B%0%k!<%W!%3+H/%A!<%`$,(BInfiniband$B%5%V%7%9%F%`$N%a%s%F%J(B
      $B$KDs=P$7!$<uM}$5$l$?$,!$>.%j%]%8%H%j$N%Y!<%9$H$J$C$F$$$k%9%J%C%W(B
      $B%7%g%C%H$K$O$^$@<h$j9~$^$l$F$$$J$$$b$N!%$3$l$i$O%D%j!<$r>eN.%a%s%F(B
      $B%J$N%j%]%8%H%j$HF1MM$N>uBV$K$9$k$?$a$KB8:_$9$k(B``$BFI$_=P$7$N$_(B''$B$N%Q%C(B
      $B%A$G$"$k!%(B
%\item The ``rework'' group.  Patches that I have submitted, but that
%  the upstream maintainer has requested modifications to before he
%  will accept them.
\item ``rework''$B%0%k!<%W!%Ds=P$7$?$,>eN.%a%s%F%J$,<uM}$K@h$@$C$FJQ99$rMW(B
      $B5a$7$?$b$N!%(B
%\item The ``pending'' group.  Patches that I have not yet submitted to
%  the upstream maintainer, but which we have finished working on.
%  These will be ``read only'' for a while.  If the upstream maintainer
%  accepts them upon submission, I'll move them to the end of the
%  ``accepted'' group.  If he requests that I modify any, I'll move
%  them to the beginning of the ``rework'' group.
\item ``pending''$B%0%k!<%W!%>eN.%a%s%F%J$K$O$^$@Ds=P$7$F$$$J$$$,!$<j85$G(B
      $B$N:n6H$O40N;$7$?$b$N!%$3$l$i$O$7$P$i$/$N4V(B``read only''$B$K$J$C$F$*(B
      $B$j!$>eN.$N%a%s%F%J$XDs=P$7$F<uM}$5$l$?;~$O(B``accepted''$B%0%k!<%W$X0\(B
      $BF0$5$l$k!%%a%s%F%J$,JQ99$rMW5a$7$?>l9g$O(B``rework''$B%0%k!<%W$X0\F0$5(B
      $B$l$k!%(B
%\item The ``in progress'' group.  Patches that are actively being
%  developed, and should not be submitted anywhere yet.
\item ``in progress''$B%0%k!<%W!%$3$N%0%k!<%W$K$O!$%"%/%F%#%V$K3+H/$5(B
      $B$l$F$*$j!$$^$@$I$3$X$bDs=P$5$l$k$Y$-$G$O$J$$%Q%C%A$,4^$^$l$k!%(B
%\item The ``backport'' group.  Patches that adapt the source tree to
%  older versions of the kernel tree.
\item ``backport''$B%0%k!<%W!%%=!<%9$r8E$$%P!<%8%g%s$N%+!<%M%k%D%j!<$XE,9g(B
      $B$5$;$k%Q%C%A$+$i$J$k!%(B
%\item The ``do not ship'' group.  Patches that for some reason should
%  never be submitted upstream.  For example, one such patch might
%  change embedded driver identification strings to make it easier to
%  distinguish, in the field, between an out-of-tree version of the
%  driver and a version shipped by a distribution vendor.
\item ``do not ship''$B%0%k!<%W!%$J$s$i$+$NM}M3$K$h$C$F7h$7$F>eN.$XDs=P$5$l(B
      $B$k$Y$-$G$J$$%Q%C%A$+$i$J$k!%Nc$($P!$%D%j!<30$N%I%i%$%P$H%Y%s%@$K$h$C(B
      $B$FG[I[$5$l$F$$$k%I%i%$%P$r<1JL$7$d$9$/$9$k$?$a$K%I%i%$%P$N<1JLJ8;z(B
      $BNs$rJQ99$9$k$h$&$J%Q%C%A$,3:Ev$9$k!%(B
\end{itemize}

%Now to return to the reasons for ordering groups of patches in this
%way.  We would like the lowest patches in the stack to be as stable as
%possible, so that we will not need to rework higher patches due to
%changes in context.  Putting patches that will never be changed first
%in the \sfilename{series} file serves this purpose.

$B%Q%C%A$r$3$N$h$&$JJ}K!$G@0M}$9$kM}M3$N@bL@$XLa$m$&!%0lHL$K!$%Q%C%A%9%?%C(B
$B%/$NDl$K$"$k%Q%C%A$O$J$k$Y$/0BDj$G$"$C$FM_$7$$$H;W$&$b$N$@!%$=$&$G$"$l(B
$B$P!$%Q%C%A$N%3%s%F%-%9%H$GJQ99$K$h$k:F:n6H$r$;$:$K:Q$`!%(B
\sfilename{series}$B$K:G=i$KDI2C$9$k%Q%C%A$O7h$7$FJQ99$5$l$J$$$b$N$K$9$k$H(B
$B$h$$!%(B

%We would also like the patches that we know we'll need to modify to be
%applied on top of a source tree that resembles the upstream tree as
%closely as possible.  This is why we keep accepted patches around for
%a while.

$B$^$?!$E,MQ$N$?$a$KJQ99$7$J$1$l$P$J$i$J$$%Q%C%A$K$D$$$F$O!$$G$-$k$@$1>eN.(B
$B$N%D%j!<$K6a$$%=!<%9%D%j!<$KE,MQ$G$-$k$h$&$K$J$C$F$$$FM_$7$$$H9M$($k!%$3(B
$B$l$,<uM}$5$l$?%Q%C%A$r$7$P$i$/$N4VJ];}$7$F$$$kM}M3$G$"$k!%(B

%The ``backport'' and ``do not ship'' patches float at the end of the
%\sfilename{series} file.  The backport patches must be applied on top
%of all other patches, and the ``do not ship'' patches might as well
%stay out of harm's way.

``backport''$B$H(B``do not ship''$B%Q%C%A$O(B\sfilename{series}$B%U%!%$%k$NKvHx$KCV(B
$B$+$l$k!%(B``backport''$B%Q%C%A$OB>$N%Q%C%A$9$Y$F$N>e$+$iE,MQ$5$l$J$1$l$P$J$i(B
$B$J$$$7!$(B``do not ship''$B%Q%C%A$O0BA4$J$H$3$m$KCV$+$l$F$$$J$1$l$P$J$i$J$$!%(B

%\section{Maintaining the patch series}
\section{$B%Q%C%A%7%j!<%:$r4IM}$9$k(B}

%In my work, I use a number of guards to control which patches are to
%be applied.

$B$3$N:n6H$G$O!$$I$N%Q%C%A$,E,MQ$5$l$k$+@)8f$9$k$?$a$K$$$/$D$+$N%,!<%I$rMQ(B
$B$$$F$$$k!%(B

\begin{itemize}
%\item ``Accepted'' patches are guarded with \texttt{accepted}.  I
%  enable this guard most of the time.  When I'm applying the patches
%  on top of a tree where the patches are already present, I can turn
%  this patch off, and the patches that follow it will apply cleanly.

\item ``Accepted''$B%Q%C%A$O(B\texttt{accepted}$B$K$h$C$F%,!<%I$5$l$F$$$k!%I.<T(B
$B$O$3$N%,!<%I$r$[$\$$$D$bM-8z$K$7$F$$$k!%$9$G$K%Q%C%A$,B8:_$7$F$$$k%D%j!<(B
$B$N>e$K?7$?$J%Q%C%A$rE,MQ$9$k;~$O!$$3$N%Q%C%A$r%*%U$K$7$F!$8eB3$N%Q%C%A$,(B
$B%/%j!<%s$KE,MQ$5$l$k$h$&$K$9$k$3$H$,$G$-$k!%(B

%\item Patches that are ``finished'', but not yet submitted, have no
%  guards.  If I'm applying the patch stack to a copy of the upstream
%  tree, I don't need to enable any guards in order to get a reasonably
%  safe source tree.

\item $B40@.$5$l$F$$$k$b$N$N!$$^$@Ds=P$5$l$F$$$J$$%Q%C%A$O%,!<%I$r;}$?$J(B
      $B$$!%$3$N%Q%C%A%9%?%C%/$r>eN.%D%j!<$N%3%T!<$KE,MQ$9$k>l9g!$%,!<%I$r(B
      $BA4$/;H$o$:$K==J,0BA4$J%=!<%9%D%j!<$rF@$k$3$H$,$G$-$k!%(B

%\item Those patches that need reworking before being resubmitted are
%  guarded with \texttt{rework}.

 \item $B:FDs=P$N$?$a$K:n6H$,I,MW$J%Q%C%A$K$O(B\texttt{rework}$B%,!<%I$rMQ$$$k!%(B

%\item For those patches that are still under development, I use
%  \texttt{devel}.

 \item $B3+H/Cf$N%Q%C%A$K$O(B\texttt{devel}$B%,!<%I$rMQ$$$F$$$k!%(B

%\item A backport patch may have several guards, one for each version
%  of the kernel to which it applies.  For example, a patch that
%  backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard.

 \item $B%P%C%/%]!<%H%Q%C%A$O%Q%C%A$,E,MQ$5$l$k%+!<%M%k$N%P!<%8%g%s$=$l$>$l(B
      $B$KBP$7$F%,!<%I$r;}$D$3$H$,$"$k!%Nc$($P!$$"$k%3!<%I$r(B~2.6.9$B$K%P%C%/(B
      $B%]!<%H$9$k%Q%C%A$O(B~\texttt{2.6.9}$B$H$$$&%,!<%I$r;}$D!%(B
\end{itemize}
%This variety of guards gives me considerable flexibility in
%determining what kind of source tree I want to end up with.  For most
%situations, the selection of appropriate guards is automated during
%the build process, but I can manually tune the guards to use for less
%common circumstances.

$BB?$/$N%,!<%I$rMQ$$$k$3$H$K$h$C$F!$=@Fp$K:n6HBP>]$N%=!<%9%D%j!<$rA*$V$3$H(B
$B$,$G$-$k!%%S%k%I=hM}Cf$K@5$7$$%,!<%I$r<+F0E*$KA*Br$G$-$k$3$H$,$[$H$s$I$@(B
$B$,!$FC<l$J>u67$N$?$a$K<j$GA*$V$3$H$b2DG=$G$"$k!%(B

%\subsection{The art of writing backport patches}
\subsection{$B%P%C%/%]!<%H%Q%C%A$r=q$/5;=Q(B}

%Using MQ, writing a backport patch is a simple process.  All such a
%patch has to do is modify a piece of code that uses a kernel feature
%not present in the older version of the kernel, so that the driver
%continues to work correctly under that older version.

MQ$B$r;H$C$F%P%C%/%]!<%H%Q%C%A$r=q$/$N$OC1=c$J:n6H$G$"$k!%$=$N$h$&$J%Q%C%A(B
$B$,$9$Y$-$3$H$O!$8E$$%P!<%8%g%s$N%+!<%M%k$KHw$o$C$F$$$J$$5!G=$r;H$&%3!<%I(B
$B$rJQ99$7!$8E$$%P!<%8%g%s$N%+!<%M%k$G$b@5$7$/5!G=$7B3$1$k$h$&$K$9$k$3$H$@(B
$B$1$G$"$k!%(B

%A useful goal when writing a good backport patch is to make your code
%look as if it was written for the older version of the kernel you're
%targeting.  The less obtrusive the patch, the easier it will be to
%understand and maintain.  If you're writing a collection of backport
%patches to avoid the ``rat's nest'' effect of lots of
%\texttt{\#ifdef}s (hunks of source code that are only used
%conditionally) in your code, don't introduce version-dependent
%\texttt{\#ifdef}s into the patches.  Instead, write several patches,
%each of which makes unconditional changes, and control their
%application using guards.

$B$h$$%P%C%/%]!<%H%Q%C%A$H$O!$$=$N%Q%C%A$K$h$C$F$"$?$+$b%3!<%I$,%?!<%2%C%H(B
$B$N8E$$%P!<%8%g%s$N%+!<%M%k$K8~$1$F=q$+$l$?$h$&$J>uBV$K$J$k$b$N$G$"$k!%(B
$BL5M}$N$J$$%Q%C%A$OM}2r$7$d$9$/!$%a%s%F%J%s%9$bMF0W$G$"$k!%(B
$B%P%C%/%]!<%H%Q%C%A$r$$$/$D$b=q$$$F$$$k$J$i$P!$%3!<%IFb$NBgNL$N(B
\texttt{\#ifdef}$B$G>r7oE*%3%s%Q%$%k$5$l$k%3!<%I$K$h$k:.Mp$rHr$1$k$Y$-$G$"(B
$B$k!%$=$N$?$a$K%P!<%8%g%s$K0MB8$7$?(B\texttt{\#ifdef}$B$G$O$J$/!$%,!<%I$K$h$C(B
$B$F@)8f$5$l$k>r7o%3%s%Q%$%k$K$h$i$J$$JQ99$r2C$($k$Y$-$G$"$k!%(B

%There are two reasons to divide backport patches into a distinct
%group, away from the ``regular'' patches whose effects they modify.
%The first is that intermingling the two makes it more difficult to use
%a tool like the \hgext{patchbomb} extension to automate the process of
%submitting the patches to an upstream maintainer.  The second is that
%a backport patch could perturb the context in which a subsequent
%regular patch is applied, making it impossible to apply the regular
%patch cleanly \emph{without} the earlier backport patch already being
%applied.

$B%P%C%/%]!<%H%Q%C%A$rDL>o$NJQ99$r2C$($k%Q%C%A$HJL$N%0%k!<%W$KJ,3d$9$kM}M3(B
$B$,(B2$B$D$"$k!%Bh0l$NM}M3$O!$(B2$B$D$r:.$<9g$o$;$k$3$H$G!$>eN.$N%a%s%F%J$X%Q%C%A(B
$B$rDs=P$9$k$?$a$K(B\hgext{patchbomb}$B%(%/%9%F%s%7%g%s$N$h$&$J%D!<%k$r;H$&$N$,(B
$BFq$7$/$J$k$3$H$G$"$k!%BhFs$NM}M3$O!$%P%C%/%]!<%H%Q%C%A$O!$8eB3$NDL>o%Q%C(B
$B%A$NE,MQ$5$l$k%3%s%F%-%9%H$rMp$9$3$H$,$"$j!$$=$N$h$&$J>l9g!$DL>o%Q%C%A$O(B
$B%P%C%/%]!<%H%Q%C%A$J$7$K@5$7$/E,MQ$9$k$3$H$,IT2DG=$K$J$C$F$7$^$&!%(B

%\section{Useful tips for developing with MQ}
\section{MQ$B$K$h$k3+H/$N(Btips}

%\subsection{Organising patches in directories}
\subsection{$B%G%#%l%/%H%jFb$G%Q%C%A$r4IM}$9$k(B}

%If you're working on a substantial project with MQ, it's not difficult
%to accumulate a large number of patches.  For example, I have one
%patch repository that contains over 250 patches.

MQ$B$rMQ$$$FHf3SE*Bg5,LO$J%W%m%8%'%/%H$G:n6H$7$F$$$k>l9g!$BgNL$N%Q%C%A$,C_(B
$B@Q$9$k$3$H$,>/$J$/$J$$!%Nc$($PI.<T$N$H$3$m$K$O!$(B250$B0J>e$N%Q%C%A$r4^$`%Q%C(B
$B%A%j%]%8%H%j$,$"$k!%(B

%If you can group these patches into separate logical categories, you
%can if you like store them in different directories; MQ has no
%problems with patch names that contain path separators.

$B$b$7$3$l$i$N%Q%C%A$rO@M}E*$J%+%F%4%j$KJ,3d$9$k$3$H$,$G$-!$JL!9$N%G%#%l%/(B
$B%H%j$K<}MF$7$?$$$H9M$($k$J$i$P!$%Q%C%AL>$K%Q%9%;%Q%l!<%?$r4^$a$F$b(BMQ$B$OLd(B
$BBj$J$/<h$j07$&$3$H$,$G$-$k!%(B

%\subsection{Viewing the history of a patch}
\subsection{$B%Q%C%A$N%R%9%H%j$r8+$k(B}
\label{mq-collab:tips:interdiff}

%If you're developing a set of patches over a long time, it's a good
%idea to maintain them in a repository, as discussed in
%section~\ref{sec:mq:repo}.  If you do so, you'll quickly discover that
%using the \hgcmd{diff} command to look at the history of changes to a
%patch is unworkable.  This is in part because you're looking at the
%second derivative of the real code (a diff of a diff), but also
%because MQ adds noise to the process by modifying time stamps and
%directory names when it updates a patch.

$BD9$$4|4V$K$o$?$C$FB?$/$N%Q%C%A$r:n$C$F$-$?$N$J$i!$(B~\ref{sec:mq:repo}$B@a$G(B
$B5DO@$7$F$-$?$h$&$K$=$l$i$r%j%]%8%H%j$G4IM}$9$k$N$ONI$$9M$($G$"$k!%$=$&$7(B
$B$?>l9g!$$9$0$K(B\hgcmd{diff}$B%3%^%s%I$G$O%Q%C%A$N%R%9%H%j$r8+$k$3$H$K;H$($J(B
$B$$$3$H$K5$$E$/$@$m$&!%$3$l$O<B:]$N%3!<%I$NFs<!E*$JGI@8J*!J(Bdiff$B$N(Bdiff$B!K$r(B
$B8+$F$$$k$3$H$H!$(BMQ$B$,%Q%C%A$r99?7$9$k;~$K%?%$%`%9%?%s%W$H%G%#%l%/%H%jL>$r(B
$BJQ99$9$k$3$H$G!$%W%m%;%9$K%N%$%:$r2C$($F$$$k$?$a$G$G$"$k!%(B

%However, you can use the \hgext{extdiff} extension, which is bundled
%with Mercurial, to turn a diff of two versions of a patch into
%something readable.  To do this, you will need a third-party package
%called \package{patchutils}~\cite{web:patchutils}.  This provides a
%command named \command{interdiff}, which shows the differences between
%two diffs as a diff.  Used on two versions of the same diff, it
%generates a diff that represents the diff from the first to the second
%version.

$B$7$+$7(BMercurial$B$KF1:-$5$l$F$$$k(B\hgext{extdiff}$B%(%/%9%F%s%7%g%s$r;H$$!$(B2$B$D(B
$B$N%P!<%8%g%s$N%Q%C%A4V$G0UL#$N$"$k:9J,$r<h$k$3$H$,$G$-$k!%$3$N$?$a$K(B
\package{patchutils}~\cite{web:patchutils}$B$r;H$&I,MW$,$"$k!%$3$N%Q%C%1!<(B
$B%8$O(B2$B$D$N(Bdiff$B%U%!%$%k4V$N:9J,$r(Bdiff$B$H$7$FI=<($9$k(B\command{interdiff}$B$H$$(B
$B$&%3%^%s%I$rDs6!$7$F$$$k!%F1$8(Bdiff$B$N0[$J$k%P!<%8%g%s4V$G;HMQ$9$l$P!$A08e(B
$B$N(Bdiff$B$N4V$N(Bdiff$B$r@8@.$9$k!%(B

%You can enable the \hgext{extdiff} extension in the usual way, by
%adding a line to the \rcsection{extensions} section of your \hgrc.
\hgrc $B%U%!%$%k$N(B \rcsection{extensions} $B%;%/%7%g%s$K<!$N9T$rDI2C$9$kDL>o$N(B
$BJ}K!$G(B\hgext{extdiff}$B$rM-8z$K$G$-$k!%(B
\begin{codesample2}
  [extensions]
  extdiff =
\end{codesample2}
%The \command{interdiff} command expects to be passed the names of two
%files, but the \hgext{extdiff} extension passes the program it runs a
%pair of directories, each of which can contain an arbitrary number of
%files.  We thus need a small program that will run \command{interdiff}
%on each pair of files in these two directories.  This program is
%available as \sfilename{hg-interdiff} in the \dirname{examples}
%directory of the source code repository that accompanies this book.
%\excode{hg-interdiff}

\command{interdiff}$B%3%^%s%I$O(B2$B$D$N%U%!%$%kL>$rEO$5$l$k$3$H$rA[Dj$7$F$$$k(B
$B$,!$(B\hgext{extdiff}$B3HD%$O!$(B2$B$D$N%G%#%l%/%H%j$r0z?t$H$7$F<h$k%3%^%s%I$r5/(B
$BF0$9$k!%=>$C$F$3$l$i$N(B2$B$D$N%G%#%l%/%H%j$N3F!9$N%U%!%$%k$KBP$7$F(B
\command{interdiff}$B$r5/F0$9$k>.$5$J%W%m%0%i%`$,I,MW$K$J$k!%$3$NK\$N%=!<%9(B
$B%3!<%I%j%]%8%H%j%G%#%l%/%H%jFb$N(B\dirname{examples}$B%G%#%l%/%H%j$K$"$k(B
\sfilename{hg-interdiff}$B$H$$$&%W%m%0%i%`$,$=$l$@!%(B
\excode{hg-interdiff}

%With the \sfilename{hg-interdiff} program in your shell's search path,
%you can run it as follows, from inside an MQ patch directory:
$B%7%'%k%5!<%A%Q%9$NCf$K(B\sfilename{hg-interdiff}$B$,$"$l$P!$(B MQ$B%Q%C%A%G%#%l%/(B
$B%H%j$NCf$+$i<!$N$h$&$K5/F0$G$-$k!%(B

\begin{codesample2}
  hg extdiff -p hg-interdiff -r A:B my-change.patch
\end{codesample2}
%Since you'll probably want to use this long-winded command a lot, you
%can get \hgext{hgext} to make it available as a normal Mercurial
%command, again by editing your \hgrc.
$B$3$ND9$$%3%^%s%I$OIQHK$K;H$&$3$H$K$J$k$@$m$&!%$=$3$G(B \hgrc $B$rJT=8(B
$B$7!$(B\hgext{hgext}$B$GDL>o$N(BMercurial$B%3%^%s%I$N$h$&$K;H$($k$h$&$K$9$k!%(B
\begin{codesample2}
  [extdiff]
  cmd.interdiff = hg-interdiff
\end{codesample2}
%This directs \hgext{hgext} to make an \texttt{interdiff} command
%available, so you can now shorten the previous invocation of
%\hgxcmd{extdiff}{extdiff} to something a little more wieldy.
$B$3$l$O(B\hgext{hgext}$B$K(B\texttt{interdiff}$B%3%^%s%I$,MxMQ2DG=$G$"$k$3$H$r;X(B
$B<($9$k$?$a!$0JA0$N(B\hgxcmd{extdiff}{extdiff}$B$N5/F0$r<c434JC1$K$G$-$k!%(B
\begin{codesample2}
  hg interdiff -r A:B my-change.patch
\end{codesample2}

\begin{note}
%  The \command{interdiff} command works well only if the underlying
%  files against which versions of a patch are generated remain the
%  same.  If you create a patch, modify the underlying files, and then
%  regenerate the patch, \command{interdiff} may not produce useful
%  output.

\command{interdiff}$B%3%^%s%I$O!$%Q%C%A$N%P!<%8%g%s$,@8@.$5$l$?85$N%U%!%$%k(B
$B$,F10l$KJ]$?$l$F$$$k>l9g$K8B$C$F@5$7$/F0$/!%%Q%C%A$r:n@.$7$F$+$i85$N%U%!(B
$B%$%k$rJQ99$7!$%Q%C%A$r:F@8@.$7$?>l9g$O(B\command{interdiff}$B$OM-MQ$J:9J,$r=P(B
$BNO$7$J$$$+$b$7$l$J$$!%(B

\end{note}

%The \hgext{extdiff} extension is useful for more than merely improving
%the presentation of MQ~patches.  To read more about it, go to
%section~\ref{sec:hgext:extdiff}.

\hgext{extdiff}$B%(%/%9%F%s%7%g%s$O(BMQ$B%Q%C%A$NI=8=$r2~A1$9$k0J>e$N$3$H$r$9(B
$B$k!%$3$N%(%/%9%F%s%7%g%s$K$D$$$F99$KCN$j$?$$;~$O(B\ref{sec:hgext:extdiff}$B%;(B
$B%/%7%g%s$r;2>H$5$l$?$$!%(B

%%% Local Variables:
%%% mode: yatex
%%% TeX-master: "00book"
%%% End: