comparison en/mq.tex @ 233:696b1e0c01df

Tag all MQ commands as belonging to the mq extension.

232:2469608b4a08

  \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
\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 \hgcmd{qinit} command is now available; see
the example in figure~\ref{ex:mq:enabled}.

\begin{figure}[ht]
  \interaction{mq.qinit-help.help}
  \caption{How to verify that MQ is enabled}
  \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 \hgcmd{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 \hgcmd{qinit} command prints nothing
if it succeeds.

\begin{figure}[ht]
  \interaction{mq.tutorial.qinit}
  \caption{Preparing a repository for use with MQ}

  \label{ex:mq:qnew}
\end{figure}

\subsection{Creating a new patch}

To begin work on a new patch, use the \hgcmd{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}.

Also newly present in the \sdirname{.hg/patches} directory are two

they did before.

\subsection{Refreshing a patch}

When you reach a point where you want to save your work, use the
\hgcmd{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.

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh}
  \caption{Refreshing a patch}
  \label{ex:mq:qrefresh}
\end{figure}

You can run \hgcmd{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.

\begin{figure}[ht]

\end{figure}

\subsection{Stacking and tracking patches}

Once you have finished working on a patch, or need to work on another,
you can use the \hgcmd{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}).

  \interaction{mq.tutorial.qnew2}
  \caption{Stacking a second patch on top of the first}
  \label{ex:mq:qnew2}
\end{figure}

So far, with the exception of \hgcmd{qnew} and \hgcmd{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}:

\begin{itemize}
\item The \hgcmd{qseries} command lists every patch that MQ knows
  about in this repository, from oldest to newest (most recently
  \emph{created}).
\item The \hgcmd{qapplied} command lists every patch that MQ has
  \emph{applied} in this repository, again from oldest to newest (most
  recently applied).
\end{itemize}

\begin{figure}[ht]
  \interaction{mq.tutorial.qseries}
  \caption{Understanding the patch stack with \hgcmd{qseries} and
    \hgcmd{qapplied}}
  \label{ex:mq:qseries}
\end{figure}

\subsection{Manipulating the patch stack}

manage a patch without it being applied in the repository.

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

  \grafix{mq-stack}
  \caption{Applied and unapplied patches in the MQ patch stack}
  \label{fig:mq:stack}
\end{figure}

You can reapply an unapplied, or popped, patch using the \hgcmd{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 \hgcmd{qpop}
and \hgcmd{qpush} in action.  Notice that once we have popped a patch
or two patches, the output of \hgcmd{qseries} remains the same, while
that of \hgcmd{qapplied} has changed.

\begin{figure}[ht]
  \interaction{mq.tutorial.qpop}
  \caption{Modifying the stack of applied patches}
  \label{ex:mq:qpop}
\end{figure}

\subsection{Pushing and popping many patches}

While \hgcmd{qpush} and \hgcmd{qpop} each operate on a single patch at
a time by default, you can push and pop many patches in one go.  The
\hgopt{qpush}{-a} option to \hgcmd{qpush} causes it to push all
unapplied patches, while the \hgopt{qpop}{-a} option to \hgcmd{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.)

\begin{figure}[ht]
  \interaction{mq.tutorial.qpush-a}

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 \hgcmd{qnew} command will not create a new patch if there are
outstanding changes, caused in this case by the \hgcmd{add} of
\filename{file3}.

\begin{figure}[ht]
  \interaction{mq.tutorial.add}

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!

\subsection{Working on several patches at once}

The \hgcmd{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.

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
\hgcmd{qrefresh} the UI patch to save your in-progress changes, and
\hgcmd{qpop} down to the core patch.  Fix the core bug,
\hgcmd{qrefresh} the core patch, and \hgcmd{qpush} back to the UI
patch to continue where you left off.

\section{More about patches}
\label{sec:mq:adv-patch}

and the \hgcmd{import} command and MQ expect patches to have a strip
count of one.

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 \hgcmd{qimport} the patch, because \hgcmd{qimport} does not yet
have a \texttt{-p} option (see~\bug{311}).  Your best bet is to
\hgcmd{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 \hgcmd{qrefresh}.
This complexity may become unnecessary; see~\bug{311} for details.
\subsection{Strategies for applying a patch}

When \command{patch} applies a hunk, it tries a handful of
successively less accurate strategies to try to make the hunk apply.

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 \hgcmd{qpush} ever
mentions an offset or fuzz factor, you should make sure that the
modified files are correct afterwards.  

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

apply with some fuzz, provided you've verified the results of the
patching process in such cases.

\subsection{Handling rejection}

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

If your patch \emph{used to} apply cleanly, and no longer does because

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

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

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

The \hgcmd{qpush} and \hgcmd{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 \hgcmd{qpush} with a
destination specified, it will push patches until that patch is at the
top of the applied stack.  When you \hgcmd{qpop} to a destination, MQ
will pop patches until the destination patch is at the top.

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

The simplest way to do this is to \hgcmdargs{qpop}{\hgopt{qpop}{-a}}
your patches, then \hgcmd{pull} changes into the underlying
repository, and finally \hgcmdargs{qpush}{\hgopt{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, \hgcmd{qrefresh} the affected patch, and continue pushing
until you have fixed your entire stack.

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

  repository.  (Don't run \hgcmdargs{pull}{-u}; see below for why.)
\item Update to the new tip revision, using
  \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
  have pushed.
\item Merge all patches using \hgcmdargs{qpush}{\hgopt{qpush}{-m}
    \hgopt{qpush}{-a}}.  The \hgopt{qpush}{-m} option to \hgcmd{qpush}
  tells MQ to perform a three-way merge if the patch fails to apply.
\end{enumerate}

During the \hgcmdargs{qpush}{\hgopt{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 \hgcmd{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.

When you finish resolving the effects of a patch, MQ refreshes your

\section{Identifying patches}

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 \hgcmd{qpush}, for example, and it will
push patches until \filename{foo.patch} is applied.  

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

Referring to a patch by index isn't much different.  The first patch
printed in the output of \hgcmd{qseries} is patch zero (yes, it's one
of those start-at-zero counting systems); the second is patch one; and
so on

MQ also makes it easy to work with patches when you are using normal
Mercurial commands.  Every command that accepts a changeset ID will

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 \hgcmd{qpop} a patch and \hgcmd{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

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, \hgcmd{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

\subsection{MQ support for patch repositories}

MQ helps you to work with the \sdirname{.hg/patches} directory as a
repository; when you prepare a repository for working with patches
using \hgcmd{qinit}, you can pass the \hgopt{qinit}{-c} option to
create the \sdirname{.hg/patches} directory as a Mercurial repository.

\begin{note}
  If you forget to use the \hgopt{qinit}{-c} option, you can simply go
  into the \sdirname{.hg/patches} directory at any time and run

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.

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

\subsection{A few things to watch out for}

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 \hgcmd{qapplied} and \hgcmd{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.

Be aware of what patch you're working on.  Use the \hgcmd{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 \hgcmd{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.

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

\interaction{mq.tarball.repush}

\subsection{Combining entire patches}
\label{sec:mq:combine}

MQ provides a command, \hgcmd{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 \hgcmd{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}

\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 \hgcmd{qpush} it (from the hunks you moved into the
other patch), and you can simply \hgcmd{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

233:696b1e0c01df

  \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
\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}.

\begin{figure}[ht]
  \interaction{mq.qinit-help.help}
  \caption{How to verify that MQ is enabled}
  \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.

\begin{figure}[ht]
  \interaction{mq.tutorial.qinit}
  \caption{Preparing a repository for use with MQ}

  \label{ex:mq:qnew}
\end{figure}

\subsection{Creating a new patch}

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

Also newly present in the \sdirname{.hg/patches} directory are two

they did before.

\subsection{Refreshing a patch}

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.

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh}
  \caption{Refreshing a patch}
  \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.

\begin{figure}[ht]

\end{figure}

\subsection{Stacking and tracking patches}

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

  \interaction{mq.tutorial.qnew2}
  \caption{Stacking a second patch on top of the first}
  \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}:

\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{figure}[ht]
  \interaction{mq.tutorial.qseries}
  \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and
    \hgxcmd{mq}{qapplied}}
  \label{ex:mq:qseries}
\end{figure}

\subsection{Manipulating the patch stack}

manage a patch without it being applied in the repository.

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.

  \grafix{mq-stack}
  \caption{Applied and unapplied patches in the MQ patch stack}
  \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.

\begin{figure}[ht]
  \interaction{mq.tutorial.qpop}
  \caption{Modifying the stack of applied patches}
  \label{ex:mq:qpop}
\end{figure}

\subsection{Pushing and popping many patches}

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
\hgopt{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all
unapplied patches, while the \hgopt{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.)

\begin{figure}[ht]
  \interaction{mq.tutorial.qpush-a}

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

\begin{figure}[ht]
  \interaction{mq.tutorial.add}

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!

\subsection{Working on several patches at once}

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.

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.

\section{More about patches}
\label{sec:mq:adv-patch}

and the \hgcmd{import} command and MQ expect patches to have a strip
count of one.

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.
\subsection{Strategies for applying a patch}

When \command{patch} applies a hunk, it tries a handful of
successively less accurate strategies to try to make the hunk apply.

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.  

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

apply with some fuzz, provided you've verified the results of the
patching process in such cases.

\subsection{Handling rejection}

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

If your patch \emph{used to} apply cleanly, and no longer does because

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

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

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

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

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

The simplest way to do this is to \hgcmdargs{qpop}{\hgopt{qpop}{-a}}
your patches, then \hgcmd{pull} changes into the underlying
repository, and finally \hgcmdargs{qpush}{\hgopt{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.

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

  repository.  (Don't run \hgcmdargs{pull}{-u}; see below for why.)
\item Update to the new tip revision, using
  \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
  have pushed.
\item Merge all patches using \hgcmdargs{qpush}{\hgopt{qpush}{-m}
    \hgopt{qpush}{-a}}.  The \hgopt{qpush}{-m} option to \hgxcmd{mq}{qpush}
  tells MQ to perform a three-way merge if the patch fails to apply.
\end{enumerate}

During the \hgcmdargs{qpush}{\hgopt{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.

When you finish resolving the effects of a patch, MQ refreshes your

\section{Identifying patches}

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.  

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

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

MQ also makes it easy to work with patches when you are using normal
Mercurial commands.  Every command that accepts a changeset ID will

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

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

\subsection{MQ support for patch repositories}

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 \hgopt{qinit}{-c} option to
create the \sdirname{.hg/patches} directory as a Mercurial repository.

\begin{note}
  If you forget to use the \hgopt{qinit}{-c} option, you can simply go
  into the \sdirname{.hg/patches} directory at any time and run

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.

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

\subsection{A few things to watch out for}

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.

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.

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

\interaction{mq.tarball.repush}

\subsection{Combining entire patches}
\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}

\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