hgbook

annotate es/mq.tex @ 343:2fb78d342e07

find changesets by author, revision, files, or words in the commit message
changed es/Leame.1st
upgraded the list of files on translation and revision.

added a term (builtin) to the glossary

changed es/concepts.tex
file added to define labels needed by other tex files

changed es/preface.tex
killed a TODO

changed es/tour-basic.tex
I have began the translation of this file. 34% completed, according to vim

changed es/undo.tex
file added to define labels needed by other tex files
author jerojasro@localhost
date Sun Oct 19 19:56:21 2008 -0500 (2008-10-19)
parents 04c08ad7e92e
children aeda195f54a6
rev   line source
jerojasro@336 1 \chapter{Managing change with Mercurial Queues}
jerojasro@336 2 \label{chap:mq}
jerojasro@336 3
jerojasro@336 4 \section{The patch management problem}
jerojasro@336 5 \label{sec:mq:patch-mgmt}
jerojasro@336 6
jerojasro@336 7 Here is a common scenario: you need to install a software package from
jerojasro@336 8 source, but you find a bug that you must fix in the source before you
jerojasro@336 9 can start using the package. You make your changes, forget about the
jerojasro@336 10 package for a while, and a few months later you need to upgrade to a
jerojasro@336 11 newer version of the package. If the newer version of the package
jerojasro@336 12 still has the bug, you must extract your fix from the older source
jerojasro@336 13 tree and apply it against the newer version. This is a tedious task,
jerojasro@336 14 and it's easy to make mistakes.
jerojasro@336 15
jerojasro@336 16 This is a simple case of the ``patch management'' problem. You have
jerojasro@336 17 an ``upstream'' source tree that you can't change; you need to make
jerojasro@336 18 some local changes on top of the upstream tree; and you'd like to be
jerojasro@336 19 able to keep those changes separate, so that you can apply them to
jerojasro@336 20 newer versions of the upstream source.
jerojasro@336 21
jerojasro@336 22 The patch management problem arises in many situations. Probably the
jerojasro@336 23 most visible is that a user of an open source software project will
jerojasro@336 24 contribute a bug fix or new feature to the project's maintainers in the
jerojasro@336 25 form of a patch.
jerojasro@336 26
jerojasro@336 27 Distributors of operating systems that include open source software
jerojasro@336 28 often need to make changes to the packages they distribute so that
jerojasro@336 29 they will build properly in their environments.
jerojasro@336 30
jerojasro@336 31 When you have few changes to maintain, it is easy to manage a single
jerojasro@336 32 patch using the standard \command{diff} and \command{patch} programs
jerojasro@336 33 (see section~\ref{sec:mq:patch} for a discussion of these tools).
jerojasro@336 34 Once the number of changes grows, it starts to make sense to maintain
jerojasro@336 35 patches as discrete ``chunks of work,'' so that for example a single
jerojasro@336 36 patch will contain only one bug fix (the patch might modify several
jerojasro@336 37 files, but it's doing ``only one thing''), and you may have a number
jerojasro@336 38 of such patches for different bugs you need fixed and local changes
jerojasro@336 39 you require. In this situation, if you submit a bug fix patch to the
jerojasro@336 40 upstream maintainers of a package and they include your fix in a
jerojasro@336 41 subsequent release, you can simply drop that single patch when you're
jerojasro@336 42 updating to the newer release.
jerojasro@336 43
jerojasro@336 44 Maintaining a single patch against an upstream tree is a little
jerojasro@336 45 tedious and error-prone, but not difficult. However, the complexity
jerojasro@336 46 of the problem grows rapidly as the number of patches you have to
jerojasro@336 47 maintain increases. With more than a tiny number of patches in hand,
jerojasro@336 48 understanding which ones you have applied and maintaining them moves
jerojasro@336 49 from messy to overwhelming.
jerojasro@336 50
jerojasro@336 51 Fortunately, Mercurial includes a powerful extension, Mercurial Queues
jerojasro@336 52 (or simply ``MQ''), that massively simplifies the patch management
jerojasro@336 53 problem.
jerojasro@336 54
jerojasro@336 55 \section{The prehistory of Mercurial Queues}
jerojasro@336 56 \label{sec:mq:history}
jerojasro@336 57
jerojasro@336 58 During the late 1990s, several Linux kernel developers started to
jerojasro@336 59 maintain ``patch series'' that modified the behaviour of the Linux
jerojasro@336 60 kernel. Some of these series were focused on stability, some on
jerojasro@336 61 feature coverage, and others were more speculative.
jerojasro@336 62
jerojasro@336 63 The sizes of these patch series grew rapidly. In 2002, Andrew Morton
jerojasro@336 64 published some shell scripts he had been using to automate the task of
jerojasro@336 65 managing his patch queues. Andrew was successfully using these
jerojasro@336 66 scripts to manage hundreds (sometimes thousands) of patches on top of
jerojasro@336 67 the Linux kernel.
jerojasro@336 68
jerojasro@336 69 \subsection{A patchwork quilt}
jerojasro@336 70 \label{sec:mq:quilt}
jerojasro@336 71
jerojasro@336 72 In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
jerojasro@336 73 approach of Andrew's scripts and published a tool called ``patchwork
jerojasro@336 74 quilt''~\cite{web:quilt}, or simply ``quilt''
jerojasro@336 75 (see~\cite{gruenbacher:2005} for a paper describing it). Because
jerojasro@336 76 quilt substantially automated patch management, it rapidly gained a
jerojasro@336 77 large following among open source software developers.
jerojasro@336 78
jerojasro@336 79 Quilt manages a \emph{stack of patches} on top of a directory tree.
jerojasro@336 80 To begin, you tell quilt to manage a directory tree, and tell it which
jerojasro@336 81 files you want to manage; it stores away the names and contents of
jerojasro@336 82 those files. To fix a bug, you create a new patch (using a single
jerojasro@336 83 command), edit the files you need to fix, then ``refresh'' the patch.
jerojasro@336 84
jerojasro@336 85 The refresh step causes quilt to scan the directory tree; it updates
jerojasro@336 86 the patch with all of the changes you have made. You can create
jerojasro@336 87 another patch on top of the first, which will track the changes
jerojasro@336 88 required to modify the tree from ``tree with one patch applied'' to
jerojasro@336 89 ``tree with two patches applied''.
jerojasro@336 90
jerojasro@336 91 You can \emph{change} which patches are applied to the tree. If you
jerojasro@336 92 ``pop'' a patch, the changes made by that patch will vanish from the
jerojasro@336 93 directory tree. Quilt remembers which patches you have popped,
jerojasro@336 94 though, so you can ``push'' a popped patch again, and the directory
jerojasro@336 95 tree will be restored to contain the modifications in the patch. Most
jerojasro@336 96 importantly, you can run the ``refresh'' command at any time, and the
jerojasro@336 97 topmost applied patch will be updated. This means that you can, at
jerojasro@336 98 any time, change both which patches are applied and what
jerojasro@336 99 modifications those patches make.
jerojasro@336 100
jerojasro@336 101 Quilt knows nothing about revision control tools, so it works equally
jerojasro@336 102 well on top of an unpacked tarball or a Subversion working copy.
jerojasro@336 103
jerojasro@336 104 \subsection{From patchwork quilt to Mercurial Queues}
jerojasro@336 105 \label{sec:mq:quilt-mq}
jerojasro@336 106
jerojasro@336 107 In mid-2005, Chris Mason took the features of quilt and wrote an
jerojasro@336 108 extension that he called Mercurial Queues, which added quilt-like
jerojasro@336 109 behaviour to Mercurial.
jerojasro@336 110
jerojasro@336 111 The key difference between quilt and MQ is that quilt knows nothing
jerojasro@336 112 about revision control systems, while MQ is \emph{integrated} into
jerojasro@336 113 Mercurial. Each patch that you push is represented as a Mercurial
jerojasro@336 114 changeset. Pop a patch, and the changeset goes away.
jerojasro@336 115
jerojasro@336 116 Because quilt does not care about revision control tools, it is still
jerojasro@336 117 a tremendously useful piece of software to know about for situations
jerojasro@336 118 where you cannot use Mercurial and MQ.
jerojasro@336 119
jerojasro@336 120 \section{The huge advantage of MQ}
jerojasro@336 121
jerojasro@336 122 I cannot overstate the value that MQ offers through the unification of
jerojasro@336 123 patches and revision control.
jerojasro@336 124
jerojasro@336 125 A major reason that patches have persisted in the free software and
jerojasro@336 126 open source world---in spite of the availability of increasingly
jerojasro@336 127 capable revision control tools over the years---is the \emph{agility}
jerojasro@336 128 they offer.
jerojasro@336 129
jerojasro@336 130 Traditional revision control tools make a permanent, irreversible
jerojasro@336 131 record of everything that you do. While this has great value, it's
jerojasro@336 132 also somewhat stifling. If you want to perform a wild-eyed
jerojasro@336 133 experiment, you have to be careful in how you go about it, or you risk
jerojasro@336 134 leaving unneeded---or worse, misleading or destabilising---traces of
jerojasro@336 135 your missteps and errors in the permanent revision record.
jerojasro@336 136
jerojasro@336 137 By contrast, MQ's marriage of distributed revision control with
jerojasro@336 138 patches makes it much easier to isolate your work. Your patches live
jerojasro@336 139 on top of normal revision history, and you can make them disappear or
jerojasro@336 140 reappear at will. If you don't like a patch, you can drop it. If a
jerojasro@336 141 patch isn't quite as you want it to be, simply fix it---as many times
jerojasro@336 142 as you need to, until you have refined it into the form you desire.
jerojasro@336 143
jerojasro@336 144 As an example, the integration of patches with revision control makes
jerojasro@336 145 understanding patches and debugging their effects---and their
jerojasro@336 146 interplay with the code they're based on---\emph{enormously} easier.
jerojasro@336 147 Since every applied patch has an associated changeset, you can use
jerojasro@336 148 \hgcmdargs{log}{\emph{filename}} to see which changesets and patches
jerojasro@336 149 affected a file. You can use the \hgext{bisect} command to
jerojasro@336 150 binary-search through all changesets and applied patches to see where
jerojasro@336 151 a bug got introduced or fixed. You can use the \hgcmd{annotate}
jerojasro@336 152 command to see which changeset or patch modified a particular line of
jerojasro@336 153 a source file. And so on.
jerojasro@336 154
jerojasro@336 155 \section{Understanding patches}
jerojasro@336 156 \label{sec:mq:patch}
jerojasro@336 157
jerojasro@336 158 Because MQ doesn't hide its patch-oriented nature, it is helpful to
jerojasro@336 159 understand what patches are, and a little about the tools that work
jerojasro@336 160 with them.
jerojasro@336 161
jerojasro@336 162 The traditional Unix \command{diff} command compares two files, and
jerojasro@336 163 prints a list of differences between them. The \command{patch} command
jerojasro@336 164 understands these differences as \emph{modifications} to make to a
jerojasro@336 165 file. Take a look at figure~\ref{ex:mq:diff} for a simple example of
jerojasro@336 166 these commands in action.
jerojasro@336 167
jerojasro@336 168 \begin{figure}[ht]
jerojasro@336 169 \interaction{mq.dodiff.diff}
jerojasro@336 170 \caption{Simple uses of the \command{diff} and \command{patch} commands}
jerojasro@336 171 \label{ex:mq:diff}
jerojasro@336 172 \end{figure}
jerojasro@336 173
jerojasro@336 174 The type of file that \command{diff} generates (and \command{patch}
jerojasro@336 175 takes as input) is called a ``patch'' or a ``diff''; there is no
jerojasro@336 176 difference between a patch and a diff. (We'll use the term ``patch'',
jerojasro@336 177 since it's more commonly used.)
jerojasro@336 178
jerojasro@336 179 A patch file can start with arbitrary text; the \command{patch}
jerojasro@336 180 command ignores this text, but MQ uses it as the commit message when
jerojasro@336 181 creating changesets. To find the beginning of the patch content,
jerojasro@336 182 \command{patch} searches for the first line that starts with the
jerojasro@336 183 string ``\texttt{diff~-}''.
jerojasro@336 184
jerojasro@336 185 MQ works with \emph{unified} diffs (\command{patch} can accept several
jerojasro@336 186 other diff formats, but MQ doesn't). A unified diff contains two
jerojasro@336 187 kinds of header. The \emph{file header} describes the file being
jerojasro@336 188 modified; it contains the name of the file to modify. When
jerojasro@336 189 \command{patch} sees a new file header, it looks for a file with that
jerojasro@336 190 name to start modifying.
jerojasro@336 191
jerojasro@336 192 After the file header comes a series of \emph{hunks}. Each hunk
jerojasro@336 193 starts with a header; this identifies the range of line numbers within
jerojasro@336 194 the file that the hunk should modify. Following the header, a hunk
jerojasro@336 195 starts and ends with a few (usually three) lines of text from the
jerojasro@336 196 unmodified file; these are called the \emph{context} for the hunk. If
jerojasro@336 197 there's only a small amount of context between successive hunks,
jerojasro@336 198 \command{diff} doesn't print a new hunk header; it just runs the hunks
jerojasro@336 199 together, with a few lines of context between modifications.
jerojasro@336 200
jerojasro@336 201 Each line of context begins with a space character. Within the hunk,
jerojasro@336 202 a line that begins with ``\texttt{-}'' means ``remove this line,''
jerojasro@336 203 while a line that begins with ``\texttt{+}'' means ``insert this
jerojasro@336 204 line.'' For example, a line that is modified is represented by one
jerojasro@336 205 deletion and one insertion.
jerojasro@336 206
jerojasro@336 207 We will return to some of the more subtle aspects of patches later (in
jerojasro@336 208 section~\ref{sec:mq:adv-patch}), but you should have enough information
jerojasro@336 209 now to use MQ.
jerojasro@336 210
jerojasro@336 211 \section{Getting started with Mercurial Queues}
jerojasro@336 212 \label{sec:mq:start}
jerojasro@336 213
jerojasro@336 214 Because MQ is implemented as an extension, you must explicitly enable
jerojasro@336 215 before you can use it. (You don't need to download anything; MQ ships
jerojasro@336 216 with the standard Mercurial distribution.) To enable MQ, edit your
jerojasro@336 217 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.
jerojasro@336 218
jerojasro@336 219 \begin{figure}[ht]
jerojasro@336 220 \begin{codesample4}
jerojasro@336 221 [extensions]
jerojasro@336 222 hgext.mq =
jerojasro@336 223 \end{codesample4}
jerojasro@336 224 \label{ex:mq:config}
jerojasro@336 225 \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
jerojasro@336 226 \end{figure}
jerojasro@336 227
jerojasro@336 228 Once the extension is enabled, it will make a number of new commands
jerojasro@336 229 available. To verify that the extension is working, you can use
jerojasro@336 230 \hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see
jerojasro@336 231 the example in figure~\ref{ex:mq:enabled}.
jerojasro@336 232
jerojasro@336 233 \begin{figure}[ht]
jerojasro@336 234 \interaction{mq.qinit-help.help}
jerojasro@336 235 \caption{How to verify that MQ is enabled}
jerojasro@336 236 \label{ex:mq:enabled}
jerojasro@336 237 \end{figure}
jerojasro@336 238
jerojasro@336 239 You can use MQ with \emph{any} Mercurial repository, and its commands
jerojasro@336 240 only operate within that repository. To get started, simply prepare
jerojasro@336 241 the repository using the \hgxcmd{mq}{qinit} command (see
jerojasro@336 242 figure~\ref{ex:mq:qinit}). This command creates an empty directory
jerojasro@336 243 called \sdirname{.hg/patches}, where MQ will keep its metadata. As
jerojasro@336 244 with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing
jerojasro@336 245 if it succeeds.
jerojasro@336 246
jerojasro@336 247 \begin{figure}[ht]
jerojasro@336 248 \interaction{mq.tutorial.qinit}
jerojasro@336 249 \caption{Preparing a repository for use with MQ}
jerojasro@336 250 \label{ex:mq:qinit}
jerojasro@336 251 \end{figure}
jerojasro@336 252
jerojasro@336 253 \begin{figure}[ht]
jerojasro@336 254 \interaction{mq.tutorial.qnew}
jerojasro@336 255 \caption{Creating a new patch}
jerojasro@336 256 \label{ex:mq:qnew}
jerojasro@336 257 \end{figure}
jerojasro@336 258
jerojasro@336 259 \subsection{Creating a new patch}
jerojasro@336 260
jerojasro@336 261 To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This
jerojasro@336 262 command takes one argument, the name of the patch to create. MQ will
jerojasro@336 263 use this as the name of an actual file in the \sdirname{.hg/patches}
jerojasro@336 264 directory, as you can see in figure~\ref{ex:mq:qnew}.
jerojasro@336 265
jerojasro@336 266 Also newly present in the \sdirname{.hg/patches} directory are two
jerojasro@336 267 other files, \sfilename{series} and \sfilename{status}. The
jerojasro@336 268 \sfilename{series} file lists all of the patches that MQ knows about
jerojasro@336 269 for this repository, with one patch per line. Mercurial uses the
jerojasro@336 270 \sfilename{status} file for internal book-keeping; it tracks all of the
jerojasro@336 271 patches that MQ has \emph{applied} in this repository.
jerojasro@336 272
jerojasro@336 273 \begin{note}
jerojasro@336 274 You may sometimes want to edit the \sfilename{series} file by hand;
jerojasro@336 275 for example, to change the sequence in which some patches are
jerojasro@336 276 applied. However, manually editing the \sfilename{status} file is
jerojasro@336 277 almost always a bad idea, as it's easy to corrupt MQ's idea of what
jerojasro@336 278 is happening.
jerojasro@336 279 \end{note}
jerojasro@336 280
jerojasro@336 281 Once you have created your new patch, you can edit files in the
jerojasro@336 282 working directory as you usually would. All of the normal Mercurial
jerojasro@336 283 commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
jerojasro@336 284 they did before.
jerojasro@336 285
jerojasro@336 286 \subsection{Refreshing a patch}
jerojasro@336 287
jerojasro@336 288 When you reach a point where you want to save your work, use the
jerojasro@336 289 \hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
jerojasro@336 290 you are working on. This command folds the changes you have made in
jerojasro@336 291 the working directory into your patch, and updates its corresponding
jerojasro@336 292 changeset to contain those changes.
jerojasro@336 293
jerojasro@336 294 \begin{figure}[ht]
jerojasro@336 295 \interaction{mq.tutorial.qrefresh}
jerojasro@336 296 \caption{Refreshing a patch}
jerojasro@336 297 \label{ex:mq:qrefresh}
jerojasro@336 298 \end{figure}
jerojasro@336 299
jerojasro@336 300 You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way
jerojasro@336 301 to ``checkpoint'' your work. Refresh your patch at an opportune
jerojasro@336 302 time; try an experiment; and if the experiment doesn't work out,
jerojasro@336 303 \hgcmd{revert} your modifications back to the last time you refreshed.
jerojasro@336 304
jerojasro@336 305 \begin{figure}[ht]
jerojasro@336 306 \interaction{mq.tutorial.qrefresh2}
jerojasro@336 307 \caption{Refresh a patch many times to accumulate changes}
jerojasro@336 308 \label{ex:mq:qrefresh2}
jerojasro@336 309 \end{figure}
jerojasro@336 310
jerojasro@336 311 \subsection{Stacking and tracking patches}
jerojasro@336 312
jerojasro@336 313 Once you have finished working on a patch, or need to work on another,
jerojasro@336 314 you can use the \hgxcmd{mq}{qnew} command again to create a new patch.
jerojasro@336 315 Mercurial will apply this patch on top of your existing patch. See
jerojasro@336 316 figure~\ref{ex:mq:qnew2} for an example. Notice that the patch
jerojasro@336 317 contains the changes in our prior patch as part of its context (you
jerojasro@336 318 can see this more clearly in the output of \hgcmd{annotate}).
jerojasro@336 319
jerojasro@336 320 \begin{figure}[ht]
jerojasro@336 321 \interaction{mq.tutorial.qnew2}
jerojasro@336 322 \caption{Stacking a second patch on top of the first}
jerojasro@336 323 \label{ex:mq:qnew2}
jerojasro@336 324 \end{figure}
jerojasro@336 325
jerojasro@336 326 So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've
jerojasro@336 327 been careful to only use regular Mercurial commands. However, MQ
jerojasro@336 328 provides many commands that are easier to use when you are thinking
jerojasro@336 329 about patches, as illustrated in figure~\ref{ex:mq:qseries}:
jerojasro@336 330
jerojasro@336 331 \begin{itemize}
jerojasro@336 332 \item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows
jerojasro@336 333 about in this repository, from oldest to newest (most recently
jerojasro@336 334 \emph{created}).
jerojasro@336 335 \item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has
jerojasro@336 336 \emph{applied} in this repository, again from oldest to newest (most
jerojasro@336 337 recently applied).
jerojasro@336 338 \end{itemize}
jerojasro@336 339
jerojasro@336 340 \begin{figure}[ht]
jerojasro@336 341 \interaction{mq.tutorial.qseries}
jerojasro@336 342 \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and
jerojasro@336 343 \hgxcmd{mq}{qapplied}}
jerojasro@336 344 \label{ex:mq:qseries}
jerojasro@336 345 \end{figure}
jerojasro@336 346
jerojasro@336 347 \subsection{Manipulating the patch stack}
jerojasro@336 348
jerojasro@336 349 The previous discussion implied that there must be a difference
jerojasro@336 350 between ``known'' and ``applied'' patches, and there is. MQ can
jerojasro@336 351 manage a patch without it being applied in the repository.
jerojasro@336 352
jerojasro@336 353 An \emph{applied} patch has a corresponding changeset in the
jerojasro@336 354 repository, and the effects of the patch and changeset are visible in
jerojasro@336 355 the working directory. You can undo the application of a patch using
jerojasro@336 356 the \hgxcmd{mq}{qpop} command. MQ still \emph{knows about}, or manages, a
jerojasro@336 357 popped patch, but the patch no longer has a corresponding changeset in
jerojasro@336 358 the repository, and the working directory does not contain the changes
jerojasro@336 359 made by the patch. Figure~\ref{fig:mq:stack} illustrates the
jerojasro@336 360 difference between applied and tracked patches.
jerojasro@336 361
jerojasro@336 362 \begin{figure}[ht]
jerojasro@336 363 \centering
jerojasro@336 364 \grafix{mq-stack}
jerojasro@336 365 \caption{Applied and unapplied patches in the MQ patch stack}
jerojasro@336 366 \label{fig:mq:stack}
jerojasro@336 367 \end{figure}
jerojasro@336 368
jerojasro@336 369 You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush}
jerojasro@336 370 command. This creates a new changeset to correspond to the patch, and
jerojasro@336 371 the patch's changes once again become present in the working
jerojasro@336 372 directory. See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop}
jerojasro@336 373 and \hgxcmd{mq}{qpush} in action. Notice that once we have popped a patch
jerojasro@336 374 or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while
jerojasro@336 375 that of \hgxcmd{mq}{qapplied} has changed.
jerojasro@336 376
jerojasro@336 377 \begin{figure}[ht]
jerojasro@336 378 \interaction{mq.tutorial.qpop}
jerojasro@336 379 \caption{Modifying the stack of applied patches}
jerojasro@336 380 \label{ex:mq:qpop}
jerojasro@336 381 \end{figure}
jerojasro@336 382
jerojasro@336 383 \subsection{Pushing and popping many patches}
jerojasro@336 384
jerojasro@336 385 While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at
jerojasro@336 386 a time by default, you can push and pop many patches in one go. The
jerojasro@336 387 \hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all
jerojasro@336 388 unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop}
jerojasro@336 389 causes it to pop all applied patches. (For some more ways to push and
jerojasro@336 390 pop many patches, see section~\ref{sec:mq:perf} below.)
jerojasro@336 391
jerojasro@336 392 \begin{figure}[ht]
jerojasro@336 393 \interaction{mq.tutorial.qpush-a}
jerojasro@336 394 \caption{Pushing all unapplied patches}
jerojasro@336 395 \label{ex:mq:qpush-a}
jerojasro@336 396 \end{figure}
jerojasro@336 397
jerojasro@336 398 \subsection{Safety checks, and overriding them}
jerojasro@336 399
jerojasro@336 400 Several MQ commands check the working directory before they do
jerojasro@336 401 anything, and fail if they find any modifications. They do this to
jerojasro@336 402 ensure that you won't lose any changes that you have made, but not yet
jerojasro@336 403 incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this;
jerojasro@336 404 the \hgxcmd{mq}{qnew} command will not create a new patch if there are
jerojasro@336 405 outstanding changes, caused in this case by the \hgcmd{add} of
jerojasro@336 406 \filename{file3}.
jerojasro@336 407
jerojasro@336 408 \begin{figure}[ht]
jerojasro@336 409 \interaction{mq.tutorial.add}
jerojasro@336 410 \caption{Forcibly creating a patch}
jerojasro@336 411 \label{ex:mq:add}
jerojasro@336 412 \end{figure}
jerojasro@336 413
jerojasro@336 414 Commands that check the working directory all take an ``I know what
jerojasro@336 415 I'm doing'' option, which is always named \option{-f}. The exact
jerojasro@336 416 meaning of \option{-f} depends on the command. For example,
jerojasro@336 417 \hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding
jerojasro@336 418 changes into the new patch it creates, but
jerojasro@336 419 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any
jerojasro@336 420 files affected by the patch that it is popping. Be sure to read the
jerojasro@336 421 documentation for a command's \option{-f} option before you use it!
jerojasro@336 422
jerojasro@336 423 \subsection{Working on several patches at once}
jerojasro@336 424
jerojasro@336 425 The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost}
jerojasro@336 426 applied patch. This means that you can suspend work on one patch (by
jerojasro@336 427 refreshing it), pop or push to make a different patch the top, and
jerojasro@336 428 work on \emph{that} patch for a while.
jerojasro@336 429
jerojasro@336 430 Here's an example that illustrates how you can use this ability.
jerojasro@336 431 Let's say you're developing a new feature as two patches. The first
jerojasro@336 432 is a change to the core of your software, and the second---layered on
jerojasro@336 433 top of the first---changes the user interface to use the code you just
jerojasro@336 434 added to the core. If you notice a bug in the core while you're
jerojasro@336 435 working on the UI patch, it's easy to fix the core. Simply
jerojasro@336 436 \hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and
jerojasro@336 437 \hgxcmd{mq}{qpop} down to the core patch. Fix the core bug,
jerojasro@336 438 \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI
jerojasro@336 439 patch to continue where you left off.
jerojasro@336 440
jerojasro@336 441 \section{More about patches}
jerojasro@336 442 \label{sec:mq:adv-patch}
jerojasro@336 443
jerojasro@336 444 MQ uses the GNU \command{patch} command to apply patches, so it's
jerojasro@336 445 helpful to know a few more detailed aspects of how \command{patch}
jerojasro@336 446 works, and about patches themselves.
jerojasro@336 447
jerojasro@336 448 \subsection{The strip count}
jerojasro@336 449
jerojasro@336 450 If you look at the file headers in a patch, you will notice that the
jerojasro@336 451 pathnames usually have an extra component on the front that isn't
jerojasro@336 452 present in the actual path name. This is a holdover from the way that
jerojasro@336 453 people used to generate patches (people still do this, but it's
jerojasro@336 454 somewhat rare with modern revision control tools).
jerojasro@336 455
jerojasro@336 456 Alice would unpack a tarball, edit her files, then decide that she
jerojasro@336 457 wanted to create a patch. So she'd rename her working directory,
jerojasro@336 458 unpack the tarball again (hence the need for the rename), and use the
jerojasro@336 459 \cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to
jerojasro@336 460 recursively generate a patch between the unmodified directory and the
jerojasro@336 461 modified one. The result would be that the name of the unmodified
jerojasro@336 462 directory would be at the front of the left-hand path in every file
jerojasro@336 463 header, and the name of the modified directory would be at the front
jerojasro@336 464 of the right-hand path.
jerojasro@336 465
jerojasro@336 466 Since someone receiving a patch from the Alices of the net would be
jerojasro@336 467 unlikely to have unmodified and modified directories with exactly the
jerojasro@336 468 same names, the \command{patch} command has a \cmdopt{patch}{-p}
jerojasro@336 469 option that indicates the number of leading path name components to
jerojasro@336 470 strip when trying to apply a patch. This number is called the
jerojasro@336 471 \emph{strip count}.
jerojasro@336 472
jerojasro@336 473 An option of ``\texttt{-p1}'' means ``use a strip count of one''. If
jerojasro@336 474 \command{patch} sees a file name \filename{foo/bar/baz} in a file
jerojasro@336 475 header, it will strip \filename{foo} and try to patch a file named
jerojasro@336 476 \filename{bar/baz}. (Strictly speaking, the strip count refers to the
jerojasro@336 477 number of \emph{path separators} (and the components that go with them
jerojasro@336 478 ) to strip. A strip count of one will turn \filename{foo/bar} into
jerojasro@336 479 \filename{bar}, but \filename{/foo/bar} (notice the extra leading
jerojasro@336 480 slash) into \filename{foo/bar}.)
jerojasro@336 481
jerojasro@336 482 The ``standard'' strip count for patches is one; almost all patches
jerojasro@336 483 contain one leading path name component that needs to be stripped.
jerojasro@336 484 Mercurial's \hgcmd{diff} command generates path names in this form,
jerojasro@336 485 and the \hgcmd{import} command and MQ expect patches to have a strip
jerojasro@336 486 count of one.
jerojasro@336 487
jerojasro@336 488 If you receive a patch from someone that you want to add to your patch
jerojasro@336 489 queue, and the patch needs a strip count other than one, you cannot
jerojasro@336 490 just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet
jerojasro@336 491 have a \texttt{-p} option (see~\bug{311}). Your best bet is to
jerojasro@336 492 \hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}}
jerojasro@336 493 to apply their patch, followed by \hgcmd{addremove} to pick up any
jerojasro@336 494 files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}.
jerojasro@336 495 This complexity may become unnecessary; see~\bug{311} for details.
jerojasro@336 496 \subsection{Strategies for applying a patch}
jerojasro@336 497
jerojasro@336 498 When \command{patch} applies a hunk, it tries a handful of
jerojasro@336 499 successively less accurate strategies to try to make the hunk apply.
jerojasro@336 500 This falling-back technique often makes it possible to take a patch
jerojasro@336 501 that was generated against an old version of a file, and apply it
jerojasro@336 502 against a newer version of that file.
jerojasro@336 503
jerojasro@336 504 First, \command{patch} tries an exact match, where the line numbers,
jerojasro@336 505 the context, and the text to be modified must apply exactly. If it
jerojasro@336 506 cannot make an exact match, it tries to find an exact match for the
jerojasro@336 507 context, without honouring the line numbering information. If this
jerojasro@336 508 succeeds, it prints a line of output saying that the hunk was applied,
jerojasro@336 509 but at some \emph{offset} from the original line number.
jerojasro@336 510
jerojasro@336 511 If a context-only match fails, \command{patch} removes the first and
jerojasro@336 512 last lines of the context, and tries a \emph{reduced} context-only
jerojasro@336 513 match. If the hunk with reduced context succeeds, it prints a message
jerojasro@336 514 saying that it applied the hunk with a \emph{fuzz factor} (the number
jerojasro@336 515 after the fuzz factor indicates how many lines of context
jerojasro@336 516 \command{patch} had to trim before the patch applied).
jerojasro@336 517
jerojasro@336 518 When neither of these techniques works, \command{patch} prints a
jerojasro@336 519 message saying that the hunk in question was rejected. It saves
jerojasro@336 520 rejected hunks (also simply called ``rejects'') to a file with the
jerojasro@336 521 same name, and an added \sfilename{.rej} extension. It also saves an
jerojasro@336 522 unmodified copy of the file with a \sfilename{.orig} extension; the
jerojasro@336 523 copy of the file without any extensions will contain any changes made
jerojasro@336 524 by hunks that \emph{did} apply cleanly. If you have a patch that
jerojasro@336 525 modifies \filename{foo} with six hunks, and one of them fails to
jerojasro@336 526 apply, you will have: an unmodified \filename{foo.orig}, a
jerojasro@336 527 \filename{foo.rej} containing one hunk, and \filename{foo}, containing
jerojasro@336 528 the changes made by the five successful five hunks.
jerojasro@336 529
jerojasro@336 530 \subsection{Some quirks of patch representation}
jerojasro@336 531
jerojasro@336 532 There are a few useful things to know about how \command{patch} works
jerojasro@336 533 with files.
jerojasro@336 534 \begin{itemize}
jerojasro@336 535 \item This should already be obvious, but \command{patch} cannot
jerojasro@336 536 handle binary files.
jerojasro@336 537 \item Neither does it care about the executable bit; it creates new
jerojasro@336 538 files as readable, but not executable.
jerojasro@336 539 \item \command{patch} treats the removal of a file as a diff between
jerojasro@336 540 the file to be removed and the empty file. So your idea of ``I
jerojasro@336 541 deleted this file'' looks like ``every line of this file was
jerojasro@336 542 deleted'' in a patch.
jerojasro@336 543 \item It treats the addition of a file as a diff between the empty
jerojasro@336 544 file and the file to be added. So in a patch, your idea of ``I
jerojasro@336 545 added this file'' looks like ``every line of this file was added''.
jerojasro@336 546 \item It treats a renamed file as the removal of the old name, and the
jerojasro@336 547 addition of the new name. This means that renamed files have a big
jerojasro@336 548 footprint in patches. (Note also that Mercurial does not currently
jerojasro@336 549 try to infer when files have been renamed or copied in a patch.)
jerojasro@336 550 \item \command{patch} cannot represent empty files, so you cannot use
jerojasro@336 551 a patch to represent the notion ``I added this empty file to the
jerojasro@336 552 tree''.
jerojasro@336 553 \end{itemize}
jerojasro@336 554 \subsection{Beware the fuzz}
jerojasro@336 555
jerojasro@336 556 While applying a hunk at an offset, or with a fuzz factor, will often
jerojasro@336 557 be completely successful, these inexact techniques naturally leave
jerojasro@336 558 open the possibility of corrupting the patched file. The most common
jerojasro@336 559 cases typically involve applying a patch twice, or at an incorrect
jerojasro@336 560 location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever
jerojasro@336 561 mentions an offset or fuzz factor, you should make sure that the
jerojasro@336 562 modified files are correct afterwards.
jerojasro@336 563
jerojasro@336 564 It's often a good idea to refresh a patch that has applied with an
jerojasro@336 565 offset or fuzz factor; refreshing the patch generates new context
jerojasro@336 566 information that will make it apply cleanly. I say ``often,'' not
jerojasro@336 567 ``always,'' because sometimes refreshing a patch will make it fail to
jerojasro@336 568 apply against a different revision of the underlying files. In some
jerojasro@336 569 cases, such as when you're maintaining a patch that must sit on top of
jerojasro@336 570 multiple versions of a source tree, it's acceptable to have a patch
jerojasro@336 571 apply with some fuzz, provided you've verified the results of the
jerojasro@336 572 patching process in such cases.
jerojasro@336 573
jerojasro@336 574 \subsection{Handling rejection}
jerojasro@336 575
jerojasro@336 576 If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
jerojasro@336 577 message and exit. If it has left \sfilename{.rej} files behind, it is
jerojasro@336 578 usually best to fix up the rejected hunks before you push more patches
jerojasro@336 579 or do any further work.
jerojasro@336 580
jerojasro@336 581 If your patch \emph{used to} apply cleanly, and no longer does because
jerojasro@336 582 you've changed the underlying code that your patches are based on,
jerojasro@336 583 Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.
jerojasro@336 584
jerojasro@336 585 Unfortunately, there aren't any great techniques for dealing with
jerojasro@336 586 rejected hunks. Most often, you'll need to view the \sfilename{.rej}
jerojasro@336 587 file and edit the target file, applying the rejected hunks by hand.
jerojasro@336 588
jerojasro@336 589 If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
jerojasro@336 590 wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
jerojasro@336 591 vigorous than \command{patch} in its attempts to make a patch apply.
jerojasro@336 592
jerojasro@336 593 Another Linux kernel hacker, Chris Mason (the author of Mercurial
jerojasro@336 594 Queues), wrote a similar tool called
jerojasro@336 595 \command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
jerojasro@336 596 automating the application of hunks rejected by \command{patch}. The
jerojasro@336 597 \command{mpatch} command can help with four common reasons that a hunk
jerojasro@336 598 may be rejected:
jerojasro@336 599
jerojasro@336 600 \begin{itemize}
jerojasro@336 601 \item The context in the middle of a hunk has changed.
jerojasro@336 602 \item A hunk is missing some context at the beginning or end.
jerojasro@336 603 \item A large hunk might apply better---either entirely or in
jerojasro@336 604 part---if it was broken up into smaller hunks.
jerojasro@336 605 \item A hunk removes lines with slightly different content than those
jerojasro@336 606 currently present in the file.
jerojasro@336 607 \end{itemize}
jerojasro@336 608
jerojasro@336 609 If you use \command{wiggle} or \command{mpatch}, you should be doubly
jerojasro@336 610 careful to check your results when you're done. In fact,
jerojasro@336 611 \command{mpatch} enforces this method of double-checking the tool's
jerojasro@336 612 output, by automatically dropping you into a merge program when it has
jerojasro@336 613 done its job, so that you can verify its work and finish off any
jerojasro@336 614 remaining merges.
jerojasro@336 615
jerojasro@336 616 \section{Getting the best performance out of MQ}
jerojasro@336 617 \label{sec:mq:perf}
jerojasro@336 618
jerojasro@336 619 MQ is very efficient at handling a large number of patches. I ran
jerojasro@336 620 some performance experiments in mid-2006 for a talk that I gave at the
jerojasro@336 621 2006 EuroPython conference~\cite{web:europython}. I used as my data
jerojasro@336 622 set the Linux 2.6.17-mm1 patch series, which consists of 1,738
jerojasro@336 623 patches. I applied these on top of a Linux kernel repository
jerojasro@336 624 containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
jerojasro@336 625 2.6.17.
jerojasro@336 626
jerojasro@336 627 On my old, slow laptop, I was able to
jerojasro@336 628 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
jerojasro@336 629 and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds. (On a
jerojasro@336 630 newer laptop, the time to push all patches dropped to two minutes.) I
jerojasro@336 631 could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
jerojasro@336 632 lines of changes to 287 files) in 6.6 seconds.
jerojasro@336 633
jerojasro@336 634 Clearly, MQ is well suited to working in large trees, but there are a
jerojasro@336 635 few tricks you can use to get the best performance of it.
jerojasro@336 636
jerojasro@336 637 First of all, try to ``batch'' operations together. Every time you
jerojasro@336 638 run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
jerojasro@336 639 directory once to make sure you haven't made some changes and then
jerojasro@336 640 forgotten to run \hgxcmd{mq}{qrefresh}. On a small tree, the time that
jerojasro@336 641 this scan takes is unnoticeable. However, on a medium-sized tree
jerojasro@336 642 (containing tens of thousands of files), it can take a second or more.
jerojasro@336 643
jerojasro@336 644 The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
jerojasro@336 645 multiple patches at a time. You can identify the ``destination
jerojasro@336 646 patch'' that you want to end up at. When you \hgxcmd{mq}{qpush} with a
jerojasro@336 647 destination specified, it will push patches until that patch is at the
jerojasro@336 648 top of the applied stack. When you \hgxcmd{mq}{qpop} to a destination, MQ
jerojasro@336 649 will pop patches until the destination patch is at the top.
jerojasro@336 650
jerojasro@336 651 You can identify a destination patch using either the name of the
jerojasro@336 652 patch, or by number. If you use numeric addressing, patches are
jerojasro@336 653 counted from zero; this means that the first patch is zero, the second
jerojasro@336 654 is one, and so on.
jerojasro@336 655
jerojasro@336 656 \section{Updating your patches when the underlying code changes}
jerojasro@336 657 \label{sec:mq:merge}
jerojasro@336 658
jerojasro@336 659 It's common to have a stack of patches on top of an underlying
jerojasro@336 660 repository that you don't modify directly. If you're working on
jerojasro@336 661 changes to third-party code, or on a feature that is taking longer to
jerojasro@336 662 develop than the rate of change of the code beneath, you will often
jerojasro@336 663 need to sync up with the underlying code, and fix up any hunks in your
jerojasro@336 664 patches that no longer apply. This is called \emph{rebasing} your
jerojasro@336 665 patch series.
jerojasro@336 666
jerojasro@336 667 The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}
jerojasro@336 668 your patches, then \hgcmd{pull} changes into the underlying
jerojasro@336 669 repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your
jerojasro@336 670 patches again. MQ will stop pushing any time it runs across a patch
jerojasro@336 671 that fails to apply during conflicts, allowing you to fix your
jerojasro@336 672 conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing
jerojasro@336 673 until you have fixed your entire stack.
jerojasro@336 674
jerojasro@336 675 This approach is easy to use and works well if you don't expect
jerojasro@336 676 changes to the underlying code to affect how well your patches apply.
jerojasro@336 677 If your patch stack touches code that is modified frequently or
jerojasro@336 678 invasively in the underlying repository, however, fixing up rejected
jerojasro@336 679 hunks by hand quickly becomes tiresome.
jerojasro@336 680
jerojasro@336 681 It's possible to partially automate the rebasing process. If your
jerojasro@336 682 patches apply cleanly against some revision of the underlying repo, MQ
jerojasro@336 683 can use this information to help you to resolve conflicts between your
jerojasro@336 684 patches and a different revision.
jerojasro@336 685
jerojasro@336 686 The process is a little involved.
jerojasro@336 687 \begin{enumerate}
jerojasro@336 688 \item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of
jerojasro@336 689 the revision where you know that they apply cleanly.
jerojasro@336 690 \item Save a backup copy of your patch directory using
jerojasro@336 691 \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. This prints
jerojasro@336 692 the name of the directory that it has saved the patches in. It will
jerojasro@336 693 save the patches to a directory called
jerojasro@336 694 \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small
jerojasro@336 695 integer. It also commits a ``save changeset'' on top of your
jerojasro@336 696 applied patches; this is for internal book-keeping, and records the
jerojasro@336 697 states of the \sfilename{series} and \sfilename{status} files.
jerojasro@336 698 \item Use \hgcmd{pull} to bring new changes into the underlying
jerojasro@336 699 repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.)
jerojasro@336 700 \item Update to the new tip revision, using
jerojasro@336 701 \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
jerojasro@336 702 have pushed.
jerojasro@336 703 \item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}
jerojasro@336 704 \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush}
jerojasro@336 705 tells MQ to perform a three-way merge if the patch fails to apply.
jerojasro@336 706 \end{enumerate}
jerojasro@336 707
jerojasro@336 708 During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the
jerojasro@336 709 \sfilename{series} file is applied normally. If a patch applies with
jerojasro@336 710 fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and
jerojasro@336 711 performs a three-way merge with the corresponding changeset. This
jerojasro@336 712 merge uses Mercurial's normal merge machinery, so it may pop up a GUI
jerojasro@336 713 merge tool to help you to resolve problems.
jerojasro@336 714
jerojasro@336 715 When you finish resolving the effects of a patch, MQ refreshes your
jerojasro@336 716 patch based on the result of the merge.
jerojasro@336 717
jerojasro@336 718 At the end of this process, your repository will have one extra head
jerojasro@336 719 from the old patch queue, and a copy of the old patch queue will be in
jerojasro@336 720 \sdirname{.hg/patches.\emph{N}}. You can remove the extra head using
jerojasro@336 721 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}
jerojasro@336 722 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once
jerojasro@336 723 you are sure that you no longer need it as a backup.
jerojasro@336 724
jerojasro@336 725 \section{Identifying patches}
jerojasro@336 726
jerojasro@336 727 MQ commands that work with patches let you refer to a patch either by
jerojasro@336 728 using its name or by a number. By name is obvious enough; pass the
jerojasro@336 729 name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will
jerojasro@336 730 push patches until \filename{foo.patch} is applied.
jerojasro@336 731
jerojasro@336 732 As a shortcut, you can refer to a patch using both a name and a
jerojasro@336 733 numeric offset; \texttt{foo.patch-2} means ``two patches before
jerojasro@336 734 \texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
jerojasro@336 735 after \texttt{bar.patch}''.
jerojasro@336 736
jerojasro@336 737 Referring to a patch by index isn't much different. The first patch
jerojasro@336 738 printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one
jerojasro@336 739 of those start-at-zero counting systems); the second is patch one; and
jerojasro@336 740 so on.
jerojasro@336 741
jerojasro@336 742 MQ also makes it easy to work with patches when you are using normal
jerojasro@336 743 Mercurial commands. Every command that accepts a changeset ID will
jerojasro@336 744 also accept the name of an applied patch. MQ augments the tags
jerojasro@336 745 normally in the repository with an eponymous one for each applied
jerojasro@336 746 patch. In addition, the special tags \index{tags!special tag
jerojasro@336 747 names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
jerojasro@336 748 names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
jerojasro@336 749 topmost applied patches, respectively.
jerojasro@336 750
jerojasro@336 751 These additions to Mercurial's normal tagging capabilities make
jerojasro@336 752 dealing with patches even more of a breeze.
jerojasro@336 753 \begin{itemize}
jerojasro@336 754 \item Want to patchbomb a mailing list with your latest series of
jerojasro@336 755 changes?
jerojasro@336 756 \begin{codesample4}
jerojasro@336 757 hg email qbase:qtip
jerojasro@336 758 \end{codesample4}
jerojasro@336 759 (Don't know what ``patchbombing'' is? See
jerojasro@336 760 section~\ref{sec:hgext:patchbomb}.)
jerojasro@336 761 \item Need to see all of the patches since \texttt{foo.patch} that
jerojasro@336 762 have touched files in a subdirectory of your tree?
jerojasro@336 763 \begin{codesample4}
jerojasro@336 764 hg log -r foo.patch:qtip \emph{subdir}
jerojasro@336 765 \end{codesample4}
jerojasro@336 766 \end{itemize}
jerojasro@336 767
jerojasro@336 768 Because MQ makes the names of patches available to the rest of
jerojasro@336 769 Mercurial through its normal internal tag machinery, you don't need to
jerojasro@336 770 type in the entire name of a patch when you want to identify it by
jerojasro@336 771 name.
jerojasro@336 772
jerojasro@336 773 \begin{figure}[ht]
jerojasro@336 774 \interaction{mq.id.output}
jerojasro@336 775 \caption{Using MQ's tag features to work with patches}
jerojasro@336 776 \label{ex:mq:id}
jerojasro@336 777 \end{figure}
jerojasro@336 778
jerojasro@336 779 Another nice consequence of representing patch names as tags is that
jerojasro@336 780 when you run the \hgcmd{log} command, it will display a patch's name
jerojasro@336 781 as a tag, simply as part of its normal output. This makes it easy to
jerojasro@336 782 visually distinguish applied patches from underlying ``normal''
jerojasro@336 783 revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial
jerojasro@336 784 commands in use with applied patches.
jerojasro@336 785
jerojasro@336 786 \section{Useful things to know about}
jerojasro@336 787
jerojasro@336 788 There are a number of aspects of MQ usage that don't fit tidily into
jerojasro@336 789 sections of their own, but that are good to know. Here they are, in
jerojasro@336 790 one place.
jerojasro@336 791
jerojasro@336 792 \begin{itemize}
jerojasro@336 793 \item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it
jerojasro@336 794 again, the changeset that represents the patch after the pop/push
jerojasro@336 795 will have a \emph{different identity} than the changeset that
jerojasro@336 796 represented the hash beforehand. See
jerojasro@336 797 section~\ref{sec:mqref:cmd:qpush} for information as to why this is.
jerojasro@336 798 \item It's not a good idea to \hgcmd{merge} changes from another
jerojasro@336 799 branch with a patch changeset, at least if you want to maintain the
jerojasro@336 800 ``patchiness'' of that changeset and changesets below it on the
jerojasro@336 801 patch stack. If you try to do this, it will appear to succeed, but
jerojasro@336 802 MQ will become confused.
jerojasro@336 803 \end{itemize}
jerojasro@336 804
jerojasro@336 805 \section{Managing patches in a repository}
jerojasro@336 806 \label{sec:mq:repo}
jerojasro@336 807
jerojasro@336 808 Because MQ's \sdirname{.hg/patches} directory resides outside a
jerojasro@336 809 Mercurial repository's working directory, the ``underlying'' Mercurial
jerojasro@336 810 repository knows nothing about the management or presence of patches.
jerojasro@336 811
jerojasro@336 812 This presents the interesting possibility of managing the contents of
jerojasro@336 813 the patch directory as a Mercurial repository in its own right. This
jerojasro@336 814 can be a useful way to work. For example, you can work on a patch for
jerojasro@336 815 a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of
jerojasro@336 816 the patch. This lets you ``roll back'' to that version of the patch
jerojasro@336 817 later on.
jerojasro@336 818
jerojasro@336 819 You can then share different versions of the same patch stack among
jerojasro@336 820 multiple underlying repositories. I use this when I am developing a
jerojasro@336 821 Linux kernel feature. I have a pristine copy of my kernel sources for
jerojasro@336 822 each of several CPU architectures, and a cloned repository under each
jerojasro@336 823 that contains the patches I am working on. When I want to test a
jerojasro@336 824 change on a different architecture, I push my current patches to the
jerojasro@336 825 patch repository associated with that kernel tree, pop and push all of
jerojasro@336 826 my patches, and build and test that kernel.
jerojasro@336 827
jerojasro@336 828 Managing patches in a repository makes it possible for multiple
jerojasro@336 829 developers to work on the same patch series without colliding with
jerojasro@336 830 each other, all on top of an underlying source base that they may or
jerojasro@336 831 may not control.
jerojasro@336 832
jerojasro@336 833 \subsection{MQ support for patch repositories}
jerojasro@336 834
jerojasro@336 835 MQ helps you to work with the \sdirname{.hg/patches} directory as a
jerojasro@336 836 repository; when you prepare a repository for working with patches
jerojasro@336 837 using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to
jerojasro@336 838 create the \sdirname{.hg/patches} directory as a Mercurial repository.
jerojasro@336 839
jerojasro@336 840 \begin{note}
jerojasro@336 841 If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go
jerojasro@336 842 into the \sdirname{.hg/patches} directory at any time and run
jerojasro@336 843 \hgcmd{init}. Don't forget to add an entry for the
jerojasro@336 844 \sfilename{status} file to the \sfilename{.hgignore} file, though
jerojasro@336 845
jerojasro@336 846 (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you
jerojasro@336 847 automatically); you \emph{really} don't want to manage the
jerojasro@336 848 \sfilename{status} file.
jerojasro@336 849 \end{note}
jerojasro@336 850
jerojasro@336 851 As a convenience, if MQ notices that the \dirname{.hg/patches}
jerojasro@336 852 directory is a repository, it will automatically \hgcmd{add} every
jerojasro@336 853 patch that you create and import.
jerojasro@336 854
jerojasro@336 855 MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs
jerojasro@336 856 \hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves
jerojasro@336 857 some bothersome typing.
jerojasro@336 858
jerojasro@336 859 Finally, as a convenience to manage the patch directory, you can
jerojasro@336 860 define the alias \command{mq} on Unix systems. For example, on Linux
jerojasro@336 861 systems using the \command{bash} shell, you can include the following
jerojasro@336 862 snippet in your \tildefile{.bashrc}.
jerojasro@336 863
jerojasro@336 864 \begin{codesample2}
jerojasro@336 865 alias mq=`hg -R \$(hg root)/.hg/patches'
jerojasro@336 866 \end{codesample2}
jerojasro@336 867
jerojasro@336 868 You can then issue commands of the form \cmdargs{mq}{pull} from
jerojasro@336 869 the main repository.
jerojasro@336 870
jerojasro@336 871 \subsection{A few things to watch out for}
jerojasro@336 872
jerojasro@336 873 MQ's support for working with a repository full of patches is limited
jerojasro@336 874 in a few small respects.
jerojasro@336 875
jerojasro@336 876 MQ cannot automatically detect changes that you make to the patch
jerojasro@336 877 directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update}
jerojasro@336 878 changes to patches or the \sfilename{series} file, you will have to
jerojasro@336 879 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then
jerojasro@336 880 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to
jerojasro@336 881 see those changes show up there. If you forget to do this, you can
jerojasro@336 882 confuse MQ's idea of which patches are applied.
jerojasro@336 883
jerojasro@336 884 \section{Third party tools for working with patches}
jerojasro@336 885 \label{sec:mq:tools}
jerojasro@336 886
jerojasro@336 887 Once you've been working with patches for a while, you'll find
jerojasro@336 888 yourself hungry for tools that will help you to understand and
jerojasro@336 889 manipulate the patches you're dealing with.
jerojasro@336 890
jerojasro@336 891 The \command{diffstat} command~\cite{web:diffstat} generates a
jerojasro@336 892 histogram of the modifications made to each file in a patch. It
jerojasro@336 893 provides a good way to ``get a sense of'' a patch---which files it
jerojasro@336 894 affects, and how much change it introduces to each file and as a
jerojasro@336 895 whole. (I find that it's a good idea to use \command{diffstat}'s
jerojasro@336 896 \cmdopt{diffstat}{-p} option as a matter of course, as otherwise it
jerojasro@336 897 will try to do clever things with prefixes of file names that
jerojasro@336 898 inevitably confuse at least me.)
jerojasro@336 899
jerojasro@336 900 \begin{figure}[ht]
jerojasro@336 901 \interaction{mq.tools.tools}
jerojasro@336 902 \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
jerojasro@336 903 \label{ex:mq:tools}
jerojasro@336 904 \end{figure}
jerojasro@336 905
jerojasro@336 906 The \package{patchutils} package~\cite{web:patchutils} is invaluable.
jerojasro@336 907 It provides a set of small utilities that follow the ``Unix
jerojasro@336 908 philosophy;'' each does one useful thing with a patch. The
jerojasro@336 909 \package{patchutils} command I use most is \command{filterdiff}, which
jerojasro@336 910 extracts subsets from a patch file. For example, given a patch that
jerojasro@336 911 modifies hundreds of files across dozens of directories, a single
jerojasro@336 912 invocation of \command{filterdiff} can generate a smaller patch that
jerojasro@336 913 only touches files whose names match a particular glob pattern. See
jerojasro@336 914 section~\ref{mq-collab:tips:interdiff} for another example.
jerojasro@336 915
jerojasro@336 916 \section{Good ways to work with patches}
jerojasro@336 917
jerojasro@336 918 Whether you are working on a patch series to submit to a free software
jerojasro@336 919 or open source project, or a series that you intend to treat as a
jerojasro@336 920 sequence of regular changesets when you're done, you can use some
jerojasro@336 921 simple techniques to keep your work well organised.
jerojasro@336 922
jerojasro@336 923 Give your patches descriptive names. A good name for a patch might be
jerojasro@336 924 \filename{rework-device-alloc.patch}, because it will immediately give
jerojasro@336 925 you a hint what the purpose of the patch is. Long names shouldn't be
jerojasro@336 926 a problem; you won't be typing the names often, but you \emph{will} be
jerojasro@336 927 running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over.
jerojasro@336 928 Good naming becomes especially important when you have a number of
jerojasro@336 929 patches to work with, or if you are juggling a number of different
jerojasro@336 930 tasks and your patches only get a fraction of your attention.
jerojasro@336 931
jerojasro@336 932 Be aware of what patch you're working on. Use the \hgxcmd{mq}{qtop}
jerojasro@336 933 command and skim over the text of your patches frequently---for
jerojasro@336 934 example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where
jerojasro@336 935 you stand. I have several times worked on and \hgxcmd{mq}{qrefresh}ed a
jerojasro@336 936 patch other than the one I intended, and it's often tricky to migrate
jerojasro@336 937 changes into the right patch after making them in the wrong one.
jerojasro@336 938
jerojasro@336 939 For this reason, it is very much worth investing a little time to
jerojasro@336 940 learn how to use some of the third-party tools I described in
jerojasro@336 941 section~\ref{sec:mq:tools}, particularly \command{diffstat} and
jerojasro@336 942 \command{filterdiff}. The former will give you a quick idea of what
jerojasro@336 943 changes your patch is making, while the latter makes it easy to splice
jerojasro@336 944 hunks selectively out of one patch and into another.
jerojasro@336 945
jerojasro@336 946 \section{MQ cookbook}
jerojasro@336 947
jerojasro@336 948 \subsection{Manage ``trivial'' patches}
jerojasro@336 949
jerojasro@336 950 Because the overhead of dropping files into a new Mercurial repository
jerojasro@336 951 is so low, it makes a lot of sense to manage patches this way even if
jerojasro@336 952 you simply want to make a few changes to a source tarball that you
jerojasro@336 953 downloaded.
jerojasro@336 954
jerojasro@336 955 Begin by downloading and unpacking the source tarball,
jerojasro@336 956 and turning it into a Mercurial repository.
jerojasro@336 957 \interaction{mq.tarball.download}
jerojasro@336 958
jerojasro@336 959 Continue by creating a patch stack and making your changes.
jerojasro@336 960 \interaction{mq.tarball.qinit}
jerojasro@336 961
jerojasro@336 962 Let's say a few weeks or months pass, and your package author releases
jerojasro@336 963 a new version. First, bring their changes into the repository.
jerojasro@336 964 \interaction{mq.tarball.newsource}
jerojasro@336 965 The pipeline starting with \hgcmd{locate} above deletes all files in
jerojasro@336 966 the working directory, so that \hgcmd{commit}'s
jerojasro@336 967 \hgopt{commit}{--addremove} option can actually tell which files have
jerojasro@336 968 really been removed in the newer version of the source.
jerojasro@336 969
jerojasro@336 970 Finally, you can apply your patches on top of the new tree.
jerojasro@336 971 \interaction{mq.tarball.repush}
jerojasro@336 972
jerojasro@336 973 \subsection{Combining entire patches}
jerojasro@336 974 \label{sec:mq:combine}
jerojasro@336 975
jerojasro@336 976 MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire
jerojasro@336 977 patches. This ``folds'' the patches you name, in the order you name
jerojasro@336 978 them, into the topmost applied patch, and concatenates their
jerojasro@336 979 descriptions onto the end of its description. The patches that you
jerojasro@336 980 fold must be unapplied before you fold them.
jerojasro@336 981
jerojasro@336 982 The order in which you fold patches matters. If your topmost applied
jerojasro@336 983 patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and
jerojasro@336 984 \texttt{quux} into it, you will end up with a patch that has the same
jerojasro@336 985 effect as if you applied first \texttt{foo}, then \texttt{bar},
jerojasro@336 986 followed by \texttt{quux}.
jerojasro@336 987
jerojasro@336 988 \subsection{Merging part of one patch into another}
jerojasro@336 989
jerojasro@336 990 Merging \emph{part} of one patch into another is more difficult than
jerojasro@336 991 combining entire patches.
jerojasro@336 992
jerojasro@336 993 If you want to move changes to entire files, you can use
jerojasro@336 994 \command{filterdiff}'s \cmdopt{filterdiff}{-i} and
jerojasro@336 995 \cmdopt{filterdiff}{-x} options to choose the modifications to snip
jerojasro@336 996 out of one patch, concatenating its output onto the end of the patch
jerojasro@336 997 you want to merge into. You usually won't need to modify the patch
jerojasro@336 998 you've merged the changes from. Instead, MQ will report some rejected
jerojasro@336 999 hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the
jerojasro@336 1000 other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop
jerojasro@336 1001 the duplicate hunks.
jerojasro@336 1002
jerojasro@336 1003 If you have a patch that has multiple hunks modifying a file, and you
jerojasro@336 1004 only want to move a few of those hunks, the job becomes more messy,
jerojasro@336 1005 but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to
jerojasro@336 1006 print some metadata about the patch.
jerojasro@336 1007 \interaction{mq.tools.lsdiff}
jerojasro@336 1008
jerojasro@336 1009 This command prints three different kinds of number:
jerojasro@336 1010 \begin{itemize}
jerojasro@336 1011 \item (in the first column) a \emph{file number} to identify each file
jerojasro@336 1012 modified in the patch;
jerojasro@336 1013 \item (on the next line, indented) the line number within a modified
jerojasro@336 1014 file where a hunk starts; and
jerojasro@336 1015 \item (on the same line) a \emph{hunk number} to identify that hunk.
jerojasro@336 1016 \end{itemize}
jerojasro@336 1017
jerojasro@336 1018 You'll have to use some visual inspection, and reading of the patch,
jerojasro@336 1019 to identify the file and hunk numbers you'll want, but you can then
jerojasro@336 1020 pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files}
jerojasro@336 1021 and \cmdopt{filterdiff}{--hunks} options, to select exactly the file
jerojasro@336 1022 and hunk you want to extract.
jerojasro@336 1023
jerojasro@336 1024 Once you have this hunk, you can concatenate it onto the end of your
jerojasro@336 1025 destination patch and continue with the remainder of
jerojasro@336 1026 section~\ref{sec:mq:combine}.
jerojasro@336 1027
jerojasro@336 1028 \section{Differences between quilt and MQ}
jerojasro@336 1029
jerojasro@336 1030 If you are already familiar with quilt, MQ provides a similar command
jerojasro@336 1031 set. There are a few differences in the way that it works.
jerojasro@336 1032
jerojasro@336 1033 You will already have noticed that most quilt commands have MQ
jerojasro@336 1034 counterparts that simply begin with a ``\texttt{q}''. The exceptions
jerojasro@336 1035 are quilt's \texttt{add} and \texttt{remove} commands, the
jerojasro@336 1036 counterparts for which are the normal Mercurial \hgcmd{add} and
jerojasro@336 1037 \hgcmd{remove} commands. There is no MQ equivalent of the quilt
jerojasro@336 1038 \texttt{edit} command.
jerojasro@336 1039
jerojasro@336 1040 %%% Local Variables:
jerojasro@336 1041 %%% mode: latex
jerojasro@336 1042 %%% TeX-master: "00book"
jerojasro@336 1043 %%% End: