comparison ja/mq.tex @ 329:d520107e32e7

more mq.tex

328:8bdd9bc948d4

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.

Fortunately, Mercurial includes a powerful extension, Mercurial Queues
(or simply ``MQ''), that massively simplifies the patch management
problem.

%\section{The prehistory of Mercurial Queues}
\section{Mercurial Queues$BA0;K(B}
\label{sec:mq:history}

 %  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.)




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~-}''.

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.

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.

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.

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.

%\section{Getting started with Mercurial Queues}
\section{Mercurial Queues$B$r;H$C$F$_$k(B}
\label{sec:mq:start}

329:d520107e32e7

%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}

 %  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}