Mercurial > hgbook
view ja/mq.tex @ 803:5276f40fca1c
Propagate e6c99cbd0abd
Updates to chapters 5, 6, and 7
| author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
|---|---|
| date | Thu, 09 Jul 2009 13:32:44 +0900 |
| parents | de4142983445 |
| children | 8a3041e6f3cb |
line wrap: on
line source
%\chapter{Managing change with Mercurial Queues} \chapter{Mercurial Queues$B$GJQ99$r4IM}$9$k(B} \label{chap:mq} %\section{The patch management problem} \section{$B%Q%C%A4IM}$NLdBj(B} \label{sec:mq:patch-mgmt} %Here is a common scenario: you need to install a software package from %source, but you find a bug that you must fix in the source before you %can start using the package. You make your changes, forget about the %package for a while, and a few months later you need to upgrade to a %newer version of the package. If the newer version of the package %still has the bug, you must extract your fix from the older source %tree and apply it against the newer version. This is a tedious task, %and it's easy to make mistakes. $B$h$/$"$k%7%J%j%*!'%=!<%9$+$i%=%U%H%&%'%"%Q%C%1!<%8$r%$%s%9%H!<%k$9$kI,MW(B $B$,$"$k!%$7$+$7%Q%C%1!<%8$r;H$&A0$K%=!<%9$+$iD>$9$Y$-%P%0$r8+$D$1$?!%JQ99(B $B$r2C$($F!$;C$/%Q%C%1!<%8$N$3$H$OK:$l$F$$$k!%?t%v7n8e!$?7$7$$%P!<%8%g%s$r(B $B%$%s%9%H!<%k$9$k$3$H$K$J$C$?!%$b$7?7$7$$%P!<%8%g%s$,!$0MA3$H$7$F$=$N%P%0(B $B$r;}$C$F$$$?>l9g!$=$@5$r8E$$%=!<%9$+$iCj=P$7$F!$?7$7$$%P!<%8%g%s$KE,MQ$7(B $B$J$1$l$P$J$i$J$$!%$3$l$OB`6~$G$7$+$b4V0c$$$d$9$$;E;v$@!%(B %This is a simple case of the ``patch management'' problem. You have %an ``upstream'' source tree that you can't change; you need to make %some local changes on top of the upstream tree; and you'd like to be %able to keep those changes separate, so that you can apply them to %newer versions of the upstream source. $B$3$l$,%Q%C%A4IM}LdBj$N%7%s%W%k$JNc$G$"$k!%$b$7$"$J$?$,JQ99$G$-$J$$>eN.$N(B $B%=!<%9%D%j!<$,$"$l$P!$%"%C%W%9%H%j!<%`$N%D%j!<$N>e$G%m!<%+%k$JJQ99$r$7$J(B $B$1$l$P$J$i$J$$!%$"$J$?$O%"%C%W%9%H%j!<%`%=!<%9$KE,MQ$G$-$k$h$&$K$-$C$H$3(B $B$NJQ99$rJ,N%$7$F$*$-$?$$$H;W$&$O$:$@!%(B %The patch management problem arises in many situations. Probably the %most visible is that a user of an open source software project will %contribute a bug fix or new feature to the project's maintainers in the %form of a patch. $B%Q%C%A4IM}LdBj$O$$$m$$$m$J>u67$G5/$3$k!%$*$=$i$/:G$bL@$i$+$J$N$O!$%*!<%W(B $B%s%=!<%9%=%U%H%&%'%"%W%m%8%'%/%H$N%f!<%6$,!$%W%m%8%'%/%H$N%a%s%F%J$K%P%0(B $B%U%#%C%/%9$d?75!G=$r%Q%C%A$N7A$G9W8%$9$k$3$H$G$"$m$&!%(B %Distributors of operating systems that include open source software %often need to make changes to the packages they distribute so that %they will build properly in their environments. $B%*!<%W%s%=%U%H%&%'%"$r4^$`%*%Z%l!<%F%#%s%0%7%9%F%`$NG[I[<T$O!$G[I[$9$k%Q%C(B $B%1!<%8$,H`$i$N4D6-$G@5$7$/%S%k%I$G$-$k$h$&$K%Q%C%1!<%8$XJQ99$r2C$($k$3$H(B $B$,B?$$!%(B %When you have few changes to maintain, it is easy to manage a single %patch using the standard \command{diff} and \command{patch} programs %(see section~\ref{sec:mq:patch} for a discussion of these tools). Once %the number of changes grows, it starts to make sense to maintain patches %as discrete ``chunks of work,'' so that for example a single patch will %contain only one bug fix (the patch might modify several files, but it's %doing ``only one thing''), and you may have a number of such patches for %different bugs you need fixed and local changes you require. In this %situation, if you submit a bug fix patch to the upstream maintainers of %a package and they include your fix in a subsequent release, you can %simply drop that single patch when you're updating to the newer release. $B$b$7%a%s%F%J%s%9$7$F$$$kJQ99$,$4$/$o$:$+$J$i!$I8=`$N(B\command{diff}$B%3%^%s(B $B%I$H(B\command{patch}$B%3%^%s%I$r;H$C$FC10l$N%Q%C%A$r4IM}$9$k$N$,4JC1$@!%!J$3(B $B$l$i$N%D!<%k$K$D$$$F$O(B~\ref{sec:mq:patch}$B$N@a$r;2>H!%!KJQ99$N?t$,A}$($F$/(B $B$k$H!$C10l$N%P%0%U%#%C%/%9$r4^$`8D!9$N%Q%C%A$r0l2t$N=89g$H$7$F4IM}$9$k$3(B $B$H$,8=<BL#$rBS$S$F$/$k!%!J3F!9$N%Q%C%A$OJ#?t$N%U%!%$%k$rJQ99$9$k$+$b$7$l(B $B$J$$$,!$L\E*$O(B1$B$D$-$j$G$"$k!%!K=$@5$7$?$$%P%0$,$$$/$D$b$"$C$?$j!$%m!<%+%k(B $B$G$NMM!9$JJQ99$NI,MW$N$?$a!$?tB?$/$N$=$N$h$&$J%Q%C%A$r;}$D$3$H$K$J$k$+$b(B $B$7$l$J$$!%$3$N>u67$G!$%"%C%W%9%H%j!<%`$N%a%s%F%J$K%P%0=$@5%Q%C%A$rAw$j!$(B $BH`$i$,$"$J$?$N=$@5$r8e$N%j%j!<%9$K<h$j9~$a$P!$<j85$G?7$7$$%j%j!<%9$K@ZBX(B $B$($?;~$K$OC1=c$K$=$N%Q%C%A$rGK4~$9$l$PNI$$!%(B %Maintaining a single patch against an upstream tree is a little %tedious and error-prone, but not difficult. However, the complexity %of the problem grows rapidly as the number of patches you have to %maintain increases.With more than a tiny number of patches in hand, %understanding which ones you have applied and maintaining them moves %from messy to overwhelming. $BC10l$N%Q%C%A$r%"%C%W%9%H%j!<%`$N%D%j!<$KBP$7$F%a%s%F%J%s%9$9$k$3$H$O$d$d(B $BLLE]$G!$4V0c$$$N85$K$J$j$,$A$G$"$k$,!$Fq$7$/$O$J$$!%$7$+$7!$%a%s%F%J%s%9(B $B$9$k%Q%C%A$N?t$,A}$($k$K=>$C$FLdBj$NJ#;($5$,5^B.$KA}$7$F$$$/!%%Q%C%A$N?t(B $B$,$"$kDxEY0J>eB?$/$J$k$H!$$I$N%Q%C%A$rE,MQ$7$?$+!$$I$N%Q%C%A$r4IM}$7$F$$(B $B$k$N$+$NM}2r$,!$Lq2p$H$$$&>uBV$+$i05E]$5$l$k$F$$$k>uBV$K$J$k!%(B %Fortunately, Mercurial includes a powerful extension, Mercurial Queues %(or simply ``MQ''), that massively simplifies the patch management %problem. $B9,$$$K$b!$(BMercurial$B$O(BMercurial Queues$B!J$"$k$$$OC1$K(BMQ$B!K$H$$$&6/NO$J%(%/%9(B $B%F%s%7%g%s$r$b$C$F$*$j!$%Q%C%A4IM}$NLdBj$rBgI}$KC1=c2=$9$k!%(B %\section{The prehistory of Mercurial Queues} \section{Mercurial Queues$BA0;K(B} \label{sec:mq:history} %During the late 1990s, several Linux kernel developers started to %maintain ``patch series'' that modified the behaviour of the Linux %kernel. Some of these series were focused on stability, some on %feature coverage, and others were more speculative. 1990$BG/Be$N=*$o$j:"!$(BLinux$B%+!<%M%k$N3+H/<TC#$O!$(BLinux$B%+!<%M%k$r2~A1$9$k0l(B $BO"$N%Q%C%A$N4IM}$r;O$a$?!%$=$l$i$N$&$A!$$"$k$b$N$O0BDj@-$K!$JL$N$b$N$OFC(B $BDj$N5!G=$K!$$^$?JL$N$b$N$OLn?4E*$JFbMF$KFC2=$7$F$$$?!%(B %The sizes of these patch series grew rapidly. In 2002, Andrew Morton %published some shell scripts he had been using to automate the task of %managing his patch queues. Andrew was successfully using these %scripts to manage hundreds (sometimes thousands) of patches on top of %the Linux kernel. $B$3$l$i$N%Q%C%A%7%j!<%:$N%5%$%:$O$O$9$0$KKD$l>e$,$C$?!%(B2002$BG/$K(BAndrew Morton$B$OH`$N%Q%C%A%-%e!<$N4IM}$r<+F02=$9$k$$$/$D$+$N%7%'%k%9%/%j%W%H$r8x(B $BI=$7$?!%(BAndrew$B$O?tI4$+$i?t@i$N(BLinux$B%+!<%M%k%Q%C%A$r$3$l$i$N%9%/%j%W%H$G(B $B4IM}$9$k$3$H$,$G$-$F$$$?!%(B %\subsection{A patchwork quilt} \subsection{patchwork quilt} \label{sec:mq:quilt} %In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the %approach of Andrew's scripts and published a tool called ``patchwork %quilt''~\cite{web:quilt}, or simply ``quilt'' %(see~\cite{gruenbacher:2005} for a paper describing it). Because %quilt substantially automated patch management, it rapidly gained a %large following among open source software developers. 2003$BG/$N;O$a!$(BAndreas Gruenbacher$B$H(BMartin Quinson$B$O(BAndrew$B$N%9%/%j%W%H$N$d(B $B$jJ}$r??;w$F!$(B``patchwork quilt''~\cite{web:quilt}$B$"$k$$$OC1$K(B``quilt''$B$H(B $B8F$P$l$k%D!<%k$r%j%j!<%9$7$?!%!J>\$7$/$OO@J8(B~\cite{gruenbacher:2005}$B$r;2(B $B>H$N$3$H!%!K(Bquilt$B$O==J,$K<+F02=$5$l$?%Q%C%A4IM}$rDs6!$7$F$$$?$N$G!$%=%U%H(B $B%&%'%"3+H/<T$NBg$-$J;Y;}$r5^B.$K3MF@$7$F$$$C$?!%(B %Quilt manages a \emph{stack of patches} on top of a directory tree. %To begin, you tell quilt to manage a directory tree, and tell it which %files you want to manage; it stores away the names and contents of %those files. To fix a bug, you create a new patch (using a single %command), edit the files you need to fix, then ``refresh'' the patch. quilt$B$O%G%#%l%/%H%j%D%j!<>e$G(B\emph{$B%Q%C%A$N%9%?%C%/(B}$B$r4IM}$9$k!%%Q%C%A$N(B $B4IM}$r;O$a$k$K$O!$(Bquilt$B$K4IM}$9$Y$-%G%#%l%/%H%j%D%j!<$H!$4IM}BP>]$N%U%!%$(B $B%k$r;XDj$9$k!%(Bquilt$B$O$3$l$i$N%U%!%$%k$NL>A0$HCf?H$rJ]B8$9$k!%%P%0$r=$@5(B $B$9$k>l9g$O!$$^$:?7$7$$%Q%C%A$r!J%3%^%s%I(B1$B$D$G!K:n@.$7!$I,MW$J%U%!%$%k$K(B $B=$@5$r2C$($?8e!$%Q%C%A$r(B``$B%j%U%l%C%7%e(B''$B$9$l$P$h$$!%(B %The refresh step causes quilt to scan the directory tree; it updates %the patch with all of the changes you have made. You can create %another patch on top of the first, which will track the changes %required to modify the tree from ``tree with one patch applied'' to %``tree with two patches applied''. $B%j%U%l%C%7%e$G$O!$(Bquilt$B$O%G%#%l%/%H%j%D%j!<$r%9%-%c%s$7!$JQ99A4$F$rH?1G$5(B $B$;$F%Q%C%A$r99?7$9$k!%(B``$B$"$k%Q%C%A$,E,MQ$5$l$?>uBV$N%D%j!<(B''$B$+$i(B``2$B$D$N%Q%C(B $B%A$,E,MQ$5$l$?%D%j!<(B''$B$X99?7$9$k$N$KI,MW$JJQ99$rDI@W$7!$JL$N%Q%C%A$r:n$k(B $B$3$H$b$G$-$k!%(B %You can \emph{change} which patches are applied to the tree. If you %``pop'' a patch, the changes made by that patch will vanish from the %directory tree. Quilt remembers which patches you have popped, %though, so you can ``push'' a popped patch again, and the directory %tree will be restored to contain the modifications in the patch.Most %importantly, you can run the ``refresh'' command at any time, and the %topmost applied patch will be updated. This means that you can, at %any time, change both which patches are applied and what %modifications those patches make. $B%f!<%6$O$I$N%Q%C%A$,%D%j!<$KE,MQ$5$l$k$+$r(B\emph{$BJQ99(B}$B$G$-$k!%$"$k%Q%C%A$r(B $B%]%C%W$9$k$H!$$3$N%Q%C%A$K$h$kJQ99$O%D%j!<$+$i>CLG$9$k!%(Bquilt$B$O$I$N%Q%C%A(B $B$r%]%C%W$7$?$+5-21$7$F$*$j!$0lEY%]%C%W$7$?%U%!%$%k$r:F$S%W%C%7%e$7!$%G%#(B $B%l%/%H%j%D%j!<$r%Q%C%A$K$h$kJQ99$,$J$5$l$?>uBV$KLa$9$3$H$,$G$-$k!%:G$b=E(B $BMW$J$3$H$O!$$$$D$G$b(B``refresh''$B%3%^%s%I$r<B9T$7$F0lHV?7$7$/E,MQ$5$l$?%Q%C(B $B%A$r99?7$G$-$k$3$H$G$"$k!%$3$l$O$9$J$o$A!$%Q%C%A$NE,MQ$5$l$?>uBV$H!$%Q%C(B $B%A$=$l<+BN$r$$$D$G$b99?7$G$-$k$H$$$&$3$H$G$"$k!%(B %Quilt knows nothing about revision control tools, so it works equally %well on top of an unpacked tarball or a Subversion working copy. quilt$B$O%j%S%8%g%s4IM}%D!<%k$K$D$$$F$OA4$/4XCN$7$J$$$?$a!$E83+$5$l$?(Btar$B%\!<(B $B%k>e$G$b!$(BSubversion$B$N%o!<%-%s%0%3%T!<>e$G$bF1MM$KF0:n$9$k!%(B %\subsection{From patchwork quilt to Mercurial Queues} \subsection{patchwork quilt$B$+$i(BMercurial Queues$B$X(B} \label{sec:mq:quilt-mq} %In mid-2005, Chris Mason took the features of quilt and wrote an %extension that he called Mercurial Queues, which added quilt-like %behaviour to Mercurial. 2005$BG/$NCf:"(BChris Mason$B$O!$(Bquilt$B$N5!G=$r<h$jF~$l$F!$(BMercurial$B$K(Bquilt$B$N$h(B $B$&$JF0:n$rDI2C$9$k(BMercurial Queues$B$H$$$&%(%/%9%F%s%7%g%s$r=q$$$?!%(B %The key difference between quilt and MQ is that quilt knows nothing %about revision control systems, while MQ is \emph{integrated} into %Mercurial. Each patch that you push is represented as a Mercurial %changeset. Pop a patch, and the changeset goes away. quilt$B$H(BMQ$B$N0c$$$O!$(Bquilt$B$O%j%S%8%g%s4IM}%7%9%F%`$K$D$$$F2?$b4XCN$7$J$$$N(B $B$KBP$7$F!$(BMQ$B$O(BMercurial$B$KE}9g$5$l$F$$$k$3$H$G$"$k!%%W%C%7%e$7$?8D!9$N%Q%C(B $B%A$O(BMercurial$B$N%A%'%s%8%;%C%H$H$7$FI=8=$5$l$k!%%Q%C%A$r%]%C%W$9$k$H!$%A%'(B $B%s%8%;%C%H$O>C$($F$J$/$J$k!%(B %Because quilt does not care about revision control tools, it is still %a tremendously useful piece of software to know about for situations %where you cannot use Mercurial and MQ. quilt$B$O%j%S%8%g%s4IM}%D!<%k$HL54X78$KMxMQ2DG=$J$?$a!$(BMercurial$B$H(BMQ$B$,;H$((B $B$J$$>u67$G$O0MA3$H$7$FHs>o$KM-1W$J%D!<%k$G$"$k$3$H$O5-21$KN1$a$F$*$/$Y$-(B $B$G$"$k!%(B %\section{The huge advantage of MQ} \section{MQ$B$NBg$-$JMxE@(B} %I cannot overstate the value that MQ offers through the unification of %patches and revision control. MQ$B$,%Q%C%A$H%j%S%8%g%s%3%s%H%m!<%k$NE}9g$K$h$C$F$b$?$i$92ACM$r8XD%$9$k$o(B $B$1$K$O$$$+$J$$!%(B %A major reason that patches have persisted in the free software and %open source world---in spite of the availability of increasingly %capable revision control tools over the years---is the \emph{agility} %they offer. $B;~$rDI$&Kh$K%j%S%8%g%s%3%s%H%m!<%k%D!<%k$NMxMQ$,9-$,$C$F$$$k$K$b$+$+$o$i(B $B$:!$%U%j!<%=%U%H$H%*!<%W%s%=!<%9$N@$3&$K%Q%C%A$,B8:_$9$kBg$-$JM}M3$O$=$N(B \emph{$B5!IR$5(B}$B$K$"$k!%(B %Traditional revision control tools make a permanent, irreversible %record of everything that you do. While this has great value, it's %also somewhat stifling. If you want to perform a wild-eyed %experiment, you have to be careful in how you go about it, or you risk %leaving unneeded---or worse, misleading or destabilising---traces of %your missteps and errors in the permanent revision record. $BEAE}E*$J%j%S%8%g%s%3%s%H%m!<%k%D!<%k$O!$9T$J$C$?A`:n$N1J5WE*$GIT2D5UE*$J(B $B5-O?$r;D$9!%$3$l$K$OBg$-$J2ACM$,$"$k0lJ}$G!$5g6~$K46$8$k$3$H$b$"$k!%$b$7(B $B2a7c$J<B83$r$9$k$N$G$"$l$P!$$I$N$h$&$K?J$a$k$+?5=E$K$9$kI,MW$,$"$k!%$5$b(B $B$J$1$l$P!$ITMW$J!$$"$k$$$O8m2r$r>7$$$?$j!$0BDj@-$rB;$J$&%H%l!<%9$H%(%i!<(B $B$r1J5WE*$J%j%S%8%g%sMzNr$K;D$9$3$H$K$J$k!%(B %By contrast, MQ's marriage of distributed revision control with %patches makes it much easier to isolate your work. Your patches live %on top of normal revision history, and you can make them disappear or %reappear at will. If you don't like a patch, you can drop it. If a %patch isn't quite as you want it to be, simply fix it---as many times %as you need to, until you have refined it into the form you desire. $BBP>NE*$K!$(BMQ$B$K$h$kJ,;6%j%S%8%g%s%3%s%H%m!<%k$H%Q%C%A$N7k9g$O!$:n6H$r3VN%(B $B$9$k$3$H$rMZ$+$KMF0W$K$9$k!%%Q%C%A$ODL>o$N%j%S%8%g%sMzNr$N>e$K>h$C$F$*$j!$(B $BK>$`$h$&$K>CLG$5$;$?$j:F8=$5$;$k$3$H$,$G$-$k!%%Q%C%A$r5$$KF~$i$J$1$l$P!$(B $B$3$l$r4~5Q$9$k$3$H$b$G$-$k!%%Q%C%A$,$"$J$?$NK>$`$h$&$J$b$N$G$J$1$l$P!$4u(B $BK>DL$j$K$J$k$^$G2?EY$G$b4JC1$K=$@5$9$k$3$H$,$G$-$k!%(B %As an example, the integration of patches with revision control makes %understanding patches and debugging their effects---and their %interplay with the code they're based on---\emph{enormously} easier. %Since every applied patch has an associated changeset, you can use %\hgcmdargs{log}{\emph{filename}} to see which changesets and patches %affected a file. You can use the \hgext{bisect} command to %binary-search through all changesets and applied patches to see where %a bug got introduced or fixed. You can use the \hgcmd{annotate} %command to see which changeset or patch modified a particular line of %a source file. And so on. $BNc$($P!$%j%S%8%g%s%3%s%H%m!<%k$X$N%Q%C%A$NE}9g$O!$%Q%C%A$rM}2r$7!$$=$N1F(B $B6A!$0M$C$FN)$D%Y!<%9%3!<%I$H$NAj8_:nMQ$r%G%P%C%0$9$k$3$H$r2DG=$K$9$k!%E,(B $BMQ$5$l$?%Q%C%A$O!$4XO"$E$1$i$l$?%A%'%s%8%;%C%H$r;}$D$?$a!$(B \hgcmdargs{log}{\emph{filename}}$B$K$h$C$F$I$N%A%'%s%8%;%C%H$H%Q%C%A$,%U%!(B $B%$%k$K1F6A$rM?$($F$$$k$+D4$Y$k$3$H$,$G$-$k!%(B\hgext{bisect}$B%3%^%s%I$GA4$F(B $B$N%A%'%s%8%;%C%H$HE,MQ$5$l$?%Q%C%A$KBP$7$F%P%$%J%j%5!<%A$r9T$J$$!$$I$3$G(B $B%P%0$,:.F~$7$?$+!$$"$k$$$O=$@5$5$l$?$+$rD4$Y$k$3$H$,$G$-$k!%(B \hgcmd{annotate}$B%3%^%s%I$G$I$N%A%'%s%8%;%C%H$+%Q%C%A$,%=!<%9%U%!%$%k$NFC(B $BDj$N9T$rJQ99$7$?$+8+$k$3$H$,$G$-$k!%(B %\section{Understanding patches} \section{$B%Q%C%A$H$O2?$+(B} \label{sec:mq:patch} %Because MQ doesn't hide its patch-oriented nature, it is helpful to %understand what patches are, and a little about the tools that work %with them. MQ$B$O%Q%C%A;X8~$G$"$k@-<A$r1#JC$7$F$$$J$$$N$G!$%Q%C%A$,2?$G$"$k$+!$%D!<%k(B $B$,%Q%C%A$r$I$&07$&$+$rM}2r$9$k$N$O$?$d$9$$!%(B %The traditional Unix \command{diff} command compares two files, and %prints a list of differences between them. The \command{patch} command %understands these differences as \emph{modifications} to make to a %file. Take a look at figure~\ref{ex:mq:diff} for a simple example of %these commands in action. Unix$B$NEAE}E*$J(B\command{diff}$B%3%^%s%I$O(B2$B$D$N%U%!%$%k$rHf3S$7!$:9J,$N%j%9(B $B%H$r=PNO$9$k!%(B\command{patch}$B%3%^%s%I$O$3$N:9J,$rJQ99$H2r<a$7!$%U%!%$%k(B $B$K5Z$\$9!%?^(B~\ref{ex:mq:diff}$B$K$3$l$i$N%3%^%s%I$NF0:n$r<($9!%(B \begin{figure}[ht] \interaction{mq.dodiff.diff} % \caption{Simple uses of the \command{diff} and \command{patch} % commands} \caption{\command{diff}$B%3%^%s%I$H(B\command{patch}$B%3%^%s%I$NC1=c$J;HMQNc(B} \label{ex:mq:diff} \end{figure} %The type of file that \command{diff} generates (and \command{patch} %takes as input) is called a ``patch'' or a ``diff''; there is no %difference between a patch and a diff. (We'll use the term ``patch'', %since it's more commonly used.) \command{diff}$B$,@8@.$9$k!J$^$?(B\command{patch}$B$,F~NO$K<h$k!K%U%!%$%k$N<o(B $BN`$O(B``patch''$B$^$?$O(B``diff''$B$H8F$P$l!$$3$l$i$N4V$K$O0c$$$O$J$$!%!J0J2<$G(B $B$O!$$h$jB?$/;H$o$l$F$$$k(B``patch''$B$H$$$&8@MU$r;H$&$3$H$K$9$k!%!K(B %A patch file can start with arbitrary text; the \command{patch} %command ignores this text, but MQ uses it as the commit message when %creating changesets. To find the beginning of the patch content, %\command{patch} searches for the first line that starts with the %string ``\texttt{diff~-}''. $B%Q%C%A%U%!%$%k$OG$0U$N%F%-%9%H$G;O$^$k!%(B\command{patch}$B%3%^%s%I$O$3$N%F(B $B%-%9%H$rL5;k$9$k$,!$(BMQ$B$O%A%'%s%8%;%C%H$r:n$k:]$N%3%_%C%H%a%C%;!<%8$H$7$F(B $BMxMQ$9$k!%%Q%C%AFbMF$N@hF,$r8+$D$1$k$?$a$K(B\command{patch}$B$O(B ``\texttt{diff~-}''$B$G;O$^$k:G=i$N9T$r%5!<%A$9$k!%(B %MQ works with \emph{unified} diffs (\command{patch} can accept several %other diff formats, but MQ doesn't). A unified diff contains two %kinds of header. The \emph{file header} describes the file being %modified; it contains the name of the file to modify. When %\command{patch} sees a new file header, it looks for a file with that %name to start modifying. MQ\emph{unified} diffs$B7A<0$r;H$&!%!J(B\command{patch}$B%3%^%s%I$O$3$l0J30$K2?(B $B<oN`$+$N(Bdiff$B%U%)!<%^%C%H$r<u$1IU$1$k$,!$(BMQ$B$G$OMxMQ$G$-$J$$!%!K(Bunified diff$B$O(B2$B<oN`$N%X%C%@$r;}$D!%(B\emph{file $B%X%C%@(B}$B$OJQ99$5$l$F$$$k%U%!%$%k$r5-(B $B=R$9$k!%(B\command{patch}$B%3%^%s%I$O!$?7$7$$%U%!%$%k%X%C%@$r8+$D$1$k$H!$$=$3(B $B$K5-=R$5$l$F$$$k%U%!%$%kL>$r;}$D%U%!%$%k$rC5$9!%(B %After the file header comes a series of \emph{hunks}. Each hunk starts %with a header; this identifies the range of line numbers within the file %that the hunk should modify. Following the header, a hunk starts and %ends with a few (usually three) lines of text from the unmodified file; %these are called the \emph{context} for the hunk.If %there's only a small amount of context between successive hunks, %\command{diff} doesn't print a new hunk header; it just runs the hunks %together, with a few lines of context between modifications. $B%U%!%$%k%X%C%@$N8e$K$O0lO"$N(B\emph{hunks}$B$,B3$/!%3F!9$N(Bhunk$B$O%X%C%@$G;O$^(B $B$k!%$3$N%X%C%@$O%U%!%$%kFb$G(Bhunk$B$,2~JQ$9$Y$-9THV9f$NHO0O$r<1JL$9$k$N$K;H(B $B$o$l$k!%%X%C%@$KB3$-!$(Bhunk$B$O?t9T!JDL>o(B3$B!K$N2~JQ$5$l$F$$$J$$%U%!%$%k$+$i$N(B $B9T$,$"$k!%$3$l$i$O(Bhunk$B$N(B\emph{$B%3%s%F%-%9%H(B}$B$H8F$P$l$k!%$b$7O"B3$9$k(Bhunk$B$N(B $B4V$K%3%s%F%-%9%H$,>/$7$7$+$J$1$l$P!$(B\command{diff}$B$O?7$?$J(Bhunk$B%X%C%@$r=P(B $BNO$;$:!$3F!9$N(Bhunk$B$H4V$N%3%s%F%-%9%H$r9g$o$;$F=PNO$9$k!%(B %Each line of context begins with a space character. Within the hunk, %a line that begins with ``\texttt{-}'' means ``remove this line,'' %while a line that begins with ``\texttt{+}'' means ``insert this %line.'' For example, a line that is modified is represented by one %deletion and one insertion. $B%3%s%F%-%9%H$N3F9T$O!$6uGrJ8;z$G;O$^$k!%(Bhunk$BFb$G$O9T$O(B``\texttt{-}''$B$G;O(B $B$^$k!%$3$l$O(B``$B$3$N9T$r:o=|$;$h(B''$B$r0UL#$9$k!%(B $B0lJ}!$(B``\texttt{+}''$B$G;O$^$k9T$O!$(B``$B$3$N9T$rA^F~$;$h(B''$B$r0UL#$9$k!%Nc$r5s(B $B$2$k$H!$JQ99$5$l$?9T$O(B1$B$D$N:o=|$H(B1$B$D$NA^F~$GI=$5$l$k!%(B %We will return to some of the more subtle aspects of patches later (in %section~\ref{sec:mq:adv-patch}), but you should have enough information %now to use MQ. $B%Q%C%A$N:3:Y$JE@$K$D$$$F$O8e$G!J(B~\ref{sec:mq:adv-patch}$B!K$^$??($l$k$,!$(B $B$3$l$^$G$G!$(BMQ$B$r;H$&$N$K==J,$J>pJs$O=R$Y$?!%(B %\section{Getting started with Mercurial Queues} \section{Mercurial Queues$B$r;H$C$F$_$k(B} \label{sec:mq:start} %Because MQ is implemented as an extension, you must explicitly enable %before you can use it. (You don't need to download anything; MQ ships %with the standard Mercurial distribution.) To enable MQ, edit your %\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. MQ$B$O%(%/%9%F%s%7%g%s$H$7$F<BAu$5$l$F$$$k$N$G!$;H$&A0$KL@<(E*$KM-8z$K$9$k(B $BI,MW$,$"$k!%!J2?$b%@%&%s%m!<%I$9$kI,MW$O$J$$!%(BMQ$B$ODL>o$N(BMercurial$B$KF1:-$5(B $B$l$F$$$k!K(BMQ$B$rM-8z$K$9$k$K$O(B\tildefile{.hgrc}$B%U%!%$%k$rJT=8$7!$(B $B?^(B~\ref{ex:mq:config}$B$N$h$&$K@_Dj$rDI2C$9$k!%(B \begin{figure}[ht] \begin{codesample4} [extensions] hgext.mq = \end{codesample4} \label{ex:mq:config} % \caption{Contents to add to \tildefile{.hgrc} to enable the MQ % extension} \caption{MQ$B%(%/%9%F%s%7%g%s$rM-8z$K$9$k$?$a$K(B\tildefile{.hgrc}$B$KDI2C$9$kFbMF(B} \end{figure} %Once the extension is enabled, it will make a number of new commands %available. To verify that the extension is working, you can use %\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see %the example in figure~\ref{ex:mq:enabled}. $B%(%/%9%F%s%7%g%s$,M-8z2=$5$l$k$H0lO"$N%3%^%s%I$,MxMQ2DG=$K$J$k!%%(%/%9%F(B $B%s%7%g%s$,M-8z$G$"$k$3$H$r3NG'$9$k$?$a$K$O!$(B\hgcmd{help}$B$G(B \hgxcmd{mq}{qinit}$B$,$"$k$3$H$r3NG'$9$k!%?^(B~\ref{ex:mq:enabled}$B$NNc$r;2>H(B $B$5$l$?$$!%(B \begin{figure}[ht] \interaction{mq.qinit-help.help} % \caption{How to verify that MQ is enabled} \caption{MQ$B$,M-8z$G$"$k$3$H$N3NG'K!(B} \label{ex:mq:enabled} \end{figure} %You can use MQ with \emph{any} Mercurial repository, and its commands %only operate within that repository. To get started, simply prepare %the repository using the \hgxcmd{mq}{qinit} command (see %figure~\ref{ex:mq:qinit}). This command creates an empty directory %called \sdirname{.hg/patches}, where MQ will keep its metadata. As %with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing %if it succeeds. MQ$B$O(B\emph{$B$"$i$f$k(B}Mercurial$B%j%]%8%H%j$G;H$&$3$H$,$G$-!$$=$N%3%^%s%I$O3F!9(B $B$N%j%]%8%H%j$NCf$K$@$1:nMQ$9$k!%;O$a$k$?$a$K(B\hgxcmd{mq}{qinit}$B%3%^%s%I$G(B $B%j%]%8%H%j$rMQ0U$9$k!%!J?^(B~\ref{ex:mq:qinit}$B$r;2>H!K(B $B$3$N%3%^%s%I$O(BMQ$B$,%a(B $B%?%G!<%?$rJ]B8$9$k$?$a$N(B\sdirname{.hg/patches}$B$H$$$&L>A0$N6u$N%G%#%l%/%H(B $B%j$r:n@.$9$k!%B>$N(BMercurial$B%3%^%s%I$HF1MM$K!$(B\hgxcmd{mq}{qinit}$B%3%^%s%I(B $B$b@.8y$9$k$H2?$bI=<($7$J$$!%(B \begin{figure}[ht] \interaction{mq.tutorial.qinit} % \caption{Preparing a repository for use with MQ} \caption{MQ$B$r;H$&$?$a$K%j%]%8%H%j$r=`Hw$9$k(B} \label{ex:mq:qinit} \end{figure} \begin{figure}[ht] \interaction{mq.tutorial.qnew} % \caption{Creating a new patch} \caption{$B?7$7$$%Q%C%A$N:n@.(B} \label{ex:mq:qnew} \end{figure} %\subsection{Creating a new patch} \subsection{$B?7$7$$%Q%C%A$N:n@.(B} %To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This %command takes one argument, the name of the patch to create. MQ will %use this as the name of an actual file in the \sdirname{.hg/patches} %directory, as you can see in figure~\ref{ex:mq:qnew}. $B?7$7$$%Q%C%A$r07$&;~$O(B\hgxcmd{mq}{qnew}$B%3%^%s%I$r;H$&!%$3$N%3%^%s%I$O:n@.(B $B$5$l$k%Q%C%A$NL>A0$H$7$F0z?t$r(B1$B$D<h$k!%?^(B~\ref{ex:mq:qnew}$B$N$h$&$K!$(BMQ$B$O(B $B$3$l$r(B\sdirname{.hg/patches} $B%G%#%l%/%H%jFb$N<B:]$N%U%!%$%kL>$H$7$FMxMQ$9(B $B$k!%(B %Also newly present in the \sdirname{.hg/patches} directory are two %other files, \sfilename{series} and \sfilename{status}. The %\sfilename{series} file lists all of the patches that MQ knows about %for this repository, with one patch per line.Mercurial uses the %\sfilename{status} file for internal book-keeping; it tracks all of the %patches that MQ has \emph{applied} in this repository. \sdirname{.hg/patches}$B%G%#%l%/%H%j$NCf$K$O!$(B\sfilename{series}$B$H(B \sfilename{status}$B$H$$$&(B2$B$D$N%U%!%$%k$b?7$7$/:n$i$l$k!%(B \sfilename{series}$B$U$!$$$k$O(BMQ$B$,4XCN$9$k!$$3$N%j%]%8%H%jFb$NA4$F$N%Q%C%A(B $B$N%j%9%H$,$"$j!$0l9T$K0l$D$N%Q%C%A$,5-=R$5$l$F$$$k!%(BMercurial$B$O(B \sfilename{status}$B%U%!%$%k$rFbIt$N4IM}$KMQ$$$k!%$3$N%U%!%$%k$O%j%]%8%H%j(B $BFb$G(BMQ$B$,E,MQ$7$?A4$F$N%Q%C%A$,5-O?$5$l$F$$$k!%(B %\begin{note} % You may sometimes want to edit the \sfilename{series} file by hand; % for example, to change the sequence in which some patches are % applied. However, manually editing the \sfilename{status} file is % almost always a bad idea, as it's easy to corrupt MQ's idea of what % is happening. %\end{note} \begin{note} $BNc$($P!$J#?t$N%Q%C%A$,E,MQ$5$l$k<j=g$rJQ99$9$k$J$I$NL\E*$G(B \sfilename{series}$B%U%!%$%k$r<j$GJT=8$7$?$/$J$k$3$H$,$"$k$+$b$7$l$J$$!%(B $B$7$+$7(B\sfilename{status}$B$r<j$GJT=8$9$k$N$O$[$H$s$I$N>l9gNI$/$J$$9M$($G!$(B MQ$B$N>uBVDI@W$r4JC1$K68$o$;$F$7$^$&!%(B \end{note} %Once you have created your new patch, you can edit files in the %working directory as you usually would. All of the normal Mercurial %commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as %they did before. $B?7$7$$%Q%C%A$r:n$C$?8e!$%o!<%-%s%0%G%#%l%/%H%jFb$N%U%!%$%k$rDL>oDL$jJT=8(B $B$9$k$3$H$,$G$-$k!%(B\hgcmd{diff}$B$d(B\hgcmd{annotate}$B$N$h$&$JA4$F$NDL>o$N(B Mercurial$B%3%^%s%I$,A4$/F1$8$h$&$K;H$($k!%(B %\subsection{Refreshing a patch} \subsection{$B%Q%C%A$N%j%U%l%C%7%e(B} %When you reach a point where you want to save your work, use the %\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch %you are working on. This command folds the changes you have made in %the working directory into your patch, and updates its corresponding %changeset to contain those changes. $B:n6HFbMF$r%;!<%V$9$k%]%$%s%H$K:9$7$+$+$C$?$i!$(B\hgxcmd{mq}{qrefresh}$B%3%^(B $B%s%I$r;H$C$F!J?^(B~\ref{ex:mq:qnew}$B!K:n6HCf$N%Q%C%A$r99?7$9$k!%$3$N%3%^%s(B $B%I$O%o!<%-%s%0%G%#%l%/%H%j$N:9J,$r%Q%C%A$K<h$j9~$_!$%A%'%s%8%;%C%H$,JQ99(B $B$r4^$`$h$&$K99?7$9$k!%(B \begin{figure}[ht] \interaction{mq.tutorial.qrefresh} % \caption{Refreshing a patch} \caption{$B%Q%C%A$N%j%U%l%C%7%e(B} \label{ex:mq:qrefresh} \end{figure} %You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way %to ``checkpoint'' your work. Refresh your patch at an opportune %time; try an experiment; and if the experiment doesn't work out, %\hgcmd{revert} your modifications back to the last time you refreshed. \hgxcmd{mq}{qrefresh}$B$O$$$D$G$b9%$-$J;~$K<B9T$G$-!$:n6H$N>uBVJ]B8$r$9$k(B $B$N$K$b;H$($k!%%Q%C%A$N%j%U%l%C%7%e$OET9g$N$h$$;~$K9T$($P$h$$!%<B83E*$J%3!<(B $B%I$rF0$+$9>l9g!$;vA0$K%j%U%l%C%7%e$r$7$F$*$1$P!$<B83$N7k2L%3!<%I$,F0$+$J(B $B$/$F$b!$(B\hgcmd{revert}$B$9$l$P!$JQ99$O85$KLa$k!%(B \begin{figure}[ht] \interaction{mq.tutorial.qrefresh2} % \caption{Refresh a patch many times to accumulate changes} \caption{$B%Q%C%A$N%j%U%l%C%7%e$GJQ99$rC_@Q$9$k(B} \label{ex:mq:qrefresh2} \end{figure} %\subsection{Stacking and tracking patches} \subsection{$B%Q%C%A$N%9%?%C%/$HDI@W(B} %Once you have finished working on a patch, or need to work on another, %you can use the \hgxcmd{mq}{qnew} command again to create a new patch. %Mercurial will apply this patch on top of your existing patch. See %figure~\ref{ex:mq:qnew2} for an example. Notice that the patch %contains the changes in our prior patch as part of its context (you %can see this more clearly in the output of \hgcmd{annotate}). $B%Q%C%A$X$N:n6H$,=*N;$7$?$j!$B>$N:n6H$r$r$9$kI,MW$,$"$k>l9g!$(B \hgxcmd{mq}{qnew}$B%3%^%s%I$r<B9T$7!$?7$7$$%Q%C%A$r:n$k$3$H$,$G$-$k!%(B Mercurial$B$O$3$N%Q%C%A$r4{B8$N%Q%C%A$N>e$+$iE,MQ$9$k!%?^(B~\ref{ex:mq:qnew2}$B$r(B $B;2>H$N$3$H!%%Q%C%A$O@h9T$9$k%Q%C%A$NJQ99$r%3%s%F%-%9%H$H$7$F;}$D!%!J(B\hgcmd{annotate} $B$N=PNO$G$h$jL@NF$K3NG'$9$k$3$H$,$G$-$k!%!K(B \begin{figure}[ht] \interaction{mq.tutorial.qnew2} % \caption{Stacking a second patch on top of the first} \caption{$B:G=i$N%Q%C%A$N>e$K(B2$BHVL\$N%Q%C%A$r%9%?%C%/$9$k(B} \label{ex:mq:qnew2} \end{figure} %So far, with the exception of \hgxcmd{mq}{qnew} and %\hgxcmd{mq}{qrefresh}, we've been careful to only use regular Mercurial %commands. However, MQ provides many commands that are easier to use %when you are thinking about patches, as illustrated in %figure~\ref{ex:mq:qseries}: $B$3$l$^$G$O(B\hgxcmd{mq}{qnew}$B$H(B\hgxcmd{mq}{qrefresh}$B$r=|$$$F!$DL>o$N(B Mercurial$B%3%^%s%I$N$_$r;H$&$h$&$KCm0U$7$F$-$?!%$7$+$7(BMQ$B$O%Q%C%A$r07$&>l(B $B9g!$?^(B~\ref{ex:mq:qseries}$B$K<($9$h$&$J$h$j4JC1$J%3%^%s%I$rMQ0U$7$F$$$k!%(B %\begin{itemize} %\item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows % about in this repository, from oldest to newest (most recently % \emph{created}). %\item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has % \emph{applied} in this repository, again from oldest to newest (most % recently applied). %\end{itemize} \begin{itemize} \item \hgxcmd{mq}{qseries}$B%3%^%s%I$O(BMQ$B$,4XCN$9$k%j%]%8%H%jFb$N%Q%C%AA4$F(B $B$r8E$$$b$N$+$i?7$7$/(B\emph{$B:n@.$5$l$?(B}$B$b$N$N=g$K%j%9%HI=<($9$k!%(B \item \hgxcmd{mq}{qapplied}$B%3%^%s%I$O(BMQ$B$,(B\emph{$BE,MQ$7$?(B}$B%j%]%8%H%jFb$N(B $B%Q%C%AA4$F$r$d$O$j8E$$$b$N$+$i?7$7$/(B\emph{$B:n@.$5$l$?(B}$B$b$N$N=g$K%j%9%HI=<($9$k!%(B \end{itemize} \begin{figure}[ht] \interaction{mq.tutorial.qseries} % \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and % \hgxcmd{mq}{qapplied}} \caption{\hgxcmd{mq}{qseries}$B$H(B\hgxcmd{mq}{qapplied}$B$G%Q%C%A%9%?%C%/$r(B $BD4$Y$k(B} \label{ex:mq:qseries} \end{figure} %\subsection{Manipulating the patch stack} \subsection{$B%Q%C%A%9%?%C%/$NA`:n(B} %The previous discussion implied that there must be a difference %between ``known'' and ``applied'' patches, and there is. MQ can %manage a patch without it being applied in the repository. $B$3$l$^$G$N5DO@$O(B``known''$B$H(B``applied''$B%Q%C%A$K0c$$$,$"$k$3$H$r0EL[$K2>Dj(B $B$7$F$$$?!%(BMQ$B$O:90[$N$J$$%Q%C%A$r%j%]%8%H%j$KBP$7$FE,MQ$9$k$3$H$b$G$-$k!%(B %An \emph{applied} patch has a corresponding changeset in the %repository, and the effects of the patch and changeset are visible in %the working directory. You can undo the application of a patch using %the \hgxcmd{mq}{qpop} command. MQ still \emph{knows about}, or manages, a %popped patch, but the patch no longer has a corresponding changeset in %the repository, and the working directory does not contain the changes %made by the patch. Figure~\ref{fig:mq:stack} illustrates the %difference between applied and tracked patches. \emph{$BE,MQ$5$l$?(B}$B%Q%C%A$O%j%]%8%H%jFb$KBP1~$9$k%A%'%s%8%;%C%H$r;}$A!$%Q%C(B $B%A$N8z2L$H%A%'%s%8%;%C%H$O%o!<%-%s%0%G%#%l%/%H%jFb$G8+$k$3$H$,$G$-$k!%%Q%C(B $B%A$NE,MQ$O(B\hgxcmd{mq}{qpop}$B%3%^%s%I$G<h$j>C$9$3$H$,$G$-$k!%%]%C%W$5$l$?%Q%C(B $B%A$OBP1~$9$k%A%'%s%8%;%C%H$r;}$?$:!$JQ99$b%o!<%-%s%0%G%#%l%/%H%j$K;D$C$F(B $B$$$J$$$,!$(BMQ$B$O%]%C%W$5$l$?%Q%C%A$r0MA3$H$7$F5-21$7!$4IM}$7$F$$$k!%(B $B?^(B~\ref{fig:mq:stack}$B$OE,MQ$5$l$?%Q%C%A$H4IM}$5$l$F$$$k%Q%C%A$N0c$$$r<((B $B$9!%(B \begin{figure}[ht] \centering \grafix{mq-stack} % \caption{Applied and unapplied patches in the MQ patch stack} \caption{MQ$B%Q%C%A%9%?%C%/$NCf$NE,MQ$5$l$?%Q%C%A$HE,MQ$5$l$J$$%Q%C%A(B} \label{fig:mq:stack} \end{figure} %You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush} %command. This creates a new changeset to correspond to the patch, and %the patch's changes once again become present in the working %directory. See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop} %and \hgxcmd{mq}{qpush} in action. Notice that once we have popped a patch %or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while %that of \hgxcmd{mq}{qapplied} has changed. $BE,MQ$r30$7$?%Q%C%A$d%]%C%W$7$?%Q%C%A$r(B\hgxcmd{mq}{qpush}$B%3%^%s%I$G:FE,MQ(B $B$9$k$3$H$,$G$-$k!%$3$N%3%^%s%I$O!$%Q%C%A$KBP1~$7$??7$7$$%A%'%s%8%;%C%H$r(B $B:n$j!$%Q%C%A$K$h$kJQ99$O$b$&0lEY%o!<%-%s%0%G%#%l%/%H%j$K8=$l$k!%(B \hgxcmd{mq}{qpop}$B$H(B\hgxcmd{mq}{qpush}$B$N;HMQNc$r?^(B~\ref{ex:mq:qpop}$B$K<($9!%(B 1$B$D$^$?$OJ#?t$N%Q%C%A$r%]%C%W$9$k$H(B\hgxcmd{mq}{qapplied}$B$N=PNO$OJQ2=$9$k(B $B$,!$(B\hgxcmd{mq}{qseries}$B$N=PNO$OF1$8$^$^;D$k$N$KCm0U$5$l$?$$!%(B \begin{figure}[ht] \interaction{mq.tutorial.qpop} % \caption{Modifying the stack of applied patches} \caption{$BE,MQ$5$l$?%Q%C%A$N%9%?%C%/$rJQ99$9$k(B} \label{ex:mq:qpop} \end{figure} %\subsection{Pushing and popping many patches} \subsection{$B%Q%C%A$N%W%C%7%e$H%]%C%W(B} %While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at %a time by default, you can push and pop many patches in one go. The %\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all %unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop} %causes it to pop all applied patches. (For some more ways to push and %pop many patches, see section~\ref{sec:mq:perf} below.) \hgxcmd{mq}{qpush}$B$H(B\hgxcmd{mq}{qpop}$B$O0lEY$K3F!9$N%Q%C%A0l$D$:$D$rA`:n$9(B $B$k!J$3$l$O%G%U%)%k%HF0:n$G$"$k!K0lJ}!$J#?t$N%Q%C%A$r0lEY$K%]%C%W!&%W%C%7%e(B $B$9$kA`:n$b$"$k!%(B\hgxcmd{mq}{qpush}$B%3%^%s%I$N(B\hgxopt{mq}{qpush}{-a}$B%*%W%7%g(B $B%s$O!$L$E,MQ$N%Q%C%AA4BN$r%W%C%7%e$7!$(B\hgxcmd{mq}{qpop}$B%3%^%s%I$N(B \hgxopt{mq}{qpop}{-a} $B%*%W%7%g%s$OE,MQ:Q$_$N%Q%C%AA4BN$r%]%C%W$9$k!%(B $B!JB>$NJ#?t$N%Q%C%A$rF1;~$K%W%C%7%e!&%]%C%W$9$kJ}K!$K$D$$$F$O2<(B $B$N(B~\ref{sec:mq:perf}$B$r;2>H$N$3$H!K(B \begin{figure}[ht] \interaction{mq.tutorial.qpush-a} % \caption{Pushing all unapplied patches} \caption{$BE,MQ$5$l$F$$$J$$%Q%C%A$rA4$F%W%C%7%e$9$k(B} \label{ex:mq:qpush-a} \end{figure} %\subsection{Safety checks, and overriding them} \subsection{$B0BA4@-%A%'%C%/$H%*!<%P%i%$%I(B} %Several MQ commands check the working directory before they do %anything, and fail if they find any modifications. They do this to %ensure that you won't lose any changes that you have made, but not yet %incorporated into a patch.Figure~\ref{ex:mq:add} illustrates this; %the \hgxcmd{mq}{qnew} command will not create a new patch if there are %outstanding changes, caused in this case by the \hgcmd{add} of %\filename{file3}. $B$$$/$D$+$N(BMQ$B%3%^%s%I$O!$<B9T;~$K$^$:%o!<%-%s%0%G%#%l%/%H%j$r%A%'%C%/$7!$(B $BJQ99$,$J$5$l$F$$$?$i=*N;$9$k$h$&$K$J$C$F$$$k!%$3$l$O!$%f!<%6$N$^$@%Q%C%A(B $B$K<h$j9~$^$l$F$$$J$$JQ99$,<:$o$l$J$$$h$&$K$9$k$?$a$G$"$k!%(B $B?^(B~\ref{ex:mq:add}$B$O$3$l$r@bL@$7$?$b$N$G!$(B\hgxcmd{mq}{qnew}$B%3%^%s%I$O8IN)(B $B$7$?JQ99$,$"$k;~$K?7$?$J%Q%C%A$r@8@.$7$J$$!%$3$NNc$G$O!$JQ99$O(B \hgcmd{add}$B$K$h$k(B\filename{file3}$B$NDI2C$K$h$C$F@8$^$l$F$$$k!%(B \begin{figure}[ht] \interaction{mq.tutorial.add} % \caption{Forcibly creating a patch} \caption{$B%Q%C%A$N6/@)E*$J@8@.(B} \label{ex:mq:add} \end{figure} %Commands that check the working directory all take an ``I know what %I'm doing'' option, which is always named \option{-f}. The exact %meaning of \option{-f} depends on the command. For example, %\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding %changes into the new patch it creates, but %\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any %files affected by the patch that it is popping. Be sure to read the %documentation for a command's \option{-f} option before you use it! $B%o!<%-%s%0%G%#%l%/%H%j$N%A%'%C%/$r9T$J$&%3%^%s%I$OA4$F!$>e5i<T8~$1$N6/@)(B $B%*%W%7%g%s(B\option{-f}$B$r;}$C$F$$$k!%(B\option{-f}$B$N87L)$J0UL#$O!$%3%^%s%I$K(B $B$h$C$F0[$J$k!%Nc$($P(B\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}}$B$O8IN)$7$?JQ(B $B99$r?7$7$$%Q%C%A$K<h$j9~$`$H$$$&0UL#$@$,!$(B \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}}$B$O!$%]%C%W$9$k%Q%C%A$K$h$k$"$i$f(B $B$k%U%!%$%k$X$NJQ99$r<h$j>C$9$H$$$&0UL#$K$J$k!%(B\option{-f}$B%*%W%7%g%s$r;H(B $B$&;~$OI,$:;vA0$K%3%^%s%I$N%I%-%e%a%s%H$rFI$s$G3NG'$9$k$h$&$K$7$FM_$7$$!%(B %\subsection{Working on several patches at once} \subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} %The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} %applied patch. This means that you can suspend work on one patch (by %refreshing it), pop or push to make a different patch the top, and %work on \emph{that} patch for a while. \hgxcmd{mq}{qrefresh}$B%3%^%s%I$O(B\emph{$B:G$b>e(B}$B$KE,MQ$5$l$?%Q%C%A$KBP$7$F%j(B $B%U%l%C%7%e$r9T$J$&!%$3$l$O%j%U%l%C%7%e$K$h$C$F(B1$B$D$N%Q%C%A$K8=:_$N:n6H$r%5(B $B%9%Z%s%I$7$?$j!$JL$N%H%C%W%Q%C%A$d0l;~E*$K:n6H$9$k$?$a%Q%C%A$r:n$k$?$a$K(B $B%]%C%W$d%W%C%7%e$,$G$-$k$H$$$&$3$H$r0UL#$9$k!%(B %Here's an example that illustrates how you can use this ability. %Let's say you're developing a new feature as two patches. The first %is a change to the core of your software, and the second---layered on %top of the first---changes the user interface to use the code you just %added to the core. If you notice a bug in the core while you're %working on the UI patch, it's easy to fix the core. Simply %\hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and %\hgxcmd{mq}{qpop} down to the core patch. Fix the core bug, %\hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI %patch to continue where you left off. $B$3$N5!G=$N;H$$J}$r<($9Nc$r<($9!%(B2$B$D$N%Q%C%A$H$7$F?7$7$$5!G=$r3+H/$7$F$$$k(B $B$H$9$k!%:G=i$N$b$N$O$"$J$?$N%=%U%H%&%'%"$N%3%"$rJQ99$7!$(B2$BHVL\$N$b$N$O(B1$BHV(B $BL\$N$b$N$N>e$KE83+$9$k!$:#DI2C$7$?%3%"$N%3!<%I$r;H$C$?%f!<%6%$%s%?%U%'!<(B $B%9$@$H$9$k!%(BUI$B%Q%C%A$G:n6HCf$K%3%"$N%P%0$K5$IU$$$?$H$9$k$H!$4JC1$K%3%"$N(B $B=$@5$O9T$J$($k!%C1=c$K(B\hgxcmd{mq}{qrefresh}$B$K$h$C$F?J9TCf$N(BUI$B%Q%C%A$r%;!<(B $B%V$7!$(B\hgxcmd{mq}{qpop}$B$K$h$C$F%3%"%Q%C%A$XAL$k!%%3%"$N%P%0$r=$@5$7$?8e(B $B$K(B\hgxcmd{mq}{qrefresh}$B$r%3%"%Q%C%A$K$D$$$F9T$J$$!$(B\hgxcmd{mq}{qpush}$B$G(B UI$B%Q%C%A$KLa$C$F:n6H$rB3$1$k!%(B %\section{More about patches} \section{$B$5$i$K%Q%C%A$K$D$$$F(B} \label{sec:mq:adv-patch} %MQ uses the GNU \command{patch} command to apply patches, so it's %helpful to know a few more detailed aspects of how \command{patch} %works, and about patches themselves. MQ$B$O%Q%C%A$NE,MQ$K(BGNU$B$N(B\command{patch}$B%3%^%s%I$rMQ$$$k!%$=$N$?$a!$(B \command{patch}$B$NF0:n$H%Q%C%A<+BN$K$D$$$F$h$j>\$7$/CN$C$F$*$/$3$H$OM-MQ(B $B$G$"$k!%(B %\subsection{The strip count} \subsection{$B%9%H%j%C%W%+%&%s%H(B} %If you look at the file headers in a patch, you will notice that the %pathnames usually have an extra component on the front that isn't %present in the actual path name. This is a holdover from the way that %people used to generate patches (people still do this, but it's %somewhat rare with modern revision control tools). $B%Q%C%A$N%U%!%$%k%X%C%@$r8+$k$H!$%Q%9%M!<%`$N:G=i$KDI2C$NItJ,$,$D$$$F$$$k(B $B$N$K5$$E$/$O$:$@!%$3$l$O<B:]$N%Q%9%M!<%`$K$OB8:_$7$J$$$b$N$G!$%Q%C%A$r@8(B $B@.$9$k;~$N=,47$+$i$N0dJ*$G$"$k!%!JB?$/$N?M$,$$$^$@$3$NJ}K!$r;H$C$F$$$k$,!$(B $B6aBeE*$J%j%S%8%g%s%3%s%H%m!<%k%D!<%k$G$O$[$H$s$I8+$i$l$J$$!%!K(B %Alice would unpack a tarball, edit her files, then decide that she %wanted to create a patch. So she'd rename her working directory, %unpack the tarball again (hence the need for the rename), and use the %\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to %recursively generate a patch between the unmodified directory and the %modified one. %The result would be that the name of the unmodified %directory would be at the front of the left-hand path in every file %header, and the name of the modified directory would be at the front %of the right-hand path. $B%"%j%9$,(Btar$B%\!<%k$r2rE`$7!$%U%!%$%k$rJT=8$7!$%Q%C%A$r:n$j$?$$$H;W$C$F$$$k(B $B$H$9$k!%H`=w$O%o!<%-%s%0%G%#%l%/%H%j$r%j%M!<%`$7$F(Btar$B%\!<%k$r$b$&0lEY2rE`(B $B$7!J$3$N$?$a$K%j%M!<%`$,I,MW$@$C$?!K!$(B\command{diff}$B$K(B\cmdopt{diff}{-r}$B$H(B \cmdopt{diff}{-N}$B%*%W%7%g%s$r$D$1$F!$85$N$^$^$N%G%#%l%/%H%j$HJQ99$7$?%G%#(B $B%l%/%H%j$N4V$G:F5"E*$K%Q%C%A$r@8@.$9$k$@$m$&!%@8@.$5$l$?%Q%C%A$G$O!$A4$F(B $B$N%U%!%$%k%X%C%@$G85$N$^$^$N%G%#%l%/%H%j$NL>A0$,:8B&$N%Q%9$N@hF,$K!$JQ99(B $B$5$l$?%G%#%l%/%H%j$NL>A0$,1&B&$N%Q%9$N@hF,$K8=$l$k!%(B %Since someone receiving a patch from the Alices of the net would be %unlikely to have unmodified and modified directories with exactly the %same names, the \command{patch} command has a \cmdopt{patch}{-p} %option that indicates the number of leading path name components to %strip when trying to apply a patch. This number is called the %\emph{strip count}. $B%M%C%H>e$N%"%j%9$?$A$+$i%Q%C%A$r<u$1<h$C$??M$O!$JQ99$J$7$N%G%#%l%/%H%j$H(B $BJQ99$5$l$?%G%#%l%/%H%j$NN>J}$r%"%j%9$HF1$8L>A0$G;}$C$F$$$k2DG=@-$O$^$:$J(B $B$$!%(B\command{patch}$B%3%^%s%I$K$O(B\cmdopt{patch}{-p}$B%*%W%7%g%s$,$"$j!$%Q%C(B $B%A$rE,MQ$9$k;~$K%Q%9$NMWAG$r@hF,$+$i$$$/$D:o$k$+$r;XDj$G$-$k!%$3$N?t$O(B \emph{$B%9%H%j%C%W%+%&%s%H(B}$B$H8F$P$l$k!%(B %An option of ``\texttt{-p1}'' means ``use a strip count of one''. If %\command{patch} sees a file name \filename{foo/bar/baz} in a file %header, it will strip \filename{foo} and try to patch a file named %\filename{bar/baz}. (Strictly speaking, the strip count refers to the %number of \emph{path separators} (and the components that go with them %) to strip. A strip count of one will turn \filename{foo/bar} into %\filename{bar}, but \filename{/foo/bar} (notice the extra leading %slash) into \filename{foo/bar}.) $B%*%W%7%g%s(B``\texttt{-p1}''$B$O(B``$B%9%H%j%C%W%+%&%s%H(B1$B$r;H$&(B''$B$H$$$&0UL#$G$"(B $B$k!%$b$7(B\command{patch}$B$,%U%!%$%k%X%C%@$K(B\filename{foo/bar/baz}$B$r8+$D$1(B $B$?;~$O!$(B\filename{foo}$B$rMn$7$F(B\filename{bar/baz}$B$H$$$&L>A0$N%U%!%$%k$K%Q%C(B $B%A$r;n$_$k!%!J87L)$K8@$&$H%9%H%j%C%W%+%&%s%H$O(B\emph{$B%Q%9%;%Q%l!<%?(B}$B$N?t(B $B$r;2>H$7$F$$$k!J7k2L$H$7$FMWAG$b;2>H$5$l$k!K%9%H%j%C%W%+%&%s%H(B1$B$O(B \filename{foo/bar}$B$r(B\filename{bar}$B$KJQ$($k!%$^$?(B\filename{/foo/bar}$B!JA0(B $B$KCV$+$l$?%9%i%C%7%e$KCm0U!K$O(B\filename{foo/bar}$B$H$J$k!%!K(B %The ``standard'' strip count for patches is one; almost all patches %contain one leading path name component that needs to be stripped. %Mercurial's \hgcmd{diff} command generates path names in this form, %and the \hgcmd{import} command and MQ expect patches to have a strip %count of one. $B%Q%C%A$X$N(B``$BI8=`E*$J(B''$B%9%H%j%C%W%+%&%s%H$O(B1$B$G$"$k!%$[$H$s$IA4$F$N%Q%C%A(B $B$O<h$j=|$/$Y$-%Q%9MWAG$r0l$D;}$C$F$$$k!%(BMercurial$B$N(B\hgcmd{diff}$B%3%^%s%I(B $B$O%Q%9L>$r$3$N7A<0$G@8@.$7!$(B\hgcmd{import}$B%3%^%s%I$H(BMQ$B$O%9%H%j%C%W%+%&%s(B $B%H(B1$B$rA0Ds$H$7$F$$$k!%(B %If you receive a patch from someone that you want to add to your patch %queue, and the patch needs a strip count other than one, you cannot %just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet %have a \texttt{-p} option (see~\bug{311}). Your best bet is to %\hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} %to apply their patch, followed by \hgcmd{addremove} to pick up any %files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. %This complexity may become unnecessary; see~\bug{311} for details. $BC/$+$+$i%Q%C%A$r<u$1<h$j!$%Q%C%A%-%e!<$KDI2C$9$k$H$-!$%9%H%j%C%W%+%&%s%H(B $B$,(B1$B0J30$G$"$l$PC1$K(B\hgxcmd{mq}{qimport}$B$9$k$3$H$O$G$-$J$$!%$3$l$O(B \hgxcmd{mq}{qimport}$B%3%^%s%I$,$^$@(B\texttt{-p}$B%*%W%7%g%s$r;}$C$F$$$J$$$?$a(B $B$@!J(B\bug{311}$B$r;2>H!K!%:G$b>e<j$/$$$-$=$&$JJ}K!$O!$(B\hgxcmd{mq}{qnew}$B$G?7(B $B$?$K%Q%C%A$r:n$j!$(B\cmdargs{patch}{-p\emph{N}}$B$r<B9T$7$F<u$1<h$C$?%Q%C%A$r(B $BE,MQ$7$?8e!$%Q%C%A$K$h$C$FDI2C$5$l$?$j:o=|$5$l$?%U%!%$%k$r(B \hgcmd{addremove}$B$K$h$C$F%T%C%/%"%C%W$7!$(B\hgxcmd{mq}{qrefresh}$B$r<B9T$9$k(B $B$3$H$G$"$k!%$3$NJ#;($J<j=g$O>-MhE*$K$OI,MW$J$/$J$k$O$:$@!J(B\bug{311}$B$r;2(B $B>H!K!%(B %\subsection{Strategies for applying a patch} \subsection{$B%Q%C%AE,MQ$N$?$a$N@oN,(B} %When \command{patch} applies a hunk, it tries a handful of %successively less accurate strategies to try to make the hunk apply. %This falling-back technique often makes it possible to take a patch %that was generated against an old version of a file, and apply it %against a newer version of that file. \command{patch}$B$,(Bhunk$B$rE,MQ$9$k$H$-!$$$$/$D$+$N$"$^$j@53N$G$J$$@oN,$rB3$1(B $B$FMQ$$$k!%$3$N%U%)!<%k%P%C%/<jK!$K$h$C$F!$8E$$%P!<%8%g%s$N%U%!%$%k$KBP$7(B $B$F:n@.$7$?%Q%C%A$r?7$7$$%U%!%$%k$KE,MQ$9$k$3$H$5$($7$P$7$P2DG=$H$J$k!%(B %First, \command{patch} tries an exact match, where the line numbers, %the context, and the text to be modified must apply exactly. If it %cannot make an exact match, it tries to find an exact match for the %context, without honouring the line numbering information. If this %succeeds, it prints a line of output saying that the hunk was applied, %but at some \emph{offset} from the original line number. $B:G=i$K!$(B\command{patch}$B$O9THV9f!$%3%s%F%-%9%H!$JQ99$5$l$k%F%-%9%H$N@53N$J(B $B%^%C%A$r;n$_$k!%@53N$J%^%C%A$,$G$-$J$$>l9g!$9THV9f$rL5;k$7$F%3%s%F%-%9%H(B $B$N@53N$J%^%C%A$r;n$_$k!%$3$l$,@.8y$9$l$P!$(Bhunk$B$,E,MQ$5$l$?$,!$(B\emph{$B%*%U(B $B%;%C%H(B}$B$,@8$8$?$H$$$&%a%C%;!<%8$rI=<($9$k!%(B %If a context-only match fails, \command{patch} removes the first and %last lines of the context, and tries a \emph{reduced} context-only %match. If the hunk with reduced context succeeds, it prints a message %saying that it applied the hunk with a \emph{fuzz factor} (the number %after the fuzz factor indicates how many lines of context %\command{patch} had to trim before the patch applied). $B%3%s%F%-%9%H$N$_$N%^%C%A$,<:GT$9$k$H!$(B\command{patch}$B$O%3%s%F%-%9%H$N:G=i(B $B$H:G8e$N9T$r:o$j!$%3%s%F%-%9%H$N(B\emph{$B=L>.(B}$B%^%C%A$r;n$_$k!%=L>.%3%s%F%-%9(B $B%H$K$h$k(Bhunk$B$,@.8y$9$k$H!$(Bhunk$B$,E,MQ$5$l$?$3$H$H(B\emph{fuzz $B%U%!%/%?!<(B}$B$r(B $B4^$`%a%C%;!<%8$rI=<($9$k!%!J(Bfuzz$B%U%!%/%?!<$N8e$m$N?t;z$O!$(B \command{patch}$B%3%^%s%I$,!$%Q%C%A$rE,MQ$9$kA0$K%3%s%F%-%9%H$N2?9T$r:o=|$9(B $B$kI,MW$,$"$C$?$N$+$r<($9!%!K(B %When neither of these techniques works, \command{patch} prints a message %saying that the hunk in question was rejected. It saves rejected hunks %(also simply called ``rejects'') to a file with the same name, and an %added \sfilename{.rej} extension. It also saves an unmodified copy of %the file with a \sfilename{.orig} extension; the copy of the file %without any extensions will contain any changes made by hunks that %\emph{did} apply cleanly. If you have a patch that modifies %\filename{foo} with six hunks, and one of them fails to apply, you will %have: an unmodified \filename{foo.orig}, a \filename{foo.rej} containing %one hunk, and \filename{foo}, containing the changes made by the five %successful five hunks. $B$I$A$i$b>e<j$/$$$+$J$+$C$?>l9g!$(B\command{patch}$B$O(Bhunk$B$,%j%8%'%/%H$5$l$?$H(B $B$$$&%a%C%;!<%8$rI=<($9$k!%%3%^%s%I$O%j%8%'%/%H$5$l$?(Bhunk$B!J$"$k$$$OC1$K(B ``rejects''$B!K$rF1L>$G3HD%;R(B\sfilename{.rej}$B$N%U%!%$%k$K%;!<%V$9$k!%%3%^%s(B $B%I$OF1;~$KL5JQ99$N%U%!%$%k$r(B\sfilename{.orig}$B$H$$$&3HD%;R$G%;!<%V$9$k!#3H(B $BD%;R$N$J$$%U%!%$%k$N%3%T!<$O!$(Bhunk$B$+$i%/%j!<%s$KE,MQ$5$l$?JQ99$rA4$F4^$`!%(B \filename{foo}$B$H$$$&%U%!%$%k$rJQ99$9$k(B6$B$D$N(Bhunk$B$r4^$`%Q%C%A%U%!%$%k$,$"$j!$(B $B$=$NFb$N(B1$B$D$,E,MQ$G$-$J$+$C$?$H$9$k$H!$L5JQ99$N%U%!%$%k(B \filename{foo.orig}$B!$(Bhunk1$B$D$r4^$`%U%!%$%k(B\filename{foo.rej}$B!$@5$7$/E,MQ(B $B$5$l$?(B5$B$D$N(Bhunk$B$r4^$`%U%!%$%k(B\filename{foo}$B$,@8@.$5$l$k!%(B %\subsection{Some quirks of patch representation} \subsection{$B%Q%C%AI=8=$N4qL/$JE@(B} %There are a few useful things to know about how \command{patch} works %with files. %\begin{itemize} %\item This should already be obvious, but \command{patch} cannot % handle binary files. %\item Neither does it care about the executable bit; it creates new % files as readable, but not executable. %\item \command{patch} treats the removal of a file as a diff between % the file to be removed and the empty file. So your idea of ``I % deleted this file'' looks like ``every line of this file was % deleted'' in a patch. %\item It treats the addition of a file as a diff between the empty % file and the file to be added. So in a patch, your idea of ``I % added this file'' looks like ``every line of this file was added''. %\item It treats a renamed file as the removal of the old name, and the % addition of the new name. This means that renamed files have a big % footprint in patches. (Note also that Mercurial does not currently % try to infer when files have been renamed or copied in a patch.) %\item \command{patch} cannot represent empty files, so you cannot use % a patch to represent the notion ``I added this empty file to the % tree''. %\end{itemize} \command{patch}$B$,%U%!%$%k$K$I$N$h$&$K:nMQ$9$k$+!$M-MQ$JE@$r$$$/$D$+=R$Y(B $B$k!%(B \begin{itemize} \item $B$9$G$KL@Gr$@$,!$(B\command{patch}$B$O%P%$%J%j%U%!%$%k$r07$&$3$H$O$G$-(B $B$J$$!%(B \item $B<B9T%S%C%H$r9MN8$7$J$$$@$1$G$J$/!$?7$7$$%U%!%$%k$rFI$_<h$j2DG=B0(B $B@-$G:n@.$7!$<B9T2DG=B0@-$OIU$1$J$$!%(B \item \command{patch}$B%3%^%s%I$O%U%!%$%k$N:o=|$r:o=|$5$l$k%U%!%$%k$HCf?H(B $B$,$+$i$N%U%!%$%k$H$N:9J,$H$7$F07$&!%=>$C$F!$%U%!%$%k$r:o=|$9$k$H$$(B $B$&$3$H$O!$%Q%C%A%U%!%$%k$NCf$G$O%U%!%$%k$NCf$NA4$F$N9T$r:o=|$9$k$3(B $B$H$HEy2A$G$"$k!%(B \item \command{patch}$B%3%^%s%I$O%U%!%$%k$NDI2C$r6u$N%U%!%$%k$HDI2C$5$l$k(B $B%U%!%$%k$N:9J,$H$7$F07$&!%=>$C$F%U%!%$%k$NDI2C$O%Q%C%A%U%!%$%k$NCf(B $B$G$O%U%!%$%k$KA4$F$N9T$rDI2C$9$k$3$H$HEy2A$G$"$k!%(B \item \command{patch}$B%3%^%s%I$OL>A0$NJQ99$5$l$?%U%!%$%k$r5lL>$N%U%!%$%k(B $B$N:o=|$H?7$7$$%U%!%$%k$NDI2C$H$7$F07$&!%=>$C$FL>A0$NJQ99$5$l$?%U%!(B $B%$%k$O%Q%C%AFb$GBg$-$J%U%C%H%W%j%s%H$r@j$a$k!%!J(BMercurial$B$O8=:_$N(B $B$H$3$m!$%Q%C%AFb$G%U%!%$%k$,%j%M!<%`$5$l$?$N$+!$%3%T!<$5$l$?$N$+(B $B$r4XCN$7$J$$!K(B \item \command{patch}$B%3%^%s%I$OCf?H$N6u$N%U%!%$%k$rI=8=$G$-$J$$!%=>$C$F(B $B%Q%C%A%U%!%$%k$r!V6u$N%U%!%$%k$r%D%j!<$KDI2C$9$k!W$H$$$&MQES$K;H(B $B$&$3$H$O$G$-$J$$!%(B \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 %develop than the rate of change of the code beneath, you will often %need to sync up with the underlying code, and fix up any hunks in your %patches that no longer apply. This is called \emph{rebasing} your %patch series. $BD>@\JQ99$7$J$$%j%]%8%H%j$N>e$K%Q%C%A$N%9%?%C%/$r4IM}$9$k$3$H$O$h$/9T$o$l(B $B$k!%%5!<%I%Q!<%F%#$N%3!<%I$rJQ99$9$k:n6H$r$7$F$$$k>l9g$d!$85$K$J$k%3!<%I(B $B$NJQ99IQEY$KHf$Y$FD9$$;~4V$,$+$+$k5!G=$r3+H/$7$F$$$k>l9g!$$7$P$7$P85$N%3!<(B $B%I$NF14|$r9T$$!$%Q%C%A$NCf$N$b$O$dE,MQ$G$-$J$/$J$C$?(Bhunk$B$r=$@5$9$k$3$H$K(B $B$J$k$@$m$&!%$3$l$O%Q%C%A$N(B\emph{rebasing}$B$H8F$P$l$k!%(B %The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} %your patches, then \hgcmd{pull} changes into the underlying %repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your %patches again. MQ will stop pushing any time it runs across a patch %that fails to apply during conflicts, allowing you to fix your %conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing %until you have fixed your entire stack. $B$3$l$r9T$&:G$b4JC1$JJ}K!$O!$%Q%C%A$KBP$7$F(B \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}$B$r9T$$!$2<0L$N%j%]%8%H%j$K(B \hgcmd{pull}$B$r9T$&!%$=$7$F:G8e$K%Q%C%A$K:F$S(B \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}}$B$r9T$&!%(B MQ$B$O%Q%C%AE,MQCf$K%3%s%U(B $B%j%/%H$,$"$k$H!$$$$D$G$b%W%C%7%e$rDd;_$7!$(B\hgxcmd{mq}{qrefresh}$B$K$h$C$F%3(B $B%s%U%j%/%H$r=$@5$9$k5!2q$rM?$($k!%$=$N8e$K$9$Y$F$N%Q%C%A%9%?%C%/$rE,MQ$9(B $B$k$^$G%W%C%7%e$rB3$1$k!%(B %This approach is easy to use and works well if you don't expect %changes to the underlying code to affect how well your patches apply. %If your patch stack touches code that is modified frequently or %invasively in the underlying repository, however, fixing up rejected %hunks by hand quickly becomes tiresome. $B$3$N%"%W%m!<%A$O4JC1$G!$%Q%C%A$NE,MQ$5$l$k2<0L$N%3!<%I$X$NJQ99$,$J$1$l$P(B $B$&$^$/F/$/!%$7$+$7!$%Q%C%A%9%?%C%/$,!$IQHK$K99?7$5$l$?$j!$2<0L%j%]%8%H%j(B $B$X?/F~E*$K99?7$5$l$?$j$9$k%3!<%I$K?($l$F$$$k>l9g$O%j%8%'%/%H$5$l$?%3!<%I(B $B$N=$@5$OLLE]$J$b$N$K$J$k!%(B %It's possible to partially automate the rebasing process. If your %patches apply cleanly against some revision of the underlying repo, MQ %can use this information to help you to resolve conflicts between your %patches and a different revision. rebase$B%W%m%;%9$rItJ,E*$K<+F02=$9$k$3$H$O2DG=$G$"$k!%%Q%C%A$,2<0L$N%j%]%8(B $B%H%j$N$$$:$l$+$N%P!<%8%g%s$K%/%j!<%s$KE,MQ$G$-$k$N$G$"$l$P!$(BMQ$B$O$3$N>pJs(B $B$r;H$C$F%Q%C%A$H$=$NB>$N%j%S%8%g%s$H$N4V$N%3%s%U%j%/%H$r2r>C$9$k$N$r1g=u(B $B$9$k!%(B %The process is a little involved. $B$3$N%W%m%;%9$O$d$d9~$_F~$C$F$$$k!%(B \begin{enumerate} %\item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of % the revision where you know that they apply cleanly. \item $B:G=i$K!$%Q%C%A$,%/%j!<%s$KE,MQ$G$-$k%j%S%8%g%s$N>e$G!$$9$Y$F$N%Q%C(B $B%A$KBP$7$F(B\hgcmdargs{qpush}{-a}$B$r9T$&!%(B %\item Save a backup copy of your patch directory using % \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. % This prints % the name of the directory that it has saved the patches in. It will % save the patches to a directory called % \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small % integer. It also commits a ``save changeset'' on top of your % applied patches; this is for internal book-keeping, and records the % states of the \sfilename{series} and \sfilename{status} files. \item $B%Q%C%A%G%#%l%/%H%j$r%;!<%V$r(B \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}$B$r(B $BMQ$$$F9T$&!%%Q%C%A$r%;!<%V$7$?%G%#%l%/%H%jL>$,I=<($5$l$k!%$3$N%3%^(B $B%s%I$O!$(B\sdirname{.hg/patches.\emph{N}}$B$H$$$&%G%#%l%/%H%j$K%;!<%V$r(B $B9T$&!%$3$3$G(B\texttt{\emph{N}}$B$O>.$5$$@0?t$G$"$k!%$3$N%3%^%s%I$O(B``$B%;!<(B $B%V%A%'%s%8%;%C%H(B''$B$rE,MQ$5$l$?%Q%C%A$N>e$K%3%_%C%H$9$k!%$3$l$OFbIt(B $BE*$J4IM}$H!$(B\sfilename{series}$B%U%!%$%k5Z$S(B\sfilename{status}$B%U%!%$(B $B%k$N>uBV$r5-O?$9$k$?$a$G$"$k!%(B %\item Use \hgcmd{pull} to bring new changes into the underlying % repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.) \item \hgcmd{pull}$B%3%^%s%I$r;H$C$F?7$?$JJQ99$r2<0L$N%j%]%8%H%j$K<h$j9~(B $B$`!%(B(\hgcmdargs{pull}{-u}$B$r<B9T$7$F$O$$$1$J$$!%M}M3$K$D$$$F$O2<5-(B $B$r;2>H!%(B) %\item Update to the new tip revision, using % \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you % have pushed. \item \hgcmdargs{update}{\hgopt{update}{-C}}$B$rMQ$$$F!$(Bpush$B$7$?%Q%C%A$r%*!<(B $B%P%i%$%I$7$F?7$?$J(Btip$B%j%S%8%g%s$X$N%"%C%W%G!<%H$r9T$&!%(B %\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} % \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush} % tells MQ to perform a three-way merge if the patch fails to apply. \item \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} \hgxopt{mq}{qpush}{-a}}$B$r(B $BMQ$$$F$9$Y$F$N%Q%C%A$N%^!<%8$r9T$&!%(B\hgxopt{mq}{qpush}{-m}$B%*%W%7%g(B $B%s$r(B\hgxcmd{mq}{qpush}$B$KIU$1$k$H!$(BMQ$B$O%Q%C%A$NE,MQ$K<:GT$7$?>l(B $B9g!$(B3$B%&%'%$%^!<%8$r9T$&!%(B \end{enumerate} %During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the %\sfilename{series} file is applied normally. If a patch applies with %fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and %performs a three-way merge with the corresponding changeset. This %merge uses Mercurial's normal merge machinery, so it may pop up a GUI %merge tool to help you to resolve problems. \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}$B%3%^%s%I$N<B9T(B $BCf!$(B\sfilename{series}$BFb$N%Q%C%A$ODL>oDL$jE,MQ$5$l$k!%$b$7%Q%C%A$,(Bfuzz$B$d(B reject$B$r=P$7$?>l9g!$(BMQ$B$O(B\hgxcmd{mq}{qsave}$B$7$?%-%e!<$r;2>H$7!$BP1~$9$k%A%'(B $B%s%8%;%C%H$H$N4V$G(B3$B%&%'%$%^!<%8$r9T$&!%%^!<%8$O(BMercurial$B$NDL>o$N5!9=$r;H$C(B $B$F9T$o$l$k$?$a!$@_Dj$K$h$C$FLdBj$r2r7h$9$k$?$a$N(BGUI$B%^!<%8%D!<%k$J$I$,5/F0(B $B$9$k!%(B %When you finish resolving the effects of a patch, MQ refreshes your %patch based on the result of the merge. $B%Q%C%A$N1F6A$N2r7h$r=*$($?;~!$(BMQ$B$O%^!<%8$N7k2L$rF'$^$($F%Q%C%A$N%j%U%l%C(B $B%7%e$r9T$&!%(B %At the end of this process, your repository will have one extra head %from the old patch queue, and a copy of the old patch queue will be in %\sdirname{.hg/patches.\emph{N}}. You can remove the extra head using %\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}} %or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once %you are sure that you no longer need it as a backup. $B$3$N%W%m%;%9$N:G8e$K%j%]%8%H%j$K$O8E$$%Q%C%A%-%e!<$KM3Mh$9$k0l$DM>J,$J(B head$B$,$G$-!$8E$$%Q%C%A%-%e!<$,(B\sdirname{.hg/patches.\emph{N}}$B$K%3%T!<$5$l(B $B$k!%$3$N(Bhead$B$O(B\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}$B$^$?$O(B\hgcmd{strip}$B$K$h$C$F>C5n$G(B $B$-$k!%%P%C%/%"%C%W$,ITMW$J$3$H$,J,$+$l$P!$(B\sdirname{.hg/patches.\emph{N}}$B$r(B $B>C5n$7$F$b9=$o$J$$!%(B %\section{Identifying patches} \section{$B%Q%C%A$N<1JL(B} %MQ commands that work with patches let you refer to a patch either by %using its name or by a number. By name is obvious enough; pass the %name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will %push patches until \filename{foo.patch} is applied. $B%Q%C%A$r07$&(BMQ$B%3%^%s%I$O!$%Q%C%A$r%Q%C%AL>$^$?$OHV9f$G;2>H$9$k!%L>A0$N>l(B $B9g$ONc$($P%U%!%$%kL>(B\filename{foo.patch}$B$r(B\hgxcmd{mq}{qpush}$B$KEO$9!%$3$N(B $B>l9g!$%3%^%s%I$O(B\filename{foo.patch}$B$^$G$N%U%!%$%k$r%W%C%7%e$9$k!%(B %As a shortcut, you can refer to a patch using both a name and a %numeric offset; \texttt{foo.patch-2} means ``two patches before %\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches %after \texttt{bar.patch}''. $B%7%g!<%H%+%C%H$H$7$F!$%Q%C%A$KL>A0$H?t;z$K$h$k%*%U%;%C%HN>J}$rMQ$$$F;2>H(B $B$9$k$3$H$,$G$-$k!%(B\texttt{foo.patch-2}$B$O(B``\texttt{foo.patch}$B$N(B2$B$DA0$N%Q%C(B $B%A(B''$B$H2r<a$5$l$k!%$^$?!$(B\texttt{bar.patch+4}$B$O(B``\texttt{bar.patch}$B$N(B4$B$D(B $B8e$N%Q%C%A(B''$B$H2r<a$5$l$k!%(B %Referring to a patch by index isn't much different. The first patch %printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one %of those start-at-zero counting systems); the second is patch one; and %so on $B%$%s%G%C%/%9$,$"$^$j0c$o$J$$%Q%C%A$N;2>H!%(B\hgxcmd{mq}{qseries}$B$G:G=i$KI=(B $B<($5$l$k%Q%C%A$O%Q%C%A(B0($B$3$l$b(B0$B$+$i?t$(;O$a$k(B)$B$G!$(B2$BHVL\$O%Q%C%A(B1$B$N$h$&$K(B $BB3$/!%(B %MQ also makes it easy to work with patches when you are using normal %Mercurial commands. Every command that accepts a changeset ID will %also accept the name of an applied patch. MQ augments the tags %normally in the repository with an eponymous one for each applied %patch. In addition, the special tags \index{tags!special tag % names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag % names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and %topmost applied patches, respectively. MQ$B$O!$DL>o$N(BMercurial$B%3%^%s%I$r;H$&;~$N$b4JC1$K$7$F$$$k!%A4$F$N%3%^%s%I$O(B $B%A%'%s%8%;%C%H(BID$B$HE,MQ$5$l$?%Q%C%A$NHV9f$r<u$1IU$1$k!%(BMQ$B$O!$%j%]%8%H%j$K(B $BE,MQ$5$l$?%Q%C%A$NL>A0$N$D$$$?%?%0$r<u$1IU$1$k!%$5$i$K!$:G2<0L$NE,MQ$5$l(B $B$?%Q%C%A$rI=$9FCJL$J%?%0(B\index{tags!special tag names!\texttt{qbase}}\texttt{qbase}$B$H!$:G>e0L$rI=$9FCJL$J%?%0(B \index{tags!special tag names!\texttt{qtip}}\texttt{qtip}$B$b<u$1IU$1$k!%(B %These additions to Mercurial's normal tagging capabilities make %dealing with patches even more of a breeze. Mercurial$B$NDL>o$N%?%05!G=$X$N$3$l$i$NDI2C$O!$%Q%C%A$N<h$j07$$$K$*$$$FBg$-(B $B$J0UL#$r;}$D!%(B \begin{itemize} %\item Want to patchbomb a mailing list with your latest series of % changes? \item $B0lO"$N:G?7$NJQ99$r%Q%C%AGzCF$H$7$F%a!<%j%s%0%j%9%H$X$KEj$29~$_$?$$(B $B$@$m$&$+!)(B \begin{codesample4} hg email qbase:qtip \end{codesample4} % (Don't know what ``patchbombing'' is? See % section~\ref{sec:hgext:patchbomb}.) (``patchbombing''$B$,2?$+J,$+$i$J$1$l$P(Bsection~\ref{sec:hgext:patchbomb}$B$r(B $B;2>H$N$3$H!%(B) %\item Need to see all of the patches since \texttt{foo.patch} that % have touched files in a subdirectory of your tree? \item $B%D%j!<Cf$N%5%V%G%#%l%/%H%j$K4^$^$l$k%U%!%$%k$K?($l$?(B \texttt{foo.patch}$B0J9_$N%Q%C%A$rA4$F8+$?$$$+!)(B \begin{codesample4} hg log -r foo.patch:qtip \emph{subdir} \end{codesample4} \end{itemize} %Because MQ makes the names of patches available to the rest of %Mercurial through its normal internal tag machinery, you don't need to %type in the entire name of a patch when you want to identify it by %name. MQ$B$G$N%Q%C%A$NL>>N$O!$FbIt$N%?%05!9=$rMQ$$$F$$$k$?$a!$(BMercurial$B$NB>$NItJ,(B $B$G$bMxMQ2DG=$G$"$k!%L>>N$r;XDj$9$k;~!$L>>NA4$F$rF~NO$9$kI,MW$O$J$$!%(B \begin{figure}[ht] \interaction{mq.id.output} % \caption{Using MQ's tag features to work with patches} \caption{$B%Q%C%A$r07$&$?$a(BMQ$B$N%?%05!G=$rMxMQ$9$k(B} \label{ex:mq:id} \end{figure} %Another nice consequence of representing patch names as tags is that %when you run the \hgcmd{log} command, it will display a patch's name %as a tag, simply as part of its normal output. This makes it easy to %visually distinguish applied patches from underlying ``normal'' %revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial %commands in use with applied patches. $B%Q%C%AL>$r%?%0$H$7$F<h$j07$&$3$H$N$b$&0l$D$NMxE@$O!$(B\hgcmd{log}$B%3%^%s%I(B $B$r<B9T$7$?;~!$DL>o=PNO$N0lIt$K%Q%C%AL>$r%?%0$H$7$FI=<($9$kE@$G$"$k!%$3$N(B $B$?$a!$E,MQ$7$?%Q%C%A$O2<0L$N(B``$BDL>o$N(B''$B%j%S%8%g%s$H;k3PE*$K6hJL$70W$/$J$k!%(B $B?^(B~\ref{ex:mq:id}$B$K$$$/$D$+$NDL>o$N(BMercurial$B%3%^%s%I$rE,MQ:Q$_%Q%C%A$H6&(B $B$K;HMQ$7$?>l9g$r<($9!%(B %\section{Useful things to know about} \section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} %There are a number of aspects of MQ usage that don't fit tidily into %sections of their own, but that are good to know. Here they are, in %one place. MQ$B$N;HMQK!$K$O8DJL$K<h$j>e$2$k$[$I$G$O$J$$$,!$CN$C$F$*$/$HNI$$$$$/$D$+$N(B $BE@$,$"$k!%$3$3$G$O$=$l$i$r$^$H$a$F<h$j>e$2$k!%(B \begin{itemize} %\item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it % again, the changeset that represents the patch after the pop/push % will have a \emph{different identity} than the changeset that % represented the hash beforehand. See % section~\ref{sec:mqref:cmd:qpush} for information as to why this is. \item $B%Q%C%A$r(B\hgxcmd{mq}{qpop}$B$7$?8e$G:F$S(B\hgxcmd{mq}{qpush}$B$9$k(B $B$H!$(Bpop/push$B$7$?8e$N%A%'%s%8%;%C%H$O!$0JA0$N%A%'%s%8%;%C%H$H0[$J$k(B $B%"%$%G%s%F%#%F%#$r;}$A!$%O%C%7%eCM$,0[$J$k!%$3$NM}M3$K$D$$$F$O%;%/(B $B%7%g%s(B~\ref{sec:mqref:cmd:qpush}$B$r;2>H$5$l$?$$!%(B %\item It's not a good idea to \hgcmd{merge} changes from another % branch with a patch changeset, at least if you want to maintain the % ``patchiness'' of that changeset and changesets below it on the % patch stack. If you try to do this, it will appear to succeed, but % MQ will become confused. \item \hgcmd{merge}$B$,B>$N%V%i%s%A$N%Q%C%A%A%'%s%8%;%C%H$r%^!<%8$9$k$3$H(B $B$O!$$=$N%A%'%s%8%;%C%H$H%Q%C%A%9%?%C%/$K@Q$_9~$^$l$?B>$N%A%'%s%8%;%C(B $B%H$H$N4V$G0l4S@-$r0];}$7$h$&$H$9$k$N$G$"$l$PHr$1$k$Y$-$G$"$k!%$3$l(B $B$r;n$_$?>l9g!$0l8+@.8y$7$?$h$&$K8+$($F$b(BMQ$B$O:.Mp>uBV$K4Y$C$F$7$^(B $B$&!%(B \end{itemize} %\section{Managing patches in a repository} \section{$B%j%]%8%H%jFb$G$N%Q%C%A$N4IM}(B} \label{sec:mq:repo} %Because MQ's \sdirname{.hg/patches} directory resides outside a %Mercurial repository's working directory, the ``underlying'' Mercurial %repository knows nothing about the management or presence of patches. MQ$B$N(B\sdirname{.hg/patches}$B%G%#%l%/%H%j$O(BMercurial$B%j%]%8%H%j$N%o!<%-%s%0(B $B%G%#%l%/%H%j$N30$K$"$k$N$G!$(B``$B2<0L$N(B''Mercurial$B%j%]%8%H%j$O%Q%C%A$N4IM}(B $B$d!$$=$NB;0&;yBP$K$D$$$F2?$bCN$i$J$$!%(B %This presents the interesting possibility of managing the contents of %the patch directory as a Mercurial repository in its own right. This %can be a useful way to work. For example, you can work on a patch for %a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of %the patch. This lets you ``roll back'' to that version of the patch %later on. $B$3$N$3$H$+$i!$%Q%C%A%G%#%l%/%H%j$N4IM}$rFHN)$7$?(BMercurial$B%j%]%8%H%j$H$7$F(B $B9T$&$3$H$,$G$-$k$N$G$O$J$$$+$H$$$&6=L#$,@8$^$l$k!%<B:]$3$NJ}K!$OM-8z$JJ}(B $BK!$H$J$jF@$k!%Nc$($P!$$7$P$i$/$N4V(B1$B$D$N%Q%C%A$K$D$$$F:n6H$r9T$C$?8e(B $B$G!$(B\hgxcmd{mq}{qrefresh}$B$r9T$$!$%Q%C%A$N8=:_$N>uBV$r(B\hgcmd{commit}$B$9$k(B $B$3$H$,$G$-$k!%$3$l$K$h$C$F!$8e$G$3$N%Q%C%A$r(B``$B%m!<%k%P%C%/(B''$B$9$k$3$H$,2D(B $BG=$H$J$k!%(B %You can then share different versions of the same patch stack among %multiple underlying repositories. I use this when I am developing a %Linux kernel feature. I have a pristine copy of my kernel sources for %each of several CPU architectures, and a cloned repository under each %that contains the patches I am working on. When I want to test a %change on a different architecture, I push my current patches to the %patch repository associated with that kernel tree, pop and push all of %my patches, and build and test that kernel. $BJ#?t$N2<0L%j%]%8%H%j$N4V$G!$F1$8%Q%C%A%9%?%C%/$N0[$J$k%P!<%8%g%s$r6&M-$9(B $B$k$3$H$,$G$-$k!%I.<T$O$3$l$r(BLinux$B%+!<%M%k$N5!G=$r3+H/$9$k;~$KMxMQ$7$F$$(B $B$k!%$$$/$D$+$N(BCPU$B%"!<%-%F%/%A%c$N3F!9$KBP$7$F$^$C$5$i$J%+!<%M%k%=!<%9$N%j(B $B%]%8%H%j$rMQ0U$7!$:n6HCf$N%Q%C%A$r4^$`%j%]%8%H%j$r$=$l$i$N4V$G%/%m!<%s$7(B $B$F$$$k!%JQ99$r0[$J$k%"!<%-%F%/%A%c$G%F%9%H$7$?$$;~$O!$8=:_$N%Q%C%A$r$=$N(B $B%"!<%-%F%/%A%cMQ$N%+!<%M%k%D%j!<$H7k$SIU$$$?%Q%C%A$N%j%]%8%H%j$X%W%C%7%e(B $B$7!$$9$Y$F$N%Q%C%A$r(Bpop$B!$(Bpush$B$7$F%+!<%M%k$N%S%k%I$H%F%9%H$r9T$C$F$$$k!%(B %Managing patches in a repository makes it possible for multiple %developers to work on the same patch series without colliding with %each other, all on top of an underlying source base that they may or %may not control. $B%j%]%8%H%jFb$G%Q%C%A$r4IM}$9$k$H!$J#?t$N3+H/<T$,F1$8%Q%C%A%7%j!<%:$N>e$G(B $B>WFM$9$k$3$H$J$/:n6H$G$-$k$h$&$K$J$k!%$3$l$OH`$i$,2<0L$N%=!<%9%Y!<%9$r%3(B $B%s%H%m!<%k$G$-$k$+H]$+$K4X$o$j$,$J$$!%(B %\subsection{MQ support for patch repositories} \subsection{MQ$B$K$h$k%Q%C%A%j%]%8%H%j%5%]!<%H(B} %MQ helps you to work with the \sdirname{.hg/patches} directory as a %repository; when you prepare a repository for working with patches %using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to %create the \sdirname{.hg/patches} directory as a Mercurial repository. MQ$B$O(B\sdirname{.hg/patches}$B%G%#%l%/%H%j$r%j%]%8%H%j$H$7$F;H$$$J$,$i:n6H$9(B $B$k$3$H$r%5%]!<%H$7$F$$$k!%%Q%C%A$r07$&:n6HMQ$N%j%]%8%H%j$r(B \hgxcmd{mq}{qinit}$B$G:n@.$9$k;~!$(B\hgxopt{mq}{qinit}{-c}$B$rEO$7$F(B \sdirname{.hg/patches}$B%G%#%l%/%H%j$r(BMercurial$B%j%]%8%H%j$K$9$k$3$H$,$G$-$k!%(B \begin{note} % If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go % into the \sdirname{.hg/patches} directory at any time and run % \hgcmd{init}. Don't forget to add an entry for the % \sfilename{status} file to the \sfilename{.hgignore} file, though % (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you % automatically); you \emph{really} don't want to manage the % \sfilename{status} file. \hgxopt{mq}{qinit}{-c}$B%*%W%7%g%s$rK:$l$?>l9g$O$$$D$G$b(B \sdirname{.hg/patches}$B$KF~$C$F(B\hgcmd{init}$B$r<B9T$9$l$P$h(B $B$$!%(B\sfilename{status}$B%U%!%$%k$r(B\sfilename{.hgignore}$B%U%!%$%k$KDI2C$9$k(B $B$N$rK:$l$J$$$3$H!%(B(\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}}$B$O$3$l$r<+F0(B $BE*$K9T$&!%!K(B\sfilename{status}$B$r%P!<%8%g%s4IM}$9$kI,MW$O(B\emph{$BA4$/$J$$(B}$B!%(B \end{note} %As a convenience, if MQ notices that the \dirname{.hg/patches} %directory is a repository, it will automatically \hgcmd{add} every %patch that you create and import. \dirname{.hg/patches}$B$,%j%]%8%H%j$N;~$O!$(BMQ$B$OJXMx$N$?$a$K$3$l$^$G:n@.$7!$(B $B%$%s%]!<%H$7$?$9$Y$F$N%Q%C%A$r<+F0E*$K(B\hgcmd{add}$B$9$k!%(B %MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs %\hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves %some bothersome typing. MQ$B$O%7%g!<%H%+%C%H%3%^%s%I(B\hgxcmd{mq}{qcommit}$B$r;}$D!%$3$N%3%^%s%I$O(B \hgcmd{commit}$B%3%^%s%I$r(B\sdirname{.hg/patches}$B%G%#%l%/%H%j$NCf$G<B9T$9(B $B$k!%$3$l$K$h$C$FHK;($JF~NO$r>J$/$3$H$,$G$-$k!%(B %Finally, as a convenience to manage the patch directory, you can %define the alias \command{mq} on Unix systems. For example, on Linux %systems using the \command{bash} shell, you can include the following %snippet in your \tildefile{.bashrc}. $B%Q%C%A%G%#%l%/%H%j$N4IM}$N$?$a$K(BUNIX$B4D6-$J$i(B\command{mq}$B$H$$$&%(%$%j%"%9(B $B$r:n$C$F$*$/$HJXMx$@!%(BLinux$B$G$O(B\command{bash}$B%7%'%k$N@_Dj%U%!%$%k(B \tildefile{.bashrc}$B$K$3$l$rDj5A$7$F$*$/!%(B \begin{codesample2} alias mq=`hg -R \$(hg root)/.hg/patches' \end{codesample2} %You can then issue commands of the form \cmdargs{mq}{pull} from %the main repository. $B%a%$%s%j%]%8%H%j$+$i(B\cmdargs{mq}{pull}$B$r<B9T$9$k$3$H$,$G$-$k(B %\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$B$,BgNL$N%Q%C%A$N$"$k%j%]%8%H%j$r07$&:]$K!$$$$/$D$+$N>.$5$JE@$+$i@)8B$,(B $B$"$k!%(B %MQ cannot automatically detect changes that you make to the patch %directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update} %changes to patches or the \sfilename{series} file, you will have to %\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then %\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to %see those changes show up there. If you forget to do this, you can %confuse MQ's idea of which patches are applied. MQ$B$O!$%Q%C%A%G%#%l%/%H%j$KBP$7$F9T$o$l$?JQ99$r<+F0E*$K8!=P$9$k$3$H$O$G$-(B $B$J$$!%%Q%C%A%U%!%$%k$d(B\sfilename{series}$B$KBP$7$F(B\hgcmd{pull}$B$r9T$C$?$j!$(B $B<j$GJT=8$7$?$j!$(B\hgcmd{update}$B$r9T$C$?>l9g(B $B$O!$2<0L$N%j%]%8%H%j$KBP$7$F(B\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}$B$H(B \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}}$B$r9T$$!$JQ99$rCN$i$;$kI,MW$,$"(B $B$k!%$3$l$rK:$l$k$H(BMQ$B$O$I$N%Q%C%A$,E,MQ$5$l$?$N$+GD0.$G$-$J$/$J$C$F$7$^$&!%(B %\section{Third party tools for working with patches} \section{$B%Q%C%A8~$1%5!<%I%Q!<%F%#%D!<%k(B} \label{sec:mq:tools} %Once you've been working with patches for a while, you'll find %yourself hungry for tools that will help you to understand and %manipulate the patches you're dealing with. $B$7$P$i$/%Q%C%A$r;H$C$?:n6H$r$7$F$$$k$H!$%Q%C%A$r<h$j07$&=u$1$H$J$k$h$&$J(B $B%D!<%k$,M_$7$/$J$k$K0c$$$J$$!%(B %The \command{diffstat} command~\cite{web:diffstat} generates a %histogram of the modifications made to each file in a patch. It %provides a good way to ``get a sense of'' a patch---which files it %affects, and how much change it introduces to each file and as a %whole. (I find that it's a good idea to use \command{diffstat}'s %\cmdopt{diffstat}{-p} option as a matter of course, as otherwise it %will try to do clever things with prefixes of file names that %inevitably confuse at least me.) \command{diffstat}$B%3%^%s%I(B~\cite{web:diffstat}$B$O%Q%C%AFb$N$=$l$>$l$N%U%!(B $B%$%k$X$NJQ99$N%R%9%H%0%i%`$r@8@.$9$k!%$3$l$O!$%Q%C%A$,1F6A$r5Z$\$9%U%!%$(B $B%k$rGD0.$7$?$j!$A4BN$G$=$l$>$l$N%U%!%$%k$X$I$NDxEYJQ99$r2C$($k$N$+GD0.$9(B $B$k$N$KLrN)$D!%(B $B!J(B\command{diffstat}$B%3%^%s%I$N(B\cmdopt{diffstat}{-p}$B%*%W%7%g(B $B%s$rMQ$$$k$N$OL^O@NI$$9M$($G$"$k!%$5$b$J$1$l$P%3%^%s%I$O%U%!%$%kL>$N(B prefix$B$KBP$7$F(B``$B8-$$(B''$B$3$H$r$7$G$+$9$?$a!$>/$J$/$H$bI.<T$O:.Mp$rHr$1$i$l(B $B$J$+$C$?!%!K(B \begin{figure}[ht] \interaction{mq.tools.tools} % \caption{The \command{diffstat}, \command{filterdiff}, and % \command{lsdiff} commands} \caption{\command{diffstat}, \command{filterdiff}, $B$*$h$S(B \command{lsdiff} $B%3%^%s%I(B} \label{ex:mq:tools} \end{figure} %The \package{patchutils} package~\cite{web:patchutils} is invaluable. %It provides a set of small utilities that follow the ``Unix %philosophy;'' each does one useful thing with a patch. The %\package{patchutils} command I use most is \command{filterdiff}, which %extracts subsets from a patch file. For example, given a patch that %modifies hundreds of files across dozens of directories, a single %invocation of \command{filterdiff} can generate a smaller patch that %only touches files whose names match a particular glob pattern. See %section~\ref{mq-collab:tips:interdiff} for another example. \package{patchutils}$B%Q%C%1!<%8(B~\cite{web:patchutils}$B$OHs>o$KM-MQ$G$"$k!%(B $B$3$N%Q%C%1!<%8$O(B``UNIX$BE/3X(B''$B$K=>$C$?>.$5$J%f!<%F%#%j%F%#$+$i$J$j!$3F!9$N(B $B%f!<%F%#%j%F%#$O%Q%C%A$KBP$7$FM-MQ$JC15!G=$rDs6!$9(B $B$k!%(B\package{patchutils}$B$NCf$GI.<T$,:G$bNI$/;H$&%3%^%s%I$O(B \command{filterdiff}$B$G!$$3$l$O%Q%C%A%U%!%$%k$+$i%Q%C%A$NItJ,=89g$r<h$j=P(B $B$9!%Nc$($P!$(B10$B0J>e$N%G%#%l%/%H%j$K8Y$C$F?tI4$N%U%!%$%k$KJQ99$r9T$&$h$&$J(B $B%Q%C%A$,$"$k$H$7$F!$$?$@0l2s$N(B\command{filterdiff}$B$N<B9T$GFCDj$N%Q%?!<%s(B $B$K%^%C%A$7$?%U%!%$%k$N$_$rJQ99$9$k$h$j>.$5$J%Q%C%A$r@8@.$9$k$3$H$,$G$-(B $B$k!%$=$N$[$+$NNc$O(B\ref{mq-collab:tips:interdiff}$B$r8+$h!%(B %\section{Good ways to work with patches} \section{$B9%$^$7$$%Q%C%A<h$j07$$J}K!(B} %Whether you are working on a patch series to submit to a free software %or open source project, or a series that you intend to treat as a %sequence of regular changesets when you're done, you can use some %simple techniques to keep your work well organized. $B%U%j!<%=%U%H$d%*!<%W%s%=!<%9%W%m%8%'%/%H$KDs=P$9$k$?$a$N%Q%C%A%7%j!<%:$K(B $BBP$7$F:n6H$7$F$$$k$H$-$d!$:n6H$,=*$C$?$H$-$KDL>o$N%A%'%s%8%;%C%H$H$7$F<h(B $B$j9~$^$l$kM=Dj$N%Q%C%A%7%j!<%:$KBP$7$F$@9T$7$F$$$k$H$-$O!$:n6H$r$&$^$/7O(B $BE}$E$1$k$?$a$NC1=c$J%F%/%K%C%/$,$"$k!%(B %Give your patches descriptive names. A good name for a patch might be %\filename{rework-device-alloc.patch}, because it will immediately give %you a hint what the purpose of the patch is. Long names shouldn't be a %problem; you won't be typing the names often, but you \emph{will} be %running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over %and over. Good naming becomes especially important when you have a %number of patches to work with, or if you are juggling a number of %different tasks and your patches only get a fraction of your attention. $B%Q%C%A$K5-=RE*$JL>A0$rM?$($k!%%Q%C%A$KM?$($k$Y$-NI$$L>A0$O(B \filename{rework-device-alloc.patch}$B$N$h$&$J$b$N$G$"$k!%M}M3$OB(:B$K%Q%C(B $B%A$NL\E*$N%R%s%H$rM?$($k$+$i$G$"$k!%D9$$L>A0$OLdBj$K$O$J$i$J$$!%$J$<$J$i(B $BL>A0$r%?%$%W$9$k$3$H$OLGB?$K$J$/!$Be$o$j$K(B\hgxcmd{mq}{qapplied}$B$d(B \hgxcmd{mq}{qtop}$B$N$h$&$J%3%^%s%I$r7+$jJV$7<B9T$9$k$3$H$K$J$k$+$i$G$"$k!%(B $BB??t$N%Q%C%A$KBP$7$F:n6H$r$7$F$$$k$H$-$O!$NI$$L>A0$rIU$1$k$3$H$OFC$K=EMW(B $B$H$J$k!%$=$&$7$J$$$H!$$b$7$"$J$?$,$?$/$5$s$NJL$N%?%9%/$rJz$($F$$$k$J$i(B $B$P!$%Q%C%A$N6hJL$O$D$+$J$/$J$C$F$7$^$&!%(B %Be aware of what patch you're working on. Use the \hgxcmd{mq}{qtop} %command and skim over the text of your patches frequently---for %example, using \hgcmdargs{tip}{\hgopt{tip}{-p}}---to be sure of where %you stand. I have several times worked on and \hgxcmd{mq}{qrefresh}ed a %patch other than the one I intended, and it's often tricky to migrate %changes into the right patch after making them in the wrong one. $B$I$N%Q%C%A$K$D$$$F:n6H$7$F$$$k$N$+GD0.$7$F$*$/$Y$-$G$"(B $B$k!%(B\hgxcmd{mq}{qtop}$B%3%^%s%I$r;H$$!$%Q%C%A$rIQHK$K%A%'%C%/$9$Y$-$G$"$k!%(B $B$^$?!$Nc$($P(B\hgcmdargs{tip}{\hgopt{tip}{-p}}$B$r;H$C$F!$$$$^$I$3$K$$$k$N$+(B $B$rD4$Y$k$3$H$bI,MW$G$"$k!%0U?^$7$F$$$k%Q%C%A0J30$N%Q%C%A$K$D$$$F(B \hgxcmd{mq}{qrefresh}$B$r9T$$!$4V0c$C$?%Q%C%A$K2C$($i$l$?JQ99$r@5$7$$%Q%C%A(B $B$K0\F0$5$;$?!%(B %For this reason, it is very much worth investing a little time to %learn how to use some of the third-party tools I described in %section~\ref{sec:mq:tools}, particularly \command{diffstat} and %\command{filterdiff}. The former will give you a quick idea of what %changes your patch is making, while the latter makes it easy to splice %hunks selectively out of one patch and into another. $B$3$N$?$a!$%;%/%7%g%s(B~\ref{sec:mq:tools}$B$G=R$Y$?%5!<%I%Q!<%F%#@=$N$$$/$D$+(B $B$N%D!<%k!$FC$K(B\command{diffstat}$B$H(B\command{filterdiff}$B$N;H$$J}$r3X$V$N$O(B $B$H$F$b0UL#$,$"$k!%A0<T$O!$$"$J$?$N%Q%C%A$,$I$N$h$&$JJQ99$r2C$($k$N$+B(:B(B $B$KCN$k$3$H$,$G$-!$0lJ}$G8e<T$O%Q%C%A$NCf$N(Bhunk$B$rJL$N%Q%C%A$XA^F~$9$k$N$r(B $BMF0W$K$9$k!%(B %\section{MQ cookbook} \section{MQ$B%/%C%/%V%C%/(B} %\subsection{Manage ``trivial'' patches} \subsection{``$B%H%j%S%"%k(B''$B$J%Q%C%A$N4IM}(B} %Because the overhead of dropping files into a new Mercurial repository %is so low, it makes a lot of sense to manage patches this way even if %you simply want to make a few changes to a source tarball that you %downloaded. $B%U%!%$%k$r(BMercurial$B%j%]%8%H%j$KDI2C$9$k%*!<%P%X%C%I$O>.$5$$!%$3$N$?$a!$$?(B $B$H$(%=!<%9$N(Btar$B%"!<%+%$%V$X>/?t$NJQ99$r2C$($k$@$1$@$H$7$F$b!$%Q%C%A$r%j%](B $B%8%H%j$G4IM}$9$k$N$ONI$$J}K!$G$"$k!%(B %Begin by downloading and unpacking the source tarball, %and turning it into a Mercurial repository. %\interaction{mq.tarball.download} $B%=!<%9(Btarball$B$r%@%&%s%m!<%I$7$FE83+$7!$$3$l$r(BMercurial$B%j%]%8%H%j$KJQ49$9(B $B$k!%(B \interaction{mq.tarball.download} %Continue by creating a patch stack and making your changes. %\interaction{mq.tarball.qinit} $B?7$?$J%Q%C%A%9%?%C%/$r:n$j!$JQ99$r9T$&!%(B \interaction{mq.tarball.qinit} %Let's say a few weeks or months pass, and your package author releases %a new version. First, bring their changes into the repository. %\interaction{mq.tarball.newsource} %The pipeline starting with \hgcmd{locate} above deletes all files in %the working directory, so that \hgcmd{commit}'s %\hgopt{commit}{--addremove} option can actually tell which files have %really been removed in the newer version of the source. $B?t=54V$+$i?t%+7n7P$C$?;~!$%Q%C%1!<%8$N:n<T$,?7$7$$%P!<%8%g%s$r%j%j!<%9$7(B $B$?$H$7$h$&!%$=$N>l9g!$$^$:?7$7$$%P!<%8%g%s$H$N:9J,$r%j%]%8%H%j$K<h$j9~$`!%(B \interaction{mq.tarball.newsource} \hgcmd{locate}$B$N=PNO$r%Q%$%W$G7R$$$G%o!<%-%s%0%G%#%l%/%H%j$N$9$Y$F$N%U%!(B $B%$%k$r>C5n$7!$(B\hgcmd{commit}$B%3%^%s%I$N(B\hgopt{commit}{--addremove}$B%*%W%7%g(B $B%s$r;H$C$F<B:]$K$I$N%U%!%$%k$,?7$7$$%P!<%8%g%s$N%=!<%9$G:o=|$5$l$?$N$+;X(B $BDj$9$k!%(B %Finally, you can apply your patches on top of the new tree. %\interaction{mq.tarball.repush} $B:G8e$K%Q%C%A$r?7$7$$%D%j!<$KE,MQ$9$k!%(B \interaction{mq.tarball.repush} %\subsection{Combining entire patches} \subsection{$B%Q%C%AF1;N$r7k9g$9$k(B} \label{sec:mq:combine} %MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire %patches. This ``folds'' the patches you name, in the order you name %them, into the topmost applied patch, and concatenates their %descriptions onto the end of its description. The patches that you %fold must be unapplied before you fold them. MQ$B$K$O%Q%C%AA4BN$r7k9g$9$k(B\hgxcmd{mq}{qfold}$B$H$$$&%3%^%s%I$,$"$k!%$3$N%3(B $B%^%s%I$OL>A0$r$D$1$?%Q%C%A$rL>IU$1$?=gHV$G:F>e0L$NE,MQ:Q$_%Q%C%A$K>v$_9~(B $B$`!%3F!9$N%Q%C%A$N@bL@$O7k9g$5$l$F%Q%C%A$N@bL@$NKvHx$KDI2C$5$l$k!%>v$_9~(B $B$`%Q%C%A$O$9$G$KE,MQ$5$l$F$$$F$O$J$i$J$$!%(B %The order in which you fold patches matters. If your topmost applied %patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and %\texttt{quux} into it, you will end up with a patch that has the same %effect as if you applied first \texttt{foo}, then \texttt{bar}, %followed by \texttt{quux}. $B%Q%C%A$r>v$_9~$`=gHV$O=EMW$G$"$k!%:#!$:F>e0L$NE,MQ:Q$_%Q%C%A$,(B \texttt{foo}$B$@$H$7$F!$(B\hgxcmd{mq}{qfold} \texttt{bar}$B$H(B\texttt{quux}$B$r9T(B $B$&$H!$%Q%C%A$O(B\texttt{foo}, then \texttt{bar}, \texttt{quux}$B$N=gHV$G%Q%C(B $B%A$rE,MQ$7$?$N$HF1$88z2L$r;}$D$3$H$K$J$k!%(B %\subsection{Merging part of one patch into another} \subsection{$B%Q%C%A$N0lItJ,$rJL$N%Q%C%A$X%^!<%8$9$k(B} %Merging \emph{part} of one patch into another is more difficult than %combining entire patches. $B%Q%C%A$N(B\emph{$B0lIt(B}$B$rJL$N%Q%C%A$X%^!<%8$9$k$3$H$O!$%Q%C%A$r7k9g$9$k$h$j$O(B $BFq$7$$!%(B %If you want to move changes to entire files, you can use %\command{filterdiff}'s \cmdopt{filterdiff}{-i} and %\cmdopt{filterdiff}{-x} options to choose the modifications to snip %out of one patch, concatenating its output onto the end of the patch %you want to merge into.You usually won't need to modify the patch %you've merged the changes from. Instead, MQ will report some rejected %hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the %other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop %the duplicate hunks. $BJQ99$r%U%!%$%k$N=89gA4BN$K0\F0$9$k>l9g!$(B\command{filterdiff}$B$K(B \cmdopt{filterdiff}{-i}$B$H(B\cmdopt{filterdiff}{-x}$B$rIU$1!$(B $B0l$D$N%Q%C%A$+$i<h$k5n$kJQ99!$%Q%C%A$NKvHx$K7k9g$9$kJQ99$rA*$V!%(B $BDL>o$N>l9g!$JQ99$r<h$j=P$7$?%Q%C%A$rJQ99$9$kI,MW$O$J$$!%$=$NBe$o$j!$(BMQ$B$O(B ($BB>$N%Q%C%A$K0\F0$7$?(Bhunk$B$+$i(B)\hgxcmd{mq}{qpush}$B$7$?;~$K%j%8%'%/%H$5$l$?(B hunk$B$rJs9p$9$k!%(B %If you have a patch that has multiple hunks modifying a file, and you %only want to move a few of those hunks, the job becomes more messy, %but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to %print some metadata about the patch. %\interaction{mq.tools.lsdiff} $B%Q%C%A$K0l$D$N%U%!%$%k$rJQ99$9$kJ#?t$N(Bhunk$B$,$"$j!$$=$NCf$N0lIt$r0\F0$7$?(B $B$$>l9g$O!$:n6H$O$b$C$H$d$d$3$7$$$b$N$K$J$k$,!$0MA3$H$7$F0lIt$O<+F02=$9$k(B $B$3$H$,$G$-$k!%(B\cmdargs{lsdiff}{-nvv}$B%3%^%s%I$G%Q%C%A$N%a%?%G!<%?$rI=<($9(B $B$k!%(B\interaction{mq.tools.lsdiff} %This command prints three different kinds of number: $B$3$N%3%^%s%I$O(B3$B$D$N0[$J$kHV9f$r=PNO$9$k(B: \begin{itemize} %\item (in the first column) a \emph{file number} to identify each file % modified in the patch; \item ($B:G=i$NNs(B) $B$3$N%Q%C%A$GJQ99$5$l$k%U%!%$%k$r<1JL$9$k$?$a$N(B\emph{$B%U%!(B $B%$%kHV9f(B} %\item (on the next line, indented) the line number within a modified % file where a hunk starts; and \item ($B<!$N9T$G%$%s%G%s%H$5$l$F$$$k(B) $BJQ99$5$l$?%U%!%$%k$NCf$G(Bhun$B$,;O$^$k(B $B9THV9f(B %\item (on the same line) a \emph{hunk number} to identify that hunk. \item ($B$=$l$HF1$89T(B) $BEv3:(Bhunk$B$r<1JL$9$k(B\emph{hunk$BHV9f(B} \end{itemize} %You'll have to use some visual inspection, and reading of the patch, %to identify the file and hunk numbers you'll want, but you can then %pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files} %and \cmdopt{filterdiff}{--hunks} options, to select exactly the file %and hunk you want to extract. $BI,MW$J%U%!%$%k$H(Bhunk$BHV9f$r8+$D$1$k$?$a$K!$%Q%C%A$rFI$`$J$I$7$FL\;k$G3NG'(B $B$9$kI,MW$,$"$k!%$=$NHV9f$O!$(Bextract$B$9$k%U%!%$%k$H(Bhunk$B$rA*$V$?$a$K(B \command{filterdiff}$B%3%^%s%I$N(B\cmdopt{filterdiff}{--files}$B$H(B \cmdopt{filterdiff}{--hunks}$B%*%W%7%g%s$G;H$($k!%(B %Once you have this hunk, you can concatenate it onto the end of your %destination patch and continue with the remainder of %section~\ref{sec:mq:combine}. $B$3$N(Bhunk$B$,$G$-$?$i!$L\E*$N%Q%C%A$NKvHx$K7k9g$7!$%;%/%7%g%s$N;D$j$NItJ,$r(B $BB3$1$k$3$H$,$G$-$k(B~\ref{sec:mq:combine}$B!%(B %\section{Differences between quilt and MQ} \section{quilt$B$H(BMQ$B$N0c$$(B} %If you are already familiar with quilt, MQ provides a similar command %set. There are a few differences in the way that it works. $B$9$G$K(Bquilt$B$KFk@w$s$G$$$k%f!<%6$N$?$a$K!$(BMQ$B$OF1MM$N%3%^%s%I%;%C%H$rMQ0U(B $B$7$F$$$k!%%3%^%s%I$N5sF0$K$O2?E@$+0c$$$,$"$k!%(B %You will already have noticed that most quilt commands have MQ %counterparts that simply begin with a ``\texttt{q}''. The exceptions %are quilt's \texttt{add} and \texttt{remove} commands, the %counterparts for which are the normal Mercurial \hgcmd{add} and %\hgcmd{remove} commands. There is no MQ equivalent of the quilt %\texttt{edit} command. $B$9$G$K$[$H$s$I$N(Bquilt$B%3%^%s%I$K$O!$BP1~$9$k(B``\texttt{q}''$B$G;O$^$k(BMQ$B%3%^%s(B $B%I$,$"$k$3$H$K5$$E$$$F$$$k$3$H$H;W$&!%Nc30$O!$(Bquilt$B$N(B\texttt{add}$B%3%^%s%I(B $B$H(B\texttt{remove}$B%3%^%s%I$G!$$3$l$i$K$O$=$l$>$lDL>o$N(BMercurial$B%3%^%s%I$N(B \hgcmd{add}$B$H(B\hgcmd{remove}$B$,BP1~$9$k!%$^$?!$(Bquilt$B$N(B\texttt{edit}$B%3%^%s%I(B $B$KBP1~$9$k(BMQ$B%3%^%s%I$O$J$$!%(B %%% Local Variables: %%% mode: yatex %%% TeX-master: "00book" %%% End: