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