comparison ja/mq.tex @ 343:f3f56da2e650

more mq.tex

342:dfa9910e2a2e

\end{itemize}

%\subsection{Beware the fuzz}
\subsection{$B[#Kf$JE@$K$D$$$F(B}

While applying a hunk at an offset, or with a fuzz factor, will often
be completely successful, these inexact techniques naturally leave
open the possibility of corrupting the patched file.  The most common
cases typically involve applying a patch twice, or at an incorrect
location in the file.  

If \command{patch} or \hgxcmd{mq}{qpush} ever
mentions an offset or fuzz factor, you should make sure that the
modified files are correct afterwards.  

$B$"$k%*%U%;%C%H$d(Bfuzz factor$B$N0LCV$X$N(Bhunk$B$NE,MQ$OB?$/$N>l9gA4$/LdBj$J$/@.(B
$B8y$9$k$,!$IT@53N$J%^%C%A$rMQ$$$?>l9g!$%Q%C%A$rE,MQ$7$?%U%!%$%k$r2u$7$F$$(B
$B$k2DG=@-$,;D$k!%(B

$B%Q%C%A$rFsEYE,MQ$7$?$j!$%U%!%$%k$N4V0c$C$?>l=j$KE,MQ$7$F$7$^$&$N$,0lHV$h(B
$B$/$"$k4V0c$$$@!%(B




It's often a good idea to refresh a patch that has applied with an
offset or fuzz factor; refreshing the patch generates new context
information that will make it apply cleanly.  I say ``often,'' not
``always,'' because sometimes refreshing a patch will make it fail to
apply against a different revision of the underlying files.  In some
cases, such as when you're maintaining a patch that must sit on top of
multiple versions of a source tree, it's acceptable to have a patch
apply with some fuzz, provided you've verified the results of the
patching process in such cases.

%\subsection{Handling rejection}
\subsection{$B%j%8%'%/%H$N<h$j07$$(B}

If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
message and exit.  If it has left \sfilename{.rej} files behind, it is
usually best to fix up the rejected hunks before you push more patches
or do any further work.

If your patch \emph{used to} apply cleanly, and no longer does because
you've changed the underlying code that your patches are based on,
Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.

Unfortunately, there aren't any great techniques for dealing with
rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
file and edit the target file, applying the rejected hunks by hand.

If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
vigorous than \command{patch} in its attempts to make a patch apply.

Another Linux kernel hacker, Chris Mason (the author of Mercurial
Queues), wrote a similar tool called
\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
automating the application of hunks rejected by \command{patch}.  The
\command{mpatch} command can help with four common reasons that a hunk
may be rejected:

\begin{itemize}
\item The context in the middle of a hunk has changed.
\item A hunk is missing some context at the beginning or end.
\item A large hunk might apply better---either entirely or in
  part---if it was broken up into smaller hunks.
\item A hunk removes lines with slightly different content than those
  currently present in the file.
\end{itemize}

If you use \command{wiggle} or \command{mpatch}, you should be doubly
careful to check your results when you're done.  In fact,
\command{mpatch} enforces this method of double-checking the tool's
output, by automatically dropping you into a merge program when it has
done its job, so that you can verify its work and finish off any
remaining merges.

%\section{Getting the best performance out of MQ}
\section{MQ$B$r:GBg8B$K3hMQ$9$k(B}
\label{sec:mq:perf}

MQ is very efficient at handling a large number of patches.  I ran
some performance experiments in mid-2006 for a talk that I gave at the
2006 EuroPython conference~\cite{web:europython}.  I used as my data
set the Linux 2.6.17-mm1 patch series, which consists of 1,738
patches.  I applied these on top of a Linux kernel repository
containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
2.6.17.

On my old, slow laptop, I was able to
\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds.  (On a
newer laptop, the time to push all patches dropped to two minutes.)  I
could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
lines of changes to 287 files) in 6.6 seconds.

Clearly, MQ is well suited to working in large trees, but there are a
few tricks you can use to get the best performance of it.

First of all, try to ``batch'' operations together.  Every time you
run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
directory once to make sure you haven't made some changes and then
forgotten to run \hgxcmd{mq}{qrefresh}.  On a small tree, the time that
this scan takes is unnoticeable.  However, on a medium-sized tree
(containing tens of thousands of files), it can take a second or more.

The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
multiple patches at a time.  You can identify the ``destination
patch'' that you want to end up at.  When you \hgxcmd{mq}{qpush} with a
destination specified, it will push patches until that patch is at the
top of the applied stack.  When you \hgxcmd{mq}{qpop} to a destination, MQ
will pop patches until the destination patch is at the top.

You can identify a destination patch using either the name of the
patch, or by number.  If you use numeric addressing, patches are
counted from zero; this means that the first patch is zero, the second
is one, and so on.

%\section{Updating your patches when the underlying code changes}
\section{$B2<0L%3!<%I$NJQ2=$K9g$o$;$F%Q%C%A$r99?7$9$k(B}
\label{sec:mq:merge}

It's common to have a stack of patches on top of an underlying
repository that you don't modify directly.  If you're working on
changes to third-party code, or on a feature that is taking longer to

You can then issue commands of the form \cmdargs{mq}{pull} from
the main repository.

%\subsection{A few things to watch out for}
\subsection{$B4F;k$7$F$*$/$Y$-$$$/$D$+$NE@(B}

MQ's support for working with a repository full of patches is limited
in a few small respects.

MQ cannot automatically detect changes that you make to the patch

343:f3f56da2e650

\end{itemize}

%\subsection{Beware the fuzz}
\subsection{$B[#Kf$JE@$K$D$$$F(B}

%While applying a hunk at an offset, or with a fuzz factor, will often
%be completely successful, these inexact techniques naturally leave
%open the possibility of corrupting the patched file.  The most common
%cases typically involve applying a patch twice, or at an incorrect
%location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever
%mentions an offset or fuzz factor, you should make sure that the
%modified files are correct afterwards.  

$B$"$k%*%U%;%C%H$d(Bfuzz factor$B$N0LCV$X$N(Bhunk$B$NE,MQ$O!$B?$/$N>l9gLdBj$J$/@.8y(B
$B$9$k$,!$IT@53N$J%^%C%A$rMQ$$$?>l9g!$%Q%C%A$rE,MQ$7$?%U%!%$%k$r2u$7$F$$$k(B
$B2DG=@-$,;D$k!%:G$b$h$/$"$k$N$O!$%Q%C%A$rFsEYE,MQ$7$?$j!$%U%!%$%k$N4V0c$C(B
$B$?>l=j$KE,MQ$7$F$7$^$&$3$H$@!%(B\command{patch}$B$^$?$O(B\hgxcmd{mq}{qpush}$B$,%*(B
$B%U%;%C%H$+(Bfuzz$B%U%!%/%?!<$rI=<($7$F$$$k9g!$JQ99$5$l$?%U%!%$%k$,@5>o$G$"$k(B
$B$+3NG'$9$kI,MW$,$"$k!%(B

%It's often a good idea to refresh a patch that has applied with an
%offset or fuzz factor; refreshing the patch generates new context
%information that will make it apply cleanly.  I say ``often,'' not
%``always,'' because sometimes refreshing a patch will make it fail to
%apply against a different revision of the underlying files.  In some
%cases, such as when you're maintaining a patch that must sit on top of
%multiple versions of a source tree, it's acceptable to have a patch
%apply with some fuzz, provided you've verified the results of the
%patching process in such cases.

$B%*%U%;%C%H$d(Bfuzz factor$B$N=P$?%Q%C%A$r%j%U%l%C%7%e$9$k$N$OB?$/$N>l9gNI$$9M(B
$B$($G$"$k!%%Q%C%A$r%j%U%l%C%7%e$9$k$H!$?7$7$$%3%s%F%-%9%H>pJs$,@8@.$5$l!$(B
$B%Q%C%A$,%/%j!<%s$KE,MQ$G$-$k$h$&$K$J$k!%!V>o$K!W$G$O$J$J$/!VB?$/$N>l9g!W(B
$B$HCG$C$?$N$O!$%Q%C%A$r%j%U%l%C%7%e$9$k$3$H$G!$85$N%U%!%$%k$N0[$J$C$?%j%S(B
$B%8%g%s$G%Q%C%A$,E,MQ$G$-$J$/$J$k$3$H$,$"$k$+$i$@!%J#?t$N%P!<%8%g%s$N%=!<(B
$B%9%D%j!<$N>e$GE,MQ2DG=$J%Q%C%A$r4IM}$7$J$1$l$P$J$i$J$$$h$&$J>l9g$J$I$O!$(B
$B%Q%C%A$N7k2L$r8!>Z$7$F$"$k$N$G$"$l$P(Bfuzz$B$N=P$k%Q%C%A$b5vMF$5$lF@$k!%(B

%\subsection{Handling rejection}
\subsection{$B%j%8%'%/%H$N<h$j07$$(B}

%If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
%message and exit.  If it has left \sfilename{.rej} files behind, it is
%usually best to fix up the rejected hunks before you push more patches
%or do any further work.

\hgxcmd{mq}{qpush}$B$O%Q%C%A$NE,MQ$K<:GT$7$?>l9g!$%(%i!<%a%C%;!<%8$rI=<($7(B
$B$F=*N;$9$k!%(B\sfilename{.rej}$B%U%!%$%k$,:n$i$l$F$$$k>l9g$O!$DL>o!$$5$i$J$k(B
$B%Q%C%A$NDI2C$d?7$7$$:n6H$NA0$K%j%8%'%/%H$5$l$?(Bhunk$B$K$D$$$F=$@5$r9T$&$Y$-(B
$B$G$"$k!%(B

%If your patch \emph{used to} apply cleanly, and no longer does because
%you've changed the underlying code that your patches are based on,
%Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.

$B$=$l$^$G%Q%C%A$,%/%j!<%s$KE,MQ$5$l$F$*$j!$%Q%C%A$NBP>]$K$J$C$F$$$k%3!<%I(B
$B$KJQ99$r2C$($?$?$a$KE,MQ$G$-$J$/$J$C$?$N$J$i!$(BMercurial Queues$B$N;Y1g$r<u(B
$B$1$k$3$H$,$G$-$k!%>\$7$$>pJs$O%;%/%7%g%s(B~\ref{sec:mq:merge}$B$r8+$FM_$7$$!%(B

%Unfortunately, there aren't any great techniques for dealing with
%rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
%file and edit the target file, applying the rejected hunks by hand.

$B;DG0$J$3$H$K!$%j%8%'%/%H$5$l$?(Bhunk$B$r<h$j07$&7h$^$C$?NI$$J}K!$OB8:_$7$J(B
$B$$!%BgDq$N>l9g!$(B\sfilename{.rej}$B%U%!%$%k$r8+$F%?!<%2%C%H%U%!%$%k$rJT=8(B
$B$7!$%j%8%'%/%H$5$l$?(Bhunk$B$r<j$GE,MQ$9$k$3$H$K$J$k!%(B

%If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
%wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
%vigorous than \command{patch} in its attempts to make a patch apply.

$BKA81$,9%$-$J$i!$(BLinux kerner$B%O%C%+!<$N(BNeil Brown$B$,=q$$$?(B
\command{wiggle}~\cite{web:wiggle}$B$r;n$7$F$_$k$HNI$$!%$3$N%3%^%s%I$O(B
\command{patch}$B$h$j$b@:NOE*$K%Q%C%A$NE,MQ$r;n$_$k!%(B

%Another Linux kernel hacker, Chris Mason (the author of Mercurial
%Queues), wrote a similar tool called
%\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
%automating the application of hunks rejected by \command{patch}.  The
%\command{mpatch} command can help with four common reasons that a hunk
%may be rejected:

$BJL$N(BLinux kerner$B%O%C%+!<(B Chris Mason$B!J(BMercurial Queues$B$N:n<T$G$b$"$k!%!K(B
$B$O(B\command{mpatch}~\cite{web:mpatch}$B$H$$$&%D!<%k$r=q$$$?!%$3$N%3%^%s%I$O(B
\command{patch}$B%3%^%s%I$G%j%8%'%/%H$5$l$?(Bhunk$B$NE,MQ$r<+F02=$9(B
$B$k!%(B\command{mpatch}$B%3%^%s%I$O!$(Bhunk$B$,%j%8%'%/%H$5$l$k<g$J860x(B4$B$D$KBP1~(B
$B$9$k(B:

\begin{itemize}
%\item The context in the middle of a hunk has changed.
\item hunk$B$NCf$N%3%s%F%-%9%H$,JQ99$5$l$?(B
%\item A hunk is missing some context at the beginning or end.
\item hunk$B$N3+;OIt!&=*C<It$G%3%s%F%-%9%H$,8+$D$1$i$l$J$$(B
%\item A large hunk might apply better---either entirely or in
%  part---if it was broken up into smaller hunks.
\item $BBg$-$J(Bhunk$B$O$b$C$H>e<j$KE,MQ$G$-$kH&$@(B---hunk$B$r>.$5$J(Bhunk$B$KJ,3d$7(B
      $B$FE,MQ$9$k(B
%\item A hunk removes lines with slightly different content than those
%  currently present in the file.
\item hunk$BFb$N9T$,8=:_%U%!%$%k$K$"$k9T$H<c430c$C$F$$$k>l9g!$$=$N9T$r:o=|(B
      $B$9$k(B
\end{itemize}

%If you use \command{wiggle} or \command{mpatch}, you should be doubly
%careful to check your results when you're done.  In fact,
%\command{mpatch} enforces this method of double-checking the tool's
%output, by automatically dropping you into a merge program when it has
%done its job, so that you can verify its work and finish off any
%remaining merges.

\command{wiggle}$B$^$?$O(B\command{mpatch}$B$r;HMQ$7$?>l9g$O!$7k2L$K:Y?4$NCm0U(B
$B$,I,MW$G$"$k!%<B:]$K$O(B\command{mpatch}$B$O%D!<%k$N=PNO$GFs=E%A%'%C%/$r6/@)(B
$B$7!$F0:n$,=*$k$H<+F0E*$K%^!<%8%W%m%0%i%`$r5/F0$9$k!%$3$l$K$h$C$F:n6H$r3N(B
$BG'$7!$%^!<%8$r40N;$9$k$3$H$,$G$-$k!%(B

%\section{Getting the best performance out of MQ}
\section{MQ$B$r:GBg8B$K3hMQ$9$k(B}
\label{sec:mq:perf}

%MQ is very efficient at handling a large number of patches.  I ran
%some performance experiments in mid-2006 for a talk that I gave at the
%2006 EuroPython conference~\cite{web:europython}.  I used as my data
%set the Linux 2.6.17-mm1 patch series, which consists of 1,738
%patches.  I applied these on top of a Linux kernel repository
%containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
%2.6.17.

MQ$B$O$H$F$b8zN(E*$KBgNL$N%Q%C%A$r=hM}$9$k$3$H$,$G$-$k!%I.<T$O(B2006$BG/$NCf:"!$(B
2006 EuroPython conference~\cite{web:europython}$B$G$N9V1i$N$?$a$K@-G=B,Dj(B
$B$r9T$C$?!%B,Dj$KMQ$$$?%G!<%?$O(BLinux 2.6.17-mm1$B$N%Q%C%A%7%j!<%:$G!$(B1,738
$B$N%Q%C%A$r4^$`!%$3$N%Q%C%A$r(BLinux kernel$B%j%]%8%H%j$KE,MQ$7$?!%%j%]%8%H%j(B
$B$O(BLinux 2.6.12-rc2$B$+$i(BLinux 2.6.17$B$^$G$N(B27,472$B$N%j%S%8%g%s$r4^$s$G$$$k!%(B

%On my old, slow laptop, I was able to
%\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
%and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds.  (On a
%newer laptop, the time to push all patches dropped to two minutes.)  I
%could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
%lines of changes to 287 files) in 6.6 seconds.

$BI.<T$N8E$/CY$$%i%C%W%H%C%W$G!$(B\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}}$B$G(B
1738$B$N%Q%C%A$9$Y$F$r=hM}$9$k$N$K(B
3.5$BJ,!$(B\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}$B$r9T$&$N$K(B30$BIC$rMW$7$?!%(B($B?7(B
$B$7$$%i%C%W%H%C%W$G$O%W%C%7%e$N=jMW;~4V$O(B2$BJ,$G$"$C$?!%(B)$B:GBg$N%Q%C%A(B
(22.778$B9T$G!$(B287$B$N%U%!%$%k$rJQ99$9$k(B)$B$K(B\hgxcmd{mq}{qrefresh}$B$r9T$C$?$H$3(B
$B$m!$(B6.6$BIC$rMW$7$?!%(B

%Clearly, MQ is well suited to working in large trees, but there are a
%few tricks you can use to get the best performance of it.

MQ$B$,5pBg$J%D%j!<$G$N:n6H$KE,$7$F$$$k$N$OL@$i$+$@$,!$$5$i$K:G9b$N@-G=$r0z(B
$B$-=P$9$?$a$K$$$/$D$+$N%H%j%C%/$,;H$($k!%(B

%First of all, try to ``batch'' operations together.  Every time you
%run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
%directory once to make sure you haven't made some changes and then
%forgotten to run \hgxcmd{mq}{qrefresh}.  On a small tree, the time that
%this scan takes is unnoticeable.  However, on a medium-sized tree
%(containing tens of thousands of files), it can take a second or more.

$B$^$:Bh0l$K!$(B``batch''$B%*%Z%l!<%7%g%s$rJ;MQ$9$k$3$H$,$G$-(B
$B$k!%(B\hgxcmd{mq}{qpush}$B$^$?$O(B\hgxcmd{mq}{qpop}$B$O!$%o!<%-%s%0%G%#%l%/%H%j$K(B
$BJQ99$r2C$($?$N$K(B\hgxcmd{mq}{qrefresh}$B$N<B9T$rK:$l$F$$$J$$$+$I$&$+D4$Y$k$?(B
$B$a!$<B9T;~$K>o$K%o!<%-%s%0%G%#%l%/%H%j$r%9%-%c%s$9$k!%>.5,LO$J%D%j!<$G$O(B
$B5$$E$+$J$$DxEY$N;~4V$7$+$+$+$i$J$$$,!$(B($B?tK|$N%U%!%$%k$r;}$D$h$&$J(B)$BCf5,LO(B
$B$N$G$O?tIC$N;~4V$rMW$9$k!%(B

%The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
%multiple patches at a time.  You can identify the ``destination
%patch'' that you want to end up at.  When you \hgxcmd{mq}{qpush} with a
%destination specified, it will push patches until that patch is at the
%top of the applied stack.  When you \hgxcmd{mq}{qpop} to a destination, MQ
%will pop patches until the destination patch is at the top.

\hgxcmd{mq}{qpush}$B%3%^%s%I$H(B\hgxcmd{mq}{qpop}$B%3%^%s%I$OJ#?t$N%U%!%$%k$rF1(B
$B;~$K(Bpush$B$^$?$O(Bpop$B$9$k$3$H$,$G$-$k!%:G=*L\E*$N%Q%C%A$,$"$k$J$i(B
$B$P!$(B\hgxcmd{mq}{qpush}$B$KL\E*$N%Q%C%A$r;XDj$7$F<B9T$9$k$3$H$G!$;XDj$7$?%Q%C(B
$B%A$,:F>e0L$K$J$k$^$G%Q%C%A$r(Bpush$B$9$k!%F1MM$K(B\hgxcmd{mq}{qpop}$B$KL\E*$N%Q%C(B
$B%A$r;XDj$9$l$P!$;XDj$7$?%Q%C%A$,:F>e0L$K$J$k$^$G%Q%C%A$r(Bpop$B$9$k!%(B

%You can identify a destination patch using either the name of the
%patch, or by number.  If you use numeric addressing, patches are
%counted from zero; this means that the first patch is zero, the second
%is one, and so on.

$BL\E*$N%Q%C%A$OL>A0$G$bHV9f$G$b;XDj2DG=$G$"$k!%HV9f$,MQ$$$i$l$k>l9g$O!$%Q%C(B
$B%A$O(B0$B$+$i%+%&%s%H$5$l$k!%$D$^$j:G=i$N%Q%C%A$O(B0$B$H$J$j!$(B2$BHVL\$O(B1$B!$$H$$$&Iw(B
$B$K$J$k!%(B

%\section{Updating your patches when the underlying code changes}
\section{$BBP>]%3!<%I$NJQ2=$K9g$o$;$F%Q%C%A$r99?7$9$k(B}
\label{sec:mq:merge}

It's common to have a stack of patches on top of an underlying
repository that you don't modify directly.  If you're working on
changes to third-party code, or on a feature that is taking longer to

You can then issue commands of the form \cmdargs{mq}{pull} from
the main repository.

%\subsection{A few things to watch out for}
\subsection{$BCm0U$7$F$*$/$Y$-$$$/$D$+$NE@(B}

MQ's support for working with a repository full of patches is limited
in a few small respects.

MQ cannot automatically detect changes that you make to the patch