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