comparison ja/mq.tex @ 346:0b99bf82b573

more mq.tex

345:6da6c5741e90

%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$,$=$l$[$I0c$o$J$$%Q%C%A$X$N;2>H$O(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.

%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

%  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 \texttt{foo.patch}$B0J9_$N$9$Y$F$N%Q%C%A$r8+$?$$$+!)(B

$B%D%j!<$NCf$N%5%V%D%j!<(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.

\begin{figure}[ht]
  \interaction{mq.id.output}
  \caption{Using MQ's tag features to work with patches}
  \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.

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

\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 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.
\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.

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.

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.

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.

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

\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.
\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.

MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs
\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
some bothersome typing.

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

\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.

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

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

MQ cannot automatically detect changes that you make to the patch
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.

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

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

\begin{figure}[ht]
  \interaction{mq.tools.tools}
  \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
  \label{ex:mq:tools}

\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.

Begin by downloading and unpacking the source tarball,
and turning it into a Mercurial repository.
\interaction{mq.tarball.download}

Continue by creating a patch stack and making your changes.
\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.

Finally, you can apply your patches on top of the new tree.
\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.

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

%\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(B
$B$OFq$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.




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}

This command prints three different kinds of number:
\begin{itemize}
\item (in the first column) a \emph{file number} to identify each file
  modified in the patch;
\item (on the next line, indented) the line number within a modified
  file where a hunk starts; and
\item (on the same line) a \emph{hunk number} to identify that hunk.
\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.

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

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

$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: 

346:0b99bf82b573

%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

%  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!%(B

$B$3$l$O!$%Q%C%A$,1F6A$r5Z$\$9%U%!%$%k$rGD0.$7$?$j!$A4BN$G$=$l$>$l$N%U%!%$(B
$B%k$X$I$NDxEYJQ99$r2C$($k$N$+GD0.$9$k$N$KLrN)$D!%(B
(\command{diffstat}$B%3%^%s%I$N(B\cmdopt{diffstat}{-p}$B%*%W%7%g%s$,(B


)


\begin{figure}[ht]
  \interaction{mq.tools.tools}
  \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
  \label{ex:mq:tools}

\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%Q%C%A%9%?%C%/$r:n$jJQ99$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

$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: