1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/mq.tex	Mon Feb 09 14:42:43 2009 +0100
     1.3 @@ -0,0 +1,1043 @@
     1.4 +\chapter{Managing change with Mercurial Queues}
     1.5 +\label{chap:mq}
     1.6 +
     1.7 +\section{The patch management problem}
     1.8 +\label{sec:mq:patch-mgmt}
     1.9 +
    1.10 +Here is a common scenario: you need to install a software package from
    1.11 +source, but you find a bug that you must fix in the source before you
    1.12 +can start using the package.  You make your changes, forget about the
    1.13 +package for a while, and a few months later you need to upgrade to a
    1.14 +newer version of the package.  If the newer version of the package
    1.15 +still has the bug, you must extract your fix from the older source
    1.16 +tree and apply it against the newer version.  This is a tedious task,
    1.17 +and it's easy to make mistakes.
    1.18 +
    1.19 +This is a simple case of the ``patch management'' problem.  You have
    1.20 +an ``upstream'' source tree that you can't change; you need to make
    1.21 +some local changes on top of the upstream tree; and you'd like to be
    1.22 +able to keep those changes separate, so that you can apply them to
    1.23 +newer versions of the upstream source.
    1.24 +
    1.25 +The patch management problem arises in many situations.  Probably the
    1.26 +most visible is that a user of an open source software project will
    1.27 +contribute a bug fix or new feature to the project's maintainers in the
    1.28 +form of a patch.
    1.29 +
    1.30 +Distributors of operating systems that include open source software
    1.31 +often need to make changes to the packages they distribute so that
    1.32 +they will build properly in their environments.
    1.33 +
    1.34 +When you have few changes to maintain, it is easy to manage a single
    1.35 +patch using the standard \command{diff} and \command{patch} programs
    1.36 +(see section~\ref{sec:mq:patch} for a discussion of these tools).
    1.37 +Once the number of changes grows, it starts to make sense to maintain
    1.38 +patches as discrete ``chunks of work,'' so that for example a single
    1.39 +patch will contain only one bug fix (the patch might modify several
    1.40 +files, but it's doing ``only one thing''), and you may have a number
    1.41 +of such patches for different bugs you need fixed and local changes
    1.42 +you require.  In this situation, if you submit a bug fix patch to the
    1.43 +upstream maintainers of a package and they include your fix in a
    1.44 +subsequent release, you can simply drop that single patch when you're
    1.45 +updating to the newer release.
    1.46 +
    1.47 +Maintaining a single patch against an upstream tree is a little
    1.48 +tedious and error-prone, but not difficult.  However, the complexity
    1.49 +of the problem grows rapidly as the number of patches you have to
    1.50 +maintain increases.  With more than a tiny number of patches in hand,
    1.51 +understanding which ones you have applied and maintaining them moves
    1.52 +from messy to overwhelming.
    1.53 +
    1.54 +Fortunately, Mercurial includes a powerful extension, Mercurial Queues
    1.55 +(or simply ``MQ''), that massively simplifies the patch management
    1.56 +problem.
    1.57 +
    1.58 +\section{The prehistory of Mercurial Queues}
    1.59 +\label{sec:mq:history}
    1.60 +
    1.61 +During the late 1990s, several Linux kernel developers started to
    1.62 +maintain ``patch series'' that modified the behaviour of the Linux
    1.63 +kernel.  Some of these series were focused on stability, some on
    1.64 +feature coverage, and others were more speculative.
    1.65 +
    1.66 +The sizes of these patch series grew rapidly.  In 2002, Andrew Morton
    1.67 +published some shell scripts he had been using to automate the task of
    1.68 +managing his patch queues.  Andrew was successfully using these
    1.69 +scripts to manage hundreds (sometimes thousands) of patches on top of
    1.70 +the Linux kernel.
    1.71 +
    1.72 +\subsection{A patchwork quilt}
    1.73 +\label{sec:mq:quilt}
    1.74 +
    1.75 +In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
    1.76 +approach of Andrew's scripts and published a tool called ``patchwork
    1.77 +quilt''~\cite{web:quilt}, or simply ``quilt''
    1.78 +(see~\cite{gruenbacher:2005} for a paper describing it).  Because
    1.79 +quilt substantially automated patch management, it rapidly gained a
    1.80 +large following among open source software developers.
    1.81 +
    1.82 +Quilt manages a \emph{stack of patches} on top of a directory tree.
    1.83 +To begin, you tell quilt to manage a directory tree, and tell it which
    1.84 +files you want to manage; it stores away the names and contents of
    1.85 +those files.  To fix a bug, you create a new patch (using a single
    1.86 +command), edit the files you need to fix, then ``refresh'' the patch.
    1.87 +
    1.88 +The refresh step causes quilt to scan the directory tree; it updates
    1.89 +the patch with all of the changes you have made.  You can create
    1.90 +another patch on top of the first, which will track the changes
    1.91 +required to modify the tree from ``tree with one patch applied'' to
    1.92 +``tree with two patches applied''.
    1.93 +
    1.94 +You can \emph{change} which patches are applied to the tree.  If you
    1.95 +``pop'' a patch, the changes made by that patch will vanish from the
    1.96 +directory tree.  Quilt remembers which patches you have popped,
    1.97 +though, so you can ``push'' a popped patch again, and the directory
    1.98 +tree will be restored to contain the modifications in the patch.  Most
    1.99 +importantly, you can run the ``refresh'' command at any time, and the
   1.100 +topmost applied patch will be updated.  This means that you can, at
   1.101 +any time, change both which patches are applied and what
   1.102 +modifications those patches make.
   1.103 +
   1.104 +Quilt knows nothing about revision control tools, so it works equally
   1.105 +well on top of an unpacked tarball or a Subversion working copy.
   1.106 +
   1.107 +\subsection{From patchwork quilt to Mercurial Queues}
   1.108 +\label{sec:mq:quilt-mq}
   1.109 +
   1.110 +In mid-2005, Chris Mason took the features of quilt and wrote an
   1.111 +extension that he called Mercurial Queues, which added quilt-like
   1.112 +behaviour to Mercurial.
   1.113 +
   1.114 +The key difference between quilt and MQ is that quilt knows nothing
   1.115 +about revision control systems, while MQ is \emph{integrated} into
   1.116 +Mercurial.  Each patch that you push is represented as a Mercurial
   1.117 +changeset.  Pop a patch, and the changeset goes away.
   1.118 +
   1.119 +Because quilt does not care about revision control tools, it is still
   1.120 +a tremendously useful piece of software to know about for situations
   1.121 +where you cannot use Mercurial and MQ.
   1.122 +
   1.123 +\section{The huge advantage of MQ}
   1.124 +
   1.125 +I cannot overstate the value that MQ offers through the unification of
   1.126 +patches and revision control.
   1.127 +
   1.128 +A major reason that patches have persisted in the free software and
   1.129 +open source world---in spite of the availability of increasingly
   1.130 +capable revision control tools over the years---is the \emph{agility}
   1.131 +they offer.  
   1.132 +
   1.133 +Traditional revision control tools make a permanent, irreversible
   1.134 +record of everything that you do.  While this has great value, it's
   1.135 +also somewhat stifling.  If you want to perform a wild-eyed
   1.136 +experiment, you have to be careful in how you go about it, or you risk
   1.137 +leaving unneeded---or worse, misleading or destabilising---traces of
   1.138 +your missteps and errors in the permanent revision record.
   1.139 +
   1.140 +By contrast, MQ's marriage of distributed revision control with
   1.141 +patches makes it much easier to isolate your work.  Your patches live
   1.142 +on top of normal revision history, and you can make them disappear or
   1.143 +reappear at will.  If you don't like a patch, you can drop it.  If a
   1.144 +patch isn't quite as you want it to be, simply fix it---as many times
   1.145 +as you need to, until you have refined it into the form you desire.
   1.146 +
   1.147 +As an example, the integration of patches with revision control makes
   1.148 +understanding patches and debugging their effects---and their
   1.149 +interplay with the code they're based on---\emph{enormously} easier.
   1.150 +Since every applied patch has an associated changeset, you can use
   1.151 +\hgcmdargs{log}{\emph{filename}} to see which changesets and patches
   1.152 +affected a file.  You can use the \hgext{bisect} command to
   1.153 +binary-search through all changesets and applied patches to see where
   1.154 +a bug got introduced or fixed.  You can use the \hgcmd{annotate}
   1.155 +command to see which changeset or patch modified a particular line of
   1.156 +a source file.  And so on.
   1.157 +
   1.158 +\section{Understanding patches}
   1.159 +\label{sec:mq:patch}
   1.160 +
   1.161 +Because MQ doesn't hide its patch-oriented nature, it is helpful to
   1.162 +understand what patches are, and a little about the tools that work
   1.163 +with them.
   1.164 +
   1.165 +The traditional Unix \command{diff} command compares two files, and
   1.166 +prints a list of differences between them. The \command{patch} command
   1.167 +understands these differences as \emph{modifications} to make to a
   1.168 +file.  Take a look at figure~\ref{ex:mq:diff} for a simple example of
   1.169 +these commands in action.
   1.170 +
   1.171 +\begin{figure}[ht]
   1.172 +  \interaction{mq.dodiff.diff}
   1.173 +  \caption{Simple uses of the \command{diff} and \command{patch} commands}
   1.174 +  \label{ex:mq:diff}
   1.175 +\end{figure}
   1.176 +
   1.177 +The type of file that \command{diff} generates (and \command{patch}
   1.178 +takes as input) is called a ``patch'' or a ``diff''; there is no
   1.179 +difference between a patch and a diff.  (We'll use the term ``patch'',
   1.180 +since it's more commonly used.)
   1.181 +
   1.182 +A patch file can start with arbitrary text; the \command{patch}
   1.183 +command ignores this text, but MQ uses it as the commit message when
   1.184 +creating changesets.  To find the beginning of the patch content,
   1.185 +\command{patch} searches for the first line that starts with the
   1.186 +string ``\texttt{diff~-}''.
   1.187 +
   1.188 +MQ works with \emph{unified} diffs (\command{patch} can accept several
   1.189 +other diff formats, but MQ doesn't).  A unified diff contains two
   1.190 +kinds of header.  The \emph{file header} describes the file being
   1.191 +modified; it contains the name of the file to modify.  When
   1.192 +\command{patch} sees a new file header, it looks for a file with that
   1.193 +name to start modifying.
   1.194 +
   1.195 +After the file header comes a series of \emph{hunks}.  Each hunk
   1.196 +starts with a header; this identifies the range of line numbers within
   1.197 +the file that the hunk should modify.  Following the header, a hunk
   1.198 +starts and ends with a few (usually three) lines of text from the
   1.199 +unmodified file; these are called the \emph{context} for the hunk.  If
   1.200 +there's only a small amount of context between successive hunks,
   1.201 +\command{diff} doesn't print a new hunk header; it just runs the hunks
   1.202 +together, with a few lines of context between modifications.
   1.203 +
   1.204 +Each line of context begins with a space character.  Within the hunk,
   1.205 +a line that begins with ``\texttt{-}'' means ``remove this line,''
   1.206 +while a line that begins with ``\texttt{+}'' means ``insert this
   1.207 +line.''  For example, a line that is modified is represented by one
   1.208 +deletion and one insertion.
   1.209 +
   1.210 +We will return to some of the more subtle aspects of patches later (in
   1.211 +section~\ref{sec:mq:adv-patch}), but you should have enough information
   1.212 +now to use MQ.
   1.213 +
   1.214 +\section{Getting started with Mercurial Queues}
   1.215 +\label{sec:mq:start}
   1.216 +
   1.217 +Because MQ is implemented as an extension, you must explicitly enable
   1.218 +before you can use it.  (You don't need to download anything; MQ ships
   1.219 +with the standard Mercurial distribution.)  To enable MQ, edit your
   1.220 +\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.
   1.221 +
   1.222 +\begin{figure}[ht]
   1.223 +  \begin{codesample4}
   1.224 +    [extensions]
   1.225 +    hgext.mq =
   1.226 +  \end{codesample4}
   1.227 +  \label{ex:mq:config}
   1.228 +  \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
   1.229 +\end{figure}
   1.230 +
   1.231 +Once the extension is enabled, it will make a number of new commands
   1.232 +available.  To verify that the extension is working, you can use
   1.233 +\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see
   1.234 +the example in figure~\ref{ex:mq:enabled}.
   1.235 +
   1.236 +\begin{figure}[ht]
   1.237 +  \interaction{mq.qinit-help.help}
   1.238 +  \caption{How to verify that MQ is enabled}
   1.239 +  \label{ex:mq:enabled}
   1.240 +\end{figure}
   1.241 +
   1.242 +You can use MQ with \emph{any} Mercurial repository, and its commands
   1.243 +only operate within that repository.  To get started, simply prepare
   1.244 +the repository using the \hgxcmd{mq}{qinit} command (see
   1.245 +figure~\ref{ex:mq:qinit}).  This command creates an empty directory
   1.246 +called \sdirname{.hg/patches}, where MQ will keep its metadata.  As
   1.247 +with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing
   1.248 +if it succeeds.
   1.249 +
   1.250 +\begin{figure}[ht]
   1.251 +  \interaction{mq.tutorial.qinit}
   1.252 +  \caption{Preparing a repository for use with MQ}
   1.253 +  \label{ex:mq:qinit}
   1.254 +\end{figure}
   1.255 +
   1.256 +\begin{figure}[ht]
   1.257 +  \interaction{mq.tutorial.qnew}
   1.258 +  \caption{Creating a new patch}
   1.259 +  \label{ex:mq:qnew}
   1.260 +\end{figure}
   1.261 +
   1.262 +\subsection{Creating a new patch}
   1.263 +
   1.264 +To begin work on a new patch, use the \hgxcmd{mq}{qnew} command.  This
   1.265 +command takes one argument, the name of the patch to create.  MQ will
   1.266 +use this as the name of an actual file in the \sdirname{.hg/patches}
   1.267 +directory, as you can see in figure~\ref{ex:mq:qnew}.
   1.268 +
   1.269 +Also newly present in the \sdirname{.hg/patches} directory are two
   1.270 +other files, \sfilename{series} and \sfilename{status}.  The
   1.271 +\sfilename{series} file lists all of the patches that MQ knows about
   1.272 +for this repository, with one patch per line.  Mercurial uses the
   1.273 +\sfilename{status} file for internal book-keeping; it tracks all of the
   1.274 +patches that MQ has \emph{applied} in this repository.
   1.275 +
   1.276 +\begin{note}
   1.277 +  You may sometimes want to edit the \sfilename{series} file by hand;
   1.278 +  for example, to change the sequence in which some patches are
   1.279 +  applied.  However, manually editing the \sfilename{status} file is
   1.280 +  almost always a bad idea, as it's easy to corrupt MQ's idea of what
   1.281 +  is happening.
   1.282 +\end{note}
   1.283 +
   1.284 +Once you have created your new patch, you can edit files in the
   1.285 +working directory as you usually would.  All of the normal Mercurial
   1.286 +commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
   1.287 +they did before.
   1.288 +
   1.289 +\subsection{Refreshing a patch}
   1.290 +
   1.291 +When you reach a point where you want to save your work, use the
   1.292 +\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
   1.293 +you are working on.  This command folds the changes you have made in
   1.294 +the working directory into your patch, and updates its corresponding
   1.295 +changeset to contain those changes.
   1.296 +
   1.297 +\begin{figure}[ht]
   1.298 +  \interaction{mq.tutorial.qrefresh}
   1.299 +  \caption{Refreshing a patch}
   1.300 +  \label{ex:mq:qrefresh}
   1.301 +\end{figure}
   1.302 +
   1.303 +You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way
   1.304 +to ``checkpoint'' your work.  Refresh your patch at an opportune
   1.305 +time; try an experiment; and if the experiment doesn't work out,
   1.306 +\hgcmd{revert} your modifications back to the last time you refreshed.
   1.307 +
   1.308 +\begin{figure}[ht]
   1.309 +  \interaction{mq.tutorial.qrefresh2}
   1.310 +  \caption{Refresh a patch many times to accumulate changes}
   1.311 +  \label{ex:mq:qrefresh2}
   1.312 +\end{figure}
   1.313 +
   1.314 +\subsection{Stacking and tracking patches}
   1.315 +
   1.316 +Once you have finished working on a patch, or need to work on another,
   1.317 +you can use the \hgxcmd{mq}{qnew} command again to create a new patch.
   1.318 +Mercurial will apply this patch on top of your existing patch.  See
   1.319 +figure~\ref{ex:mq:qnew2} for an example.  Notice that the patch
   1.320 +contains the changes in our prior patch as part of its context (you
   1.321 +can see this more clearly in the output of \hgcmd{annotate}).
   1.322 +
   1.323 +\begin{figure}[ht]
   1.324 +  \interaction{mq.tutorial.qnew2}
   1.325 +  \caption{Stacking a second patch on top of the first}
   1.326 +  \label{ex:mq:qnew2}
   1.327 +\end{figure}
   1.328 +
   1.329 +So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've
   1.330 +been careful to only use regular Mercurial commands.  However, MQ
   1.331 +provides many commands that are easier to use when you are thinking
   1.332 +about patches, as illustrated in figure~\ref{ex:mq:qseries}:
   1.333 +
   1.334 +\begin{itemize}
   1.335 +\item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows
   1.336 +  about in this repository, from oldest to newest (most recently
   1.337 +  \emph{created}).
   1.338 +\item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has
   1.339 +  \emph{applied} in this repository, again from oldest to newest (most
   1.340 +  recently applied).
   1.341 +\end{itemize}
   1.342 +
   1.343 +\begin{figure}[ht]
   1.344 +  \interaction{mq.tutorial.qseries}
   1.345 +  \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and
   1.346 +    \hgxcmd{mq}{qapplied}}
   1.347 +  \label{ex:mq:qseries}
   1.348 +\end{figure}
   1.349 +
   1.350 +\subsection{Manipulating the patch stack}
   1.351 +
   1.352 +The previous discussion implied that there must be a difference
   1.353 +between ``known'' and ``applied'' patches, and there is.  MQ can
   1.354 +manage a patch without it being applied in the repository.
   1.355 +
   1.356 +An \emph{applied} patch has a corresponding changeset in the
   1.357 +repository, and the effects of the patch and changeset are visible in
   1.358 +the working directory.  You can undo the application of a patch using
   1.359 +the \hgxcmd{mq}{qpop} command.  MQ still \emph{knows about}, or manages, a
   1.360 +popped patch, but the patch no longer has a corresponding changeset in
   1.361 +the repository, and the working directory does not contain the changes
   1.362 +made by the patch.  Figure~\ref{fig:mq:stack} illustrates the
   1.363 +difference between applied and tracked patches.
   1.364 +
   1.365 +\begin{figure}[ht]
   1.366 +  \centering
   1.367 +  \grafix{mq-stack}
   1.368 +  \caption{Applied and unapplied patches in the MQ patch stack}
   1.369 +  \label{fig:mq:stack}
   1.370 +\end{figure}
   1.371 +
   1.372 +You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush}
   1.373 +command.  This creates a new changeset to correspond to the patch, and
   1.374 +the patch's changes once again become present in the working
   1.375 +directory.  See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop}
   1.376 +and \hgxcmd{mq}{qpush} in action.  Notice that once we have popped a patch
   1.377 +or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while
   1.378 +that of \hgxcmd{mq}{qapplied} has changed.
   1.379 +
   1.380 +\begin{figure}[ht]
   1.381 +  \interaction{mq.tutorial.qpop}
   1.382 +  \caption{Modifying the stack of applied patches}
   1.383 +  \label{ex:mq:qpop}
   1.384 +\end{figure}
   1.385 +
   1.386 +\subsection{Pushing and popping many patches}
   1.387 +
   1.388 +While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at
   1.389 +a time by default, you can push and pop many patches in one go.  The
   1.390 +\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all
   1.391 +unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop}
   1.392 +causes it to pop all applied patches.  (For some more ways to push and
   1.393 +pop many patches, see section~\ref{sec:mq:perf} below.)
   1.394 +
   1.395 +\begin{figure}[ht]
   1.396 +  \interaction{mq.tutorial.qpush-a}
   1.397 +  \caption{Pushing all unapplied patches}
   1.398 +  \label{ex:mq:qpush-a}
   1.399 +\end{figure}
   1.400 +
   1.401 +\subsection{Safety checks, and overriding them}
   1.402 +
   1.403 +Several MQ commands check the working directory before they do
   1.404 +anything, and fail if they find any modifications.  They do this to
   1.405 +ensure that you won't lose any changes that you have made, but not yet
   1.406 +incorporated into a patch.  Figure~\ref{ex:mq:add} illustrates this;
   1.407 +the \hgxcmd{mq}{qnew} command will not create a new patch if there are
   1.408 +outstanding changes, caused in this case by the \hgcmd{add} of
   1.409 +\filename{file3}.
   1.410 +
   1.411 +\begin{figure}[ht]
   1.412 +  \interaction{mq.tutorial.add}
   1.413 +  \caption{Forcibly creating a patch}
   1.414 +  \label{ex:mq:add}
   1.415 +\end{figure}
   1.416 +
   1.417 +Commands that check the working directory all take an ``I know what
   1.418 +I'm doing'' option, which is always named \option{-f}.  The exact
   1.419 +meaning of \option{-f} depends on the command.  For example,
   1.420 +\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding
   1.421 +changes into the new patch it creates, but
   1.422 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any
   1.423 +files affected by the patch that it is popping.  Be sure to read the
   1.424 +documentation for a command's \option{-f} option before you use it!
   1.425 +
   1.426 +\subsection{Working on several patches at once}
   1.427 +
   1.428 +The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost}
   1.429 +applied patch.  This means that you can suspend work on one patch (by
   1.430 +refreshing it), pop or push to make a different patch the top, and
   1.431 +work on \emph{that} patch for a while.
   1.432 +
   1.433 +Here's an example that illustrates how you can use this ability.
   1.434 +Let's say you're developing a new feature as two patches.  The first
   1.435 +is a change to the core of your software, and the second---layered on
   1.436 +top of the first---changes the user interface to use the code you just
   1.437 +added to the core.  If you notice a bug in the core while you're
   1.438 +working on the UI patch, it's easy to fix the core.  Simply
   1.439 +\hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and
   1.440 +\hgxcmd{mq}{qpop} down to the core patch.  Fix the core bug,
   1.441 +\hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI
   1.442 +patch to continue where you left off.
   1.443 +
   1.444 +\section{More about patches}
   1.445 +\label{sec:mq:adv-patch}
   1.446 +
   1.447 +MQ uses the GNU \command{patch} command to apply patches, so it's
   1.448 +helpful to know a few more detailed aspects of how \command{patch}
   1.449 +works, and about patches themselves.
   1.450 +
   1.451 +\subsection{The strip count}
   1.452 +
   1.453 +If you look at the file headers in a patch, you will notice that the
   1.454 +pathnames usually have an extra component on the front that isn't
   1.455 +present in the actual path name.  This is a holdover from the way that
   1.456 +people used to generate patches (people still do this, but it's
   1.457 +somewhat rare with modern revision control tools).  
   1.458 +
   1.459 +Alice would unpack a tarball, edit her files, then decide that she
   1.460 +wanted to create a patch.  So she'd rename her working directory,
   1.461 +unpack the tarball again (hence the need for the rename), and use the
   1.462 +\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to
   1.463 +recursively generate a patch between the unmodified directory and the
   1.464 +modified one.  The result would be that the name of the unmodified
   1.465 +directory would be at the front of the left-hand path in every file
   1.466 +header, and the name of the modified directory would be at the front
   1.467 +of the right-hand path.
   1.468 +
   1.469 +Since someone receiving a patch from the Alices of the net would be
   1.470 +unlikely to have unmodified and modified directories with exactly the
   1.471 +same names, the \command{patch} command has a \cmdopt{patch}{-p}
   1.472 +option that indicates the number of leading path name components to
   1.473 +strip when trying to apply a patch.  This number is called the
   1.474 +\emph{strip count}.
   1.475 +
   1.476 +An option of ``\texttt{-p1}'' means ``use a strip count of one''.  If
   1.477 +\command{patch} sees a file name \filename{foo/bar/baz} in a file
   1.478 +header, it will strip \filename{foo} and try to patch a file named
   1.479 +\filename{bar/baz}.  (Strictly speaking, the strip count refers to the
   1.480 +number of \emph{path separators} (and the components that go with them
   1.481 +) to strip.  A strip count of one will turn \filename{foo/bar} into
   1.482 +\filename{bar}, but \filename{/foo/bar} (notice the extra leading
   1.483 +slash) into \filename{foo/bar}.)
   1.484 +
   1.485 +The ``standard'' strip count for patches is one; almost all patches
   1.486 +contain one leading path name component that needs to be stripped.
   1.487 +Mercurial's \hgcmd{diff} command generates path names in this form,
   1.488 +and the \hgcmd{import} command and MQ expect patches to have a strip
   1.489 +count of one.
   1.490 +
   1.491 +If you receive a patch from someone that you want to add to your patch
   1.492 +queue, and the patch needs a strip count other than one, you cannot
   1.493 +just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet
   1.494 +have a \texttt{-p} option (see~\bug{311}).  Your best bet is to
   1.495 +\hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}}
   1.496 +to apply their patch, followed by \hgcmd{addremove} to pick up any
   1.497 +files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}.
   1.498 +This complexity may become unnecessary; see~\bug{311} for details.
   1.499 +\subsection{Strategies for applying a patch}
   1.500 +
   1.501 +When \command{patch} applies a hunk, it tries a handful of
   1.502 +successively less accurate strategies to try to make the hunk apply.
   1.503 +This falling-back technique often makes it possible to take a patch
   1.504 +that was generated against an old version of a file, and apply it
   1.505 +against a newer version of that file.
   1.506 +
   1.507 +First, \command{patch} tries an exact match, where the line numbers,
   1.508 +the context, and the text to be modified must apply exactly.  If it
   1.509 +cannot make an exact match, it tries to find an exact match for the
   1.510 +context, without honouring the line numbering information.  If this
   1.511 +succeeds, it prints a line of output saying that the hunk was applied,
   1.512 +but at some \emph{offset} from the original line number.
   1.513 +
   1.514 +If a context-only match fails, \command{patch} removes the first and
   1.515 +last lines of the context, and tries a \emph{reduced} context-only
   1.516 +match.  If the hunk with reduced context succeeds, it prints a message
   1.517 +saying that it applied the hunk with a \emph{fuzz factor} (the number
   1.518 +after the fuzz factor indicates how many lines of context
   1.519 +\command{patch} had to trim before the patch applied).
   1.520 +
   1.521 +When neither of these techniques works, \command{patch} prints a
   1.522 +message saying that the hunk in question was rejected.  It saves
   1.523 +rejected hunks (also simply called ``rejects'') to a file with the
   1.524 +same name, and an added \sfilename{.rej} extension.  It also saves an
   1.525 +unmodified copy of the file with a \sfilename{.orig} extension; the
   1.526 +copy of the file without any extensions will contain any changes made
   1.527 +by hunks that \emph{did} apply cleanly.  If you have a patch that
   1.528 +modifies \filename{foo} with six hunks, and one of them fails to
   1.529 +apply, you will have: an unmodified \filename{foo.orig}, a
   1.530 +\filename{foo.rej} containing one hunk, and \filename{foo}, containing
   1.531 +the changes made by the five successful hunks.
   1.532 +
   1.533 +\subsection{Some quirks of patch representation}
   1.534 +
   1.535 +There are a few useful things to know about how \command{patch} works
   1.536 +with files.
   1.537 +\begin{itemize}
   1.538 +\item This should already be obvious, but \command{patch} cannot
   1.539 +  handle binary files.
   1.540 +\item Neither does it care about the executable bit; it creates new
   1.541 +  files as readable, but not executable.
   1.542 +\item \command{patch} treats the removal of a file as a diff between
   1.543 +  the file to be removed and the empty file.  So your idea of ``I
   1.544 +  deleted this file'' looks like ``every line of this file was
   1.545 +  deleted'' in a patch.
   1.546 +\item It treats the addition of a file as a diff between the empty
   1.547 +  file and the file to be added.  So in a patch, your idea of ``I
   1.548 +  added this file'' looks like ``every line of this file was added''.
   1.549 +\item It treats a renamed file as the removal of the old name, and the
   1.550 +  addition of the new name.  This means that renamed files have a big
   1.551 +  footprint in patches.  (Note also that Mercurial does not currently
   1.552 +  try to infer when files have been renamed or copied in a patch.)
   1.553 +\item \command{patch} cannot represent empty files, so you cannot use
   1.554 +  a patch to represent the notion ``I added this empty file to the
   1.555 +  tree''.
   1.556 +\end{itemize}
   1.557 +\subsection{Beware the fuzz}
   1.558 +
   1.559 +While applying a hunk at an offset, or with a fuzz factor, will often
   1.560 +be completely successful, these inexact techniques naturally leave
   1.561 +open the possibility of corrupting the patched file.  The most common
   1.562 +cases typically involve applying a patch twice, or at an incorrect
   1.563 +location in the file.  If \command{patch} or \hgxcmd{mq}{qpush} ever
   1.564 +mentions an offset or fuzz factor, you should make sure that the
   1.565 +modified files are correct afterwards.  
   1.566 +
   1.567 +It's often a good idea to refresh a patch that has applied with an
   1.568 +offset or fuzz factor; refreshing the patch generates new context
   1.569 +information that will make it apply cleanly.  I say ``often,'' not
   1.570 +``always,'' because sometimes refreshing a patch will make it fail to
   1.571 +apply against a different revision of the underlying files.  In some
   1.572 +cases, such as when you're maintaining a patch that must sit on top of
   1.573 +multiple versions of a source tree, it's acceptable to have a patch
   1.574 +apply with some fuzz, provided you've verified the results of the
   1.575 +patching process in such cases.
   1.576 +
   1.577 +\subsection{Handling rejection}
   1.578 +
   1.579 +If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
   1.580 +message and exit.  If it has left \sfilename{.rej} files behind, it is
   1.581 +usually best to fix up the rejected hunks before you push more patches
   1.582 +or do any further work.
   1.583 +
   1.584 +If your patch \emph{used to} apply cleanly, and no longer does because
   1.585 +you've changed the underlying code that your patches are based on,
   1.586 +Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.
   1.587 +
   1.588 +Unfortunately, there aren't any great techniques for dealing with
   1.589 +rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
   1.590 +file and edit the target file, applying the rejected hunks by hand.
   1.591 +
   1.592 +If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
   1.593 +wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
   1.594 +vigorous than \command{patch} in its attempts to make a patch apply.
   1.595 +
   1.596 +Another Linux kernel hacker, Chris Mason (the author of Mercurial
   1.597 +Queues), wrote a similar tool called
   1.598 +\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
   1.599 +automating the application of hunks rejected by \command{patch}.  The
   1.600 +\command{mpatch} command can help with four common reasons that a hunk
   1.601 +may be rejected:
   1.602 +
   1.603 +\begin{itemize}
   1.604 +\item The context in the middle of a hunk has changed.
   1.605 +\item A hunk is missing some context at the beginning or end.
   1.606 +\item A large hunk might apply better---either entirely or in
   1.607 +  part---if it was broken up into smaller hunks.
   1.608 +\item A hunk removes lines with slightly different content than those
   1.609 +  currently present in the file.
   1.610 +\end{itemize}
   1.611 +
   1.612 +If you use \command{wiggle} or \command{mpatch}, you should be doubly
   1.613 +careful to check your results when you're done.  In fact,
   1.614 +\command{mpatch} enforces this method of double-checking the tool's
   1.615 +output, by automatically dropping you into a merge program when it has
   1.616 +done its job, so that you can verify its work and finish off any
   1.617 +remaining merges.
   1.618 +
   1.619 +\section{Getting the best performance out of MQ}
   1.620 +\label{sec:mq:perf}
   1.621 +
   1.622 +MQ is very efficient at handling a large number of patches.  I ran
   1.623 +some performance experiments in mid-2006 for a talk that I gave at the
   1.624 +2006 EuroPython conference~\cite{web:europython}.  I used as my data
   1.625 +set the Linux 2.6.17-mm1 patch series, which consists of 1,738
   1.626 +patches.  I applied these on top of a Linux kernel repository
   1.627 +containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
   1.628 +2.6.17.
   1.629 +
   1.630 +On my old, slow laptop, I was able to
   1.631 +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
   1.632 +and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds.  (On a
   1.633 +newer laptop, the time to push all patches dropped to two minutes.)  I
   1.634 +could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
   1.635 +lines of changes to 287 files) in 6.6 seconds.
   1.636 +
   1.637 +Clearly, MQ is well suited to working in large trees, but there are a
   1.638 +few tricks you can use to get the best performance of it.
   1.639 +
   1.640 +First of all, try to ``batch'' operations together.  Every time you
   1.641 +run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
   1.642 +directory once to make sure you haven't made some changes and then
   1.643 +forgotten to run \hgxcmd{mq}{qrefresh}.  On a small tree, the time that
   1.644 +this scan takes is unnoticeable.  However, on a medium-sized tree
   1.645 +(containing tens of thousands of files), it can take a second or more.
   1.646 +
   1.647 +The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
   1.648 +multiple patches at a time.  You can identify the ``destination
   1.649 +patch'' that you want to end up at.  When you \hgxcmd{mq}{qpush} with a
   1.650 +destination specified, it will push patches until that patch is at the
   1.651 +top of the applied stack.  When you \hgxcmd{mq}{qpop} to a destination, MQ
   1.652 +will pop patches until the destination patch is at the top.
   1.653 +
   1.654 +You can identify a destination patch using either the name of the
   1.655 +patch, or by number.  If you use numeric addressing, patches are
   1.656 +counted from zero; this means that the first patch is zero, the second
   1.657 +is one, and so on.
   1.658 +
   1.659 +\section{Updating your patches when the underlying code changes}
   1.660 +\label{sec:mq:merge}
   1.661 +
   1.662 +It's common to have a stack of patches on top of an underlying
   1.663 +repository that you don't modify directly.  If you're working on
   1.664 +changes to third-party code, or on a feature that is taking longer to
   1.665 +develop than the rate of change of the code beneath, you will often
   1.666 +need to sync up with the underlying code, and fix up any hunks in your
   1.667 +patches that no longer apply.  This is called \emph{rebasing} your
   1.668 +patch series.
   1.669 +
   1.670 +The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}
   1.671 +your patches, then \hgcmd{pull} changes into the underlying
   1.672 +repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your
   1.673 +patches again.  MQ will stop pushing any time it runs across a patch
   1.674 +that fails to apply during conflicts, allowing you to fix your
   1.675 +conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing
   1.676 +until you have fixed your entire stack.
   1.677 +
   1.678 +This approach is easy to use and works well if you don't expect
   1.679 +changes to the underlying code to affect how well your patches apply.
   1.680 +If your patch stack touches code that is modified frequently or
   1.681 +invasively in the underlying repository, however, fixing up rejected
   1.682 +hunks by hand quickly becomes tiresome.
   1.683 +
   1.684 +It's possible to partially automate the rebasing process.  If your
   1.685 +patches apply cleanly against some revision of the underlying repo, MQ
   1.686 +can use this information to help you to resolve conflicts between your
   1.687 +patches and a different revision.
   1.688 +
   1.689 +The process is a little involved.
   1.690 +\begin{enumerate}
   1.691 +\item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of
   1.692 +  the revision where you know that they apply cleanly.
   1.693 +\item Save a backup copy of your patch directory using
   1.694 +  \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}.  This prints
   1.695 +  the name of the directory that it has saved the patches in.  It will
   1.696 +  save the patches to a directory called
   1.697 +  \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small
   1.698 +  integer.  It also commits a ``save changeset'' on top of your
   1.699 +  applied patches; this is for internal book-keeping, and records the
   1.700 +  states of the \sfilename{series} and \sfilename{status} files.
   1.701 +\item Use \hgcmd{pull} to bring new changes into the underlying
   1.702 +  repository.  (Don't run \hgcmdargs{pull}{-u}; see below for why.)
   1.703 +\item Update to the new tip revision, using
   1.704 +  \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
   1.705 +  have pushed.
   1.706 +\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}
   1.707 +    \hgxopt{mq}{qpush}{-a}}.  The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush}
   1.708 +  tells MQ to perform a three-way merge if the patch fails to apply.
   1.709 +\end{enumerate}
   1.710 +
   1.711 +During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the
   1.712 +\sfilename{series} file is applied normally.  If a patch applies with
   1.713 +fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and
   1.714 +performs a three-way merge with the corresponding changeset.  This
   1.715 +merge uses Mercurial's normal merge machinery, so it may pop up a GUI
   1.716 +merge tool to help you to resolve problems.
   1.717 +
   1.718 +When you finish resolving the effects of a patch, MQ refreshes your
   1.719 +patch based on the result of the merge.
   1.720 +
   1.721 +At the end of this process, your repository will have one extra head
   1.722 +from the old patch queue, and a copy of the old patch queue will be in
   1.723 +\sdirname{.hg/patches.\emph{N}}. You can remove the extra head using
   1.724 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}
   1.725 +or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
   1.726 +you are sure that you no longer need it as a backup.
   1.727 +
   1.728 +\section{Identifying patches}
   1.729 +
   1.730 +MQ commands that work with patches let you refer to a patch either by
   1.731 +using its name or by a number.  By name is obvious enough; pass the
   1.732 +name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will
   1.733 +push patches until \filename{foo.patch} is applied.  
   1.734 +
   1.735 +As a shortcut, you can refer to a patch using both a name and a
   1.736 +numeric offset; \texttt{foo.patch-2} means ``two patches before
   1.737 +\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
   1.738 +after \texttt{bar.patch}''.
   1.739 +
   1.740 +Referring to a patch by index isn't much different.  The first patch
   1.741 +printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one
   1.742 +of those start-at-zero counting systems); the second is patch one; and
   1.743 +so on.
   1.744 +
   1.745 +MQ also makes it easy to work with patches when you are using normal
   1.746 +Mercurial commands.  Every command that accepts a changeset ID will
   1.747 +also accept the name of an applied patch.  MQ augments the tags
   1.748 +normally in the repository with an eponymous one for each applied
   1.749 +patch.  In addition, the special tags \index{tags!special tag
   1.750 +  names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
   1.751 +  names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
   1.752 +topmost applied patches, respectively.
   1.753 +
   1.754 +These additions to Mercurial's normal tagging capabilities make
   1.755 +dealing with patches even more of a breeze.
   1.756 +\begin{itemize}
   1.757 +\item Want to patchbomb a mailing list with your latest series of
   1.758 +  changes?
   1.759 +  \begin{codesample4}
   1.760 +    hg email qbase:qtip
   1.761 +  \end{codesample4}
   1.762 +  (Don't know what ``patchbombing'' is?  See
   1.763 +  section~\ref{sec:hgext:patchbomb}.)
   1.764 +\item Need to see all of the patches since \texttt{foo.patch} that
   1.765 +  have touched files in a subdirectory of your tree?
   1.766 +  \begin{codesample4}
   1.767 +    hg log -r foo.patch:qtip \emph{subdir}
   1.768 +  \end{codesample4}
   1.769 +\end{itemize}
   1.770 +
   1.771 +Because MQ makes the names of patches available to the rest of
   1.772 +Mercurial through its normal internal tag machinery, you don't need to
   1.773 +type in the entire name of a patch when you want to identify it by
   1.774 +name.
   1.775 +
   1.776 +\begin{figure}[ht]
   1.777 +  \interaction{mq.id.output}
   1.778 +  \caption{Using MQ's tag features to work with patches}
   1.779 +  \label{ex:mq:id}
   1.780 +\end{figure}
   1.781 +
   1.782 +Another nice consequence of representing patch names as tags is that
   1.783 +when you run the \hgcmd{log} command, it will display a patch's name
   1.784 +as a tag, simply as part of its normal output.  This makes it easy to
   1.785 +visually distinguish applied patches from underlying ``normal''
   1.786 +revisions.  Figure~\ref{ex:mq:id} shows a few normal Mercurial
   1.787 +commands in use with applied patches.
   1.788 +
   1.789 +\section{Useful things to know about}
   1.790 +
   1.791 +There are a number of aspects of MQ usage that don't fit tidily into
   1.792 +sections of their own, but that are good to know.  Here they are, in
   1.793 +one place.
   1.794 +
   1.795 +\begin{itemize}
   1.796 +\item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it
   1.797 +  again, the changeset that represents the patch after the pop/push
   1.798 +  will have a \emph{different identity} than the changeset that
   1.799 +  represented the hash beforehand.  See
   1.800 +  section~\ref{sec:mqref:cmd:qpush} for information as to why this is.
   1.801 +\item It's not a good idea to \hgcmd{merge} changes from another
   1.802 +  branch with a patch changeset, at least if you want to maintain the
   1.803 +  ``patchiness'' of that changeset and changesets below it on the
   1.804 +  patch stack.  If you try to do this, it will appear to succeed, but
   1.805 +  MQ will become confused.
   1.806 +\end{itemize}
   1.807 +
   1.808 +\section{Managing patches in a repository}
   1.809 +\label{sec:mq:repo}
   1.810 +
   1.811 +Because MQ's \sdirname{.hg/patches} directory resides outside a
   1.812 +Mercurial repository's working directory, the ``underlying'' Mercurial
   1.813 +repository knows nothing about the management or presence of patches.
   1.814 +
   1.815 +This presents the interesting possibility of managing the contents of
   1.816 +the patch directory as a Mercurial repository in its own right.  This
   1.817 +can be a useful way to work.  For example, you can work on a patch for
   1.818 +a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of
   1.819 +the patch.  This lets you ``roll back'' to that version of the patch
   1.820 +later on.
   1.821 +
   1.822 +You can then share different versions of the same patch stack among
   1.823 +multiple underlying repositories.  I use this when I am developing a
   1.824 +Linux kernel feature.  I have a pristine copy of my kernel sources for
   1.825 +each of several CPU architectures, and a cloned repository under each
   1.826 +that contains the patches I am working on.  When I want to test a
   1.827 +change on a different architecture, I push my current patches to the
   1.828 +patch repository associated with that kernel tree, pop and push all of
   1.829 +my patches, and build and test that kernel.
   1.830 +
   1.831 +Managing patches in a repository makes it possible for multiple
   1.832 +developers to work on the same patch series without colliding with
   1.833 +each other, all on top of an underlying source base that they may or
   1.834 +may not control.
   1.835 +
   1.836 +\subsection{MQ support for patch repositories}
   1.837 +
   1.838 +MQ helps you to work with the \sdirname{.hg/patches} directory as a
   1.839 +repository; when you prepare a repository for working with patches
   1.840 +using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to
   1.841 +create the \sdirname{.hg/patches} directory as a Mercurial repository.
   1.842 +
   1.843 +\begin{note}
   1.844 +  If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go
   1.845 +  into the \sdirname{.hg/patches} directory at any time and run
   1.846 +  \hgcmd{init}.  Don't forget to add an entry for the
   1.847 +  \sfilename{status} file to the \sfilename{.hgignore} file, though
   1.848 +
   1.849 +  (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you
   1.850 +  automatically); you \emph{really} don't want to manage the
   1.851 +  \sfilename{status} file.
   1.852 +\end{note}
   1.853 +
   1.854 +As a convenience, if MQ notices that the \dirname{.hg/patches}
   1.855 +directory is a repository, it will automatically \hgcmd{add} every
   1.856 +patch that you create and import.
   1.857 +
   1.858 +MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs
   1.859 +\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
   1.860 +some bothersome typing.
   1.861 +
   1.862 +Finally, as a convenience to manage the patch directory, you can
   1.863 +define the alias \command{mq} on Unix systems. For example, on Linux
   1.864 +systems using the \command{bash} shell, you can include the following
   1.865 +snippet in your \tildefile{.bashrc}.
   1.866 +
   1.867 +\begin{codesample2}
   1.868 +  alias mq=`hg -R \$(hg root)/.hg/patches'
   1.869 +\end{codesample2}
   1.870 +
   1.871 +You can then issue commands of the form \cmdargs{mq}{pull} from
   1.872 +the main repository.
   1.873 +
   1.874 +\subsection{A few things to watch out for}
   1.875 +
   1.876 +MQ's support for working with a repository full of patches is limited
   1.877 +in a few small respects.
   1.878 +
   1.879 +MQ cannot automatically detect changes that you make to the patch
   1.880 +directory.  If you \hgcmd{pull}, manually edit, or \hgcmd{update}
   1.881 +changes to patches or the \sfilename{series} file, you will have to
   1.882 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then
   1.883 +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to
   1.884 +see those changes show up there.  If you forget to do this, you can
   1.885 +confuse MQ's idea of which patches are applied.
   1.886 +
   1.887 +\section{Third party tools for working with patches}
   1.888 +\label{sec:mq:tools}
   1.889 +
   1.890 +Once you've been working with patches for a while, you'll find
   1.891 +yourself hungry for tools that will help you to understand and
   1.892 +manipulate the patches you're dealing with.
   1.893 +
   1.894 +The \command{diffstat} command~\cite{web:diffstat} generates a
   1.895 +histogram of the modifications made to each file in a patch.  It
   1.896 +provides a good way to ``get a sense of'' a patch---which files it
   1.897 +affects, and how much change it introduces to each file and as a
   1.898 +whole.  (I find that it's a good idea to use \command{diffstat}'s
   1.899 +\cmdopt{diffstat}{-p} option as a matter of course, as otherwise it
   1.900 +will try to do clever things with prefixes of file names that
   1.901 +inevitably confuse at least me.)
   1.902 +
   1.903 +\begin{figure}[ht]
   1.904 +  \interaction{mq.tools.tools}
   1.905 +  \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
   1.906 +  \label{ex:mq:tools}
   1.907 +\end{figure}
   1.908 +
   1.909 +The \package{patchutils} package~\cite{web:patchutils} is invaluable.
   1.910 +It provides a set of small utilities that follow the ``Unix
   1.911 +philosophy;'' each does one useful thing with a patch.  The
   1.912 +\package{patchutils} command I use most is \command{filterdiff}, which
   1.913 +extracts subsets from a patch file.  For example, given a patch that
   1.914 +modifies hundreds of files across dozens of directories, a single
   1.915 +invocation of \command{filterdiff} can generate a smaller patch that
   1.916 +only touches files whose names match a particular glob pattern.  See
   1.917 +section~\ref{mq-collab:tips:interdiff} for another example.
   1.918 +
   1.919 +\section{Good ways to work with patches}
   1.920 +
   1.921 +Whether you are working on a patch series to submit to a free software
   1.922 +or open source project, or a series that you intend to treat as a
   1.923 +sequence of regular changesets when you're done, you can use some
   1.924 +simple techniques to keep your work well organised.
   1.925 +
   1.926 +Give your patches descriptive names.  A good name for a patch might be
   1.927 +\filename{rework-device-alloc.patch}, because it will immediately give
   1.928 +you a hint what the purpose of the patch is.  Long names shouldn't be
   1.929 +a problem; you won't be typing the names often, but you \emph{will} be
   1.930 +running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over.
   1.931 +Good naming becomes especially important when you have a number of
   1.932 +patches to work with, or if you are juggling a number of different
   1.933 +tasks and your patches only get a fraction of your attention.
   1.934 +
   1.935 +Be aware of what patch you're working on.  Use the \hgxcmd{mq}{qtop}
   1.936 +command and skim over the text of your patches frequently---for
   1.937 +example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where
   1.938 +you stand.  I have several times worked on and \hgxcmd{mq}{qrefresh}ed a
   1.939 +patch other than the one I intended, and it's often tricky to migrate
   1.940 +changes into the right patch after making them in the wrong one.
   1.941 +
   1.942 +For this reason, it is very much worth investing a little time to
   1.943 +learn how to use some of the third-party tools I described in
   1.944 +section~\ref{sec:mq:tools}, particularly \command{diffstat} and
   1.945 +\command{filterdiff}.  The former will give you a quick idea of what
   1.946 +changes your patch is making, while the latter makes it easy to splice
   1.947 +hunks selectively out of one patch and into another.
   1.948 +
   1.949 +\section{MQ cookbook}
   1.950 +
   1.951 +\subsection{Manage ``trivial'' patches}
   1.952 +
   1.953 +Because the overhead of dropping files into a new Mercurial repository
   1.954 +is so low, it makes a lot of sense to manage patches this way even if
   1.955 +you simply want to make a few changes to a source tarball that you
   1.956 +downloaded.
   1.957 +
   1.958 +Begin by downloading and unpacking the source tarball,
   1.959 +and turning it into a Mercurial repository.
   1.960 +\interaction{mq.tarball.download}
   1.961 +
   1.962 +Continue by creating a patch stack and making your changes.
   1.963 +\interaction{mq.tarball.qinit}
   1.964 +
   1.965 +Let's say a few weeks or months pass, and your package author releases
   1.966 +a new version.  First, bring their changes into the repository.
   1.967 +\interaction{mq.tarball.newsource}
   1.968 +The pipeline starting with \hgcmd{locate} above deletes all files in
   1.969 +the working directory, so that \hgcmd{commit}'s
   1.970 +\hgopt{commit}{--addremove} option can actually tell which files have
   1.971 +really been removed in the newer version of the source.
   1.972 +
   1.973 +Finally, you can apply your patches on top of the new tree.
   1.974 +\interaction{mq.tarball.repush}
   1.975 +
   1.976 +\subsection{Combining entire patches}
   1.977 +\label{sec:mq:combine}
   1.978 +
   1.979 +MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire
   1.980 +patches.  This ``folds'' the patches you name, in the order you name
   1.981 +them, into the topmost applied patch, and concatenates their
   1.982 +descriptions onto the end of its description.  The patches that you
   1.983 +fold must be unapplied before you fold them.
   1.984 +
   1.985 +The order in which you fold patches matters.  If your topmost applied
   1.986 +patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and
   1.987 +\texttt{quux} into it, you will end up with a patch that has the same
   1.988 +effect as if you applied first \texttt{foo}, then \texttt{bar},
   1.989 +followed by \texttt{quux}.
   1.990 +
   1.991 +\subsection{Merging part of one patch into another}
   1.992 +
   1.993 +Merging \emph{part} of one patch into another is more difficult than
   1.994 +combining entire patches.
   1.995 +
   1.996 +If you want to move changes to entire files, you can use
   1.997 +\command{filterdiff}'s \cmdopt{filterdiff}{-i} and
   1.998 +\cmdopt{filterdiff}{-x} options to choose the modifications to snip
   1.999 +out of one patch, concatenating its output onto the end of the patch
  1.1000 +you want to merge into.  You usually won't need to modify the patch
  1.1001 +you've merged the changes from.  Instead, MQ will report some rejected
  1.1002 +hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the
  1.1003 +other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop
  1.1004 +the duplicate hunks.
  1.1005 +
  1.1006 +If you have a patch that has multiple hunks modifying a file, and you
  1.1007 +only want to move a few of those hunks, the job becomes more messy,
  1.1008 +but you can still partly automate it.  Use \cmdargs{lsdiff}{-nvv} to
  1.1009 +print some metadata about the patch.
  1.1010 +\interaction{mq.tools.lsdiff}
  1.1011 +
  1.1012 +This command prints three different kinds of number:
  1.1013 +\begin{itemize}
  1.1014 +\item (in the first column) a \emph{file number} to identify each file
  1.1015 +  modified in the patch;
  1.1016 +\item (on the next line, indented) the line number within a modified
  1.1017 +  file where a hunk starts; and
  1.1018 +\item (on the same line) a \emph{hunk number} to identify that hunk.
  1.1019 +\end{itemize}
  1.1020 +
  1.1021 +You'll have to use some visual inspection, and reading of the patch,
  1.1022 +to identify the file and hunk numbers you'll want, but you can then
  1.1023 +pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files}
  1.1024 +and \cmdopt{filterdiff}{--hunks} options, to select exactly the file
  1.1025 +and hunk you want to extract.
  1.1026 +
  1.1027 +Once you have this hunk, you can concatenate it onto the end of your
  1.1028 +destination patch and continue with the remainder of
  1.1029 +section~\ref{sec:mq:combine}.
  1.1030 +
  1.1031 +\section{Differences between quilt and MQ}
  1.1032 +
  1.1033 +If you are already familiar with quilt, MQ provides a similar command
  1.1034 +set.  There are a few differences in the way that it works.
  1.1035 +
  1.1036 +You will already have noticed that most quilt commands have MQ
  1.1037 +counterparts that simply begin with a ``\texttt{q}''.  The exceptions
  1.1038 +are quilt's \texttt{add} and \texttt{remove} commands, the
  1.1039 +counterparts for which are the normal Mercurial \hgcmd{add} and
  1.1040 +\hgcmd{remove} commands.  There is no MQ equivalent of the quilt
  1.1041 +\texttt{edit} command.
  1.1042 +
  1.1043 +%%% Local Variables: 
  1.1044 +%%% mode: latex
  1.1045 +%%% TeX-master: "00book"
  1.1046 +%%% End: