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 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@7
|
230 \hgcmd{help} to see if the \hgcmd{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@8
|
241 the repository using the \hgcmd{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@7
|
244 with many Mercurial commands, the \hgcmd{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@8
|
261 To begin work on a new patch, use the \hgcmd{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@8
|
289 \hgcmd{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@8
|
300 You can run \hgcmd{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@8
|
314 you can use the \hgcmd{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@8
|
326 So far, with the exception of \hgcmd{qnew} and \hgcmd{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@8
|
332 \item The \hgcmd{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@8
|
335 \item The \hgcmd{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@8
|
342 \caption{Understanding the patch stack with \hgcmd{qseries} and
|
bos@8
|
343 \hgcmd{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@12
|
356 the \hgcmd{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@8
|
369 You can reapply an unapplied, or popped, patch using the \hgcmd{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@8
|
372 directory. See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop}
|
bos@8
|
373 and \hgcmd{qpush} in action. Notice that once we have popped a patch
|
bos@8
|
374 or two patches, the output of \hgcmd{qseries} remains the same, while
|
bos@8
|
375 that of \hgcmd{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@27
|
385 While \hgcmd{qpush} and \hgcmd{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@27
|
387 \hgopt{qpush}{-a} option to \hgcmd{qpush} causes it to push all
|
bos@27
|
388 unapplied patches, while the \hgopt{qpop}{-a} option to \hgcmd{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@27
|
404 the \hgcmd{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@27
|
417 \hgcmdargs{qnew}{\hgopt{qnew}{-f}} will incorporate any outstanding
|
bos@27
|
418 changes into the new patch it creates, but
|
bos@27
|
419 \hgcmdargs{qpop}{\hgopt{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@13
|
425 The \hgcmd{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@13
|
436 \hgcmd{qrefresh} the UI patch to save your in-progress changes, and
|
bos@13
|
437 \hgcmd{qpop} down to the core patch. Fix the core bug,
|
bos@13
|
438 \hgcmd{qrefresh} the core patch, and \hgcmd{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@26
|
490 just \hgcmd{qimport} the patch, because \hgcmd{qimport} does not yet
|
bos@26
|
491 have a \texttt{-p} option (see~\bug{311}). Your best bet is to
|
bos@26
|
492 \hgcmd{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@26
|
494 files added or removed by the patch, followed by \hgcmd{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@14
|
560 location in the file. If \command{patch} or \hgcmd{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@15
|
576 If \hgcmd{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@17
|
627 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes,
|
bos@50
|
628 and \hgcmdargs{qpop}{\hgopt{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@17
|
630 could \hgcmd{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@17
|
637 run \hgcmd{qpush} or \hgcmd{qpop}, these commands scan the working
|
bos@17
|
638 directory once to make sure you haven't made some changes and then
|
bos@17
|
639 forgotten to run \hgcmd{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@17
|
643 The \hgcmd{qpush} and \hgcmd{qpop} commands allow you to push and pop
|
bos@17
|
644 multiple patches at a time. You can identify the ``destination
|
bos@17
|
645 patch'' that you want to end up at. When you \hgcmd{qpush} with a
|
bos@17
|
646 destination specified, it will push patches until that patch is at the
|
bos@17
|
647 top of the applied stack. When you \hgcmd{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@17
|
666 The simplest way to do this is to \hgcmdargs{qpop}{\hgopt{qpop}{-a}}
|
bos@17
|
667 your patches, then \hgcmd{pull} changes into the underlying
|
bos@17
|
668 repository, and finally \hgcmdargs{qpush}{\hgopt{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@17
|
671 conflicts, \hgcmd{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@17
|
690 \hgcmdargs{qsave}{\hgopt{qsave}{-e} \hgopt{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@17
|
702 \item Merge all patches using \hgcmdargs{qpush}{\hgopt{qpush}{-m}
|
bos@17
|
703 \hgopt{qpush}{-a}}. The \hgopt{qpush}{-m} option to \hgcmd{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@17
|
707 During the \hgcmdargs{qpush}{\hgopt{qpush}{-m}}, each patch in the
|
bos@17
|
708 \sfilename{series} file is applied normally. If a patch applies with
|
bos@17
|
709 fuzz or rejects, MQ looks at the queue you \hgcmd{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@17
|
720 \hgcmdargs{qpop}{\hgopt{qpop}{-a} \hgopt{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@50
|
728 name \filename{foo.patch} to \hgcmd{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@50
|
737 printed in the output of \hgcmd{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@50
|
758 \item Need to see all of the patches since \texttt{foo.patch} that
|
bos@50
|
759 have touched files in a subdirectory of your tree?
|
bos@50
|
760 \begin{codesample4}
|
bos@50
|
761 hg log -r foo.patch:qtip \emph{subdir}
|
bos@50
|
762 \end{codesample4}
|
bos@50
|
763 \end{itemize}
|
bos@50
|
764
|
bos@50
|
765 Because MQ makes the names of patches available to the rest of
|
bos@50
|
766 Mercurial through its normal internal tag machinery, you don't need to
|
bos@50
|
767 type in the entire name of a patch when you want to identify it by
|
bos@50
|
768 name.
|
bos@50
|
769
|
bos@50
|
770 \begin{figure}[ht]
|
bos@50
|
771 \interaction{mq.id.out}
|
bos@50
|
772 \caption{Using MQ's tag features to work with patches}
|
bos@50
|
773 \label{ex:mq:id}
|
bos@50
|
774 \end{figure}
|
bos@50
|
775
|
bos@50
|
776 Another nice consequence of representing patch names as tags is that
|
bos@50
|
777 when you run the \hgcmd{log} command, it will display a patch's name
|
bos@50
|
778 as a tag, simply as part of its normal output. This makes it easy to
|
bos@50
|
779 visually distinguish applied patches from underlying ``normal''
|
bos@50
|
780 revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial
|
bos@50
|
781 commands in use with applied patches.
|
bos@50
|
782
|
bos@26
|
783 \section{Useful things to know about}
|
bos@26
|
784
|
bos@26
|
785 There are a number of aspects of MQ usage that don't fit tidily into
|
bos@26
|
786 sections of their own, but that are good to know. Here they are, in
|
bos@26
|
787 one place.
|
bos@26
|
788
|
bos@26
|
789 \begin{itemize}
|
bos@26
|
790 \item Normally, when you \hgcmd{qpop} a patch and \hgcmd{qpush} it
|
bos@26
|
791 again, the changeset that represents the patch after the pop/push
|
bos@26
|
792 will have a \emph{different identity} than the changeset that
|
bos@26
|
793 represented the hash beforehand. See section~\ref{sec:mq:cmd:qpush}
|
bos@26
|
794 for information as to why this is.
|
bos@26
|
795 \item It's not a good idea to \hgcmd{merge} changes from another
|
bos@26
|
796 branch with a patch changeset, at least if you want to maintain the
|
bos@26
|
797 ``patchiness'' of that changeset and changesets below it on the
|
bos@26
|
798 patch stack. If you try to do this, it will appear to succeed, but
|
bos@26
|
799 MQ will become confused.
|
bos@26
|
800 \end{itemize}
|
bos@50
|
801
|
bos@16
|
802 \section{Managing patches in a repository}
|
bos@16
|
803
|
bos@16
|
804 Because MQ's \sdirname{.hg/patches} directory resides outside a
|
bos@16
|
805 Mercurial repository's working directory, the ``underlying'' Mercurial
|
bos@16
|
806 repository knows nothing about the management or presence of patches.
|
bos@16
|
807
|
bos@16
|
808 This presents the interesting possibility of managing the contents of
|
bos@16
|
809 the patch directory as a Mercurial repository in its own right. This
|
bos@16
|
810 can be a useful way to work. For example, you can work on a patch for
|
bos@16
|
811 a while, \hgcmd{qrefresh} it, then \hgcmd{commit} the current state of
|
bos@16
|
812 the patch. This lets you ``roll back'' to that version of the patch
|
bos@16
|
813 later on.
|
bos@16
|
814
|
bos@26
|
815 You can then share different versions of the same patch stack among
|
bos@26
|
816 multiple underlying repositories. I use this when I am developing a
|
bos@26
|
817 Linux kernel feature. I have a pristine copy of my kernel sources for
|
bos@26
|
818 each of several CPU architectures, and a cloned repository under each
|
bos@26
|
819 that contains the patches I am working on. When I want to test a
|
bos@26
|
820 change on a different architecture, I push my current patches to the
|
bos@26
|
821 patch repository associated with that kernel tree, pop and push all of
|
bos@26
|
822 my patches, and build and test that kernel.
|
bos@16
|
823
|
bos@16
|
824 Managing patches in a repository makes it possible for multiple
|
bos@16
|
825 developers to work on the same patch series without colliding with
|
bos@16
|
826 each other, all on top of an underlying source base that they may or
|
bos@16
|
827 may not control.
|
bos@16
|
828
|
bos@17
|
829 \subsection{MQ support for patch repositories}
|
bos@16
|
830
|
bos@16
|
831 MQ helps you to work with the \sdirname{.hg/patches} directory as a
|
bos@16
|
832 repository; when you prepare a repository for working with patches
|
bos@17
|
833 using \hgcmd{qinit}, you can pass the \hgopt{qinit}{-c} option to
|
bos@16
|
834 create the \sdirname{.hg/patches} directory as a Mercurial repository.
|
bos@16
|
835
|
bos@16
|
836 \begin{note}
|
bos@16
|
837 If you forget to use the \hgopt{qinit}{-c} option, you can simply go
|
bos@16
|
838 into the \sdirname{.hg/patches} directory at any time and run
|
bos@16
|
839 \hgcmd{init}. Don't forget to add an entry for the
|
bos@17
|
840 \sfilename{status} file to the \sfilename{.hgignore} file, though
|
bos@17
|
841 (\hgcmdargs{qinit}{\hgopt{qinit}{-c}} does this for you
|
bos@17
|
842 automatically); you \emph{really} don't want to manage the
|
bos@17
|
843 \sfilename{status} file.
|
bos@16
|
844 \end{note}
|
bos@16
|
845
|
bos@16
|
846 As a convenience, if MQ notices that the \dirname{.hg/patches}
|
bos@16
|
847 directory is a repository, it will automatically \hgcmd{add} every
|
bos@16
|
848 patch that you create and import.
|
bos@16
|
849
|
bos@16
|
850 Finally, MQ provides a shortcut command, \hgcmd{qcommit}, that runs
|
bos@16
|
851 \hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves
|
bos@16
|
852 some cumbersome typing.
|
bos@16
|
853
|
bos@16
|
854 \subsection{A few things to watch out for}
|
bos@16
|
855
|
bos@16
|
856 MQ's support for working with a repository full of patches is limited
|
bos@16
|
857 in a few small respects.
|
bos@16
|
858
|
bos@16
|
859 MQ cannot automatically detect changes that you make to the patch
|
bos@16
|
860 directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update}
|
bos@16
|
861 changes to patches or the \sfilename{series} file, you will have to
|
bos@17
|
862 \hgcmdargs{qpop}{\hgopt{qpop}{-a}} and then
|
bos@17
|
863 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} in the underlying repository to
|
bos@17
|
864 see those changes show up there. If you forget to do this, you can
|
bos@17
|
865 confuse MQ's idea of which patches are applied.
|
bos@16
|
866
|
bos@26
|
867 \section{Third party tools for working with patches}
|
bos@19
|
868 \label{sec:mq:tools}
|
bos@16
|
869
|
bos@16
|
870 Once you've been working with patches for a while, you'll find
|
bos@16
|
871 yourself hungry for tools that will help you to understand and
|
bos@16
|
872 manipulate the patches you're dealing with.
|
bos@16
|
873
|
bos@16
|
874 The \command{diffstat} command~\cite{web:diffstat} generates a
|
bos@16
|
875 histogram of the modifications made to each file in a patch. It
|
bos@18
|
876 provides a good way to ``get a sense of'' a patch---which files it
|
bos@16
|
877 affects, and how much change it introduces to each file and as a
|
bos@16
|
878 whole. (I find that it's a good idea to use \command{diffstat}'s
|
bos@16
|
879 \texttt{-p} option as a matter of course, as otherwise it will try to
|
bos@16
|
880 do clever things with prefixes of file names that inevitably confuse
|
bos@16
|
881 at least me.)
|
bos@16
|
882
|
bos@19
|
883 \begin{figure}[ht]
|
bos@19
|
884 \interaction{mq.tools.tools}
|
bos@19
|
885 \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
|
bos@19
|
886 \label{ex:mq:tools}
|
bos@19
|
887 \end{figure}
|
bos@19
|
888
|
bos@16
|
889 The \package{patchutils} package~\cite{web:patchutils} is invaluable.
|
bos@16
|
890 It provides a set of small utilities that follow the ``Unix
|
bos@16
|
891 philosophy;'' each does one useful thing with a patch. The
|
bos@16
|
892 \package{patchutils} command I use most is \command{filterdiff}, which
|
bos@16
|
893 extracts subsets from a patch file. For example, given a patch that
|
bos@16
|
894 modifies hundreds of files across dozens of directories, a single
|
bos@16
|
895 invocation of \command{filterdiff} can generate a smaller patch that
|
bos@16
|
896 only touches files whose names match a particular glob pattern.
|
bos@16
|
897
|
bos@19
|
898 \section{Good ways to work with patches}
|
bos@19
|
899
|
bos@19
|
900 Whether you are working on a patch series to submit to a free software
|
bos@19
|
901 or open source project, or a series that you intend to treat as a
|
bos@19
|
902 sequence of regular changesets when you're done, you can use some
|
bos@19
|
903 simple techniques to keep your work well organised.
|
bos@19
|
904
|
bos@19
|
905 Give your patches descriptive names. A good name for a patch might be
|
bos@19
|
906 \filename{rework-device-alloc.patch}, because it will immediately give
|
bos@19
|
907 you a hint what the purpose of the patch is. Long names shouldn't be
|
bos@19
|
908 a problem; you won't be typing the names often, but you \emph{will} be
|
bos@19
|
909 running commands like \hgcmd{qapplied} and \hgcmd{qtop} over and over.
|
bos@19
|
910 Good naming becomes especially important when you have a number of
|
bos@19
|
911 patches to work with, or if you are juggling a number of different
|
bos@19
|
912 tasks and your patches only get a fraction of your attention.
|
bos@19
|
913
|
bos@19
|
914 Be aware of what patch you're working on. Use the \hgcmd{qtop}
|
bos@19
|
915 command and skim over the text of your patches frequently---for
|
bos@19
|
916 example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where
|
bos@19
|
917 you stand. I have several times worked on and \hgcmd{qrefresh}ed a
|
bos@19
|
918 patch other than the one I intended, and it's often tricky to migrate
|
bos@19
|
919 changes into the right patch after making them in the wrong one.
|
bos@19
|
920
|
bos@19
|
921 For this reason, it is very much worth investing a little time to
|
bos@19
|
922 learn how to use some of the third-party tools I described in
|
bos@19
|
923 section~\ref{sec:mq:tools}, particularly \command{diffstat} and
|
bos@19
|
924 \command{filterdiff}. The former will give you a quick idea of what
|
bos@19
|
925 changes your patch is making, while the latter makes it easy to splice
|
bos@19
|
926 hunks selectively out of one patch and into another.
|
bos@19
|
927
|
bos@19
|
928 \section{MQ cookbook}
|
bos@19
|
929
|
bos@19
|
930 \subsection{Manage ``trivial'' patches}
|
bos@19
|
931
|
bos@19
|
932 Because the overhead of dropping files into a new Mercurial repository
|
bos@19
|
933 is so low, it makes a lot of sense to manage patches this way even if
|
bos@19
|
934 you simply want to make a few changes to a source tarball that you
|
bos@19
|
935 downloaded.
|
bos@19
|
936
|
bos@19
|
937 Begin by downloading and unpacking the source tarball,
|
bos@19
|
938 and turning it into a Mercurial repository.
|
bos@19
|
939 \interaction{mq.tarball.download}
|
bos@19
|
940
|
bos@19
|
941 Continue by creating a patch stack and making your changes.
|
bos@19
|
942 \interaction{mq.tarball.qinit}
|
bos@19
|
943
|
bos@19
|
944 Let's say a few weeks or months pass, and your package author releases
|
bos@19
|
945 a new version. First, bring their changes into the repository.
|
bos@19
|
946 \interaction{mq.tarball.newsource}
|
bos@19
|
947 The pipeline starting with \hgcmd{locate} above deletes all files in
|
bos@19
|
948 the working directory, so that \hgcmd{commit}'s
|
bos@19
|
949 \hgopt{commit}{--addremove} option can actually tell which files have
|
bos@19
|
950 really been removed in the newer version of the source.
|
bos@19
|
951
|
bos@19
|
952 Finally, you can apply your patches on top of the new tree.
|
bos@19
|
953 \interaction{mq.tarball.repush}
|
bos@19
|
954
|
bos@19
|
955 \subsection{Combining entire patches}
|
bos@19
|
956 \label{sec:mq:combine}
|
bos@19
|
957
|
bos@55
|
958 MQ provides a command, \hgcmd{qfold} that lets you combine entire
|
bos@55
|
959 patches. This ``folds'' the patches you name, in the order you name
|
bos@55
|
960 them, into the topmost applied patch, and concatenates their
|
bos@55
|
961 descriptions onto the end of its description. The patches that you
|
bos@55
|
962 fold must be unapplied before you fold them.
|
bos@55
|
963
|
bos@55
|
964 The order in which you fold patches matters. If your topmost applied
|
bos@55
|
965 patch is \texttt{foo}, and you \hgcmd{qfold} \texttt{bar} and
|
bos@55
|
966 \texttt{quux} into it, you will end up with a patch that has the same
|
bos@55
|
967 effect as if you applied first \texttt{foo}, then \texttt{bar},
|
bos@55
|
968 followed by \texttt{quux}.
|
bos@19
|
969
|
bos@19
|
970 \subsection{Merging part of one patch into another}
|
bos@19
|
971
|
bos@19
|
972 Merging \emph{part} of one patch into another is more difficult than
|
bos@19
|
973 combining entire patches.
|
bos@19
|
974
|
bos@19
|
975 If you want to move changes to entire files, you can use
|
bos@19
|
976 \command{filterdiff}'s \cmdopt{filterdiff}{-i} and
|
bos@19
|
977 \cmdopt{filterdiff}{-x} options to choose the modifications to snip
|
bos@19
|
978 out of one patch, concatenating its output onto the end of the patch
|
bos@19
|
979 you want to merge into. You usually won't need to modify the patch
|
bos@19
|
980 you've merged the changes from. Instead, MQ will report some rejected
|
bos@19
|
981 hunks when you \hgcmd{qpush} it (from the hunks you moved into the
|
bos@19
|
982 other patch), and you can simply \hgcmd{qrefresh} the patch to drop
|
bos@19
|
983 the duplicate hunks.
|
bos@19
|
984
|
bos@19
|
985 If you have a patch that has multiple hunks modifying a file, and you
|
bos@19
|
986 only want to move a few of those hunks, the job becomes more messy,
|
bos@19
|
987 but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to
|
bos@19
|
988 print some metadata about the patch.
|
bos@19
|
989 \interaction{mq.tools.lsdiff}
|
bos@19
|
990
|
bos@19
|
991 This command prints three different kinds of number:
|
bos@19
|
992 \begin{itemize}
|
bos@26
|
993 \item (in the first column) a \emph{file number} to identify each file
|
bos@26
|
994 modified in the patch;
|
bos@26
|
995 \item (on the next line, indented) the line number within a modified
|
bos@26
|
996 file where a hunk starts; and
|
bos@26
|
997 \item (on the same line) a \emph{hunk number} to identify that hunk.
|
bos@19
|
998 \end{itemize}
|
bos@19
|
999
|
bos@19
|
1000 You'll have to use some visual inspection, and reading of the patch,
|
bos@19
|
1001 to identify the file and hunk numbers you'll want, but you can then
|
bos@19
|
1002 pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files}
|
bos@19
|
1003 and \cmdopt{filterdiff}{--hunks} options, to select exactly the file
|
bos@19
|
1004 and hunk you want to extract.
|
bos@19
|
1005
|
bos@19
|
1006 Once you have this hunk, you can concatenate it onto the end of your
|
bos@19
|
1007 destination patch and continue with the remainder of
|
bos@19
|
1008 section~\ref{sec:mq:combine}.
|
bos@26
|
1009
|
bos@26
|
1010 \section{Differences between quilt and MQ}
|
bos@26
|
1011
|
bos@26
|
1012 If you are already familiar with quilt, MQ provides a similar command
|
bos@26
|
1013 set. There are a few differences in the way that it works.
|
bos@26
|
1014
|
bos@26
|
1015 You will already have noticed that most quilt commands have MQ
|
bos@26
|
1016 counterparts that simply begin with a ``\texttt{q}''. The exceptions
|
bos@26
|
1017 are quilt's \texttt{add} and \texttt{remove} commands, the
|
bos@26
|
1018 counterparts for which are the normal Mercurial \hgcmd{add} and
|
bos@26
|
1019 \hgcmd{remove} commands. There is no MQ equivalent of the quilt
|
bos@26
|
1020 \texttt{edit} command.
|
bos@50
|
1021
|
bos@25
|
1022 \section{MQ command reference}
|
bos@25
|
1023 \label{sec:mq:cmdref}
|
bos@25
|
1024
|
bos@25
|
1025 For an overview of the commands provided by MQ, use the command
|
bos@25
|
1026 \hgcmdargs{help}{mq}.
|
bos@25
|
1027
|
bos@25
|
1028 \subsection{\hgcmd{qapplied}---print applied patches}
|
bos@25
|
1029
|
bos@25
|
1030 The \hgcmd{qapplied} command prints the current stack of applied
|
bos@25
|
1031 patches. Patches are printed in oldest-to-newest order, so the last
|
bos@25
|
1032 patch in the list is the ``top'' patch.
|
bos@25
|
1033
|
bos@25
|
1034 \subsection{\hgcmd{qcommit}---commit changes in the queue repository}
|
bos@25
|
1035
|
bos@25
|
1036 The \hgcmd{qcommit} command commits any outstanding changes in the
|
bos@25
|
1037 \sdirname{.hg/patches} repository. This command only works if the
|
bos@25
|
1038 \sdirname{.hg/patches} directory is a repository, i.e.~you created the
|
bos@25
|
1039 directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran
|
bos@25
|
1040 \hgcmd{init} in the directory after running \hgcmd{qinit}.
|
bos@25
|
1041
|
bos@25
|
1042 This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
|
bos@25
|
1043
|
bos@25
|
1044 \subsection{\hgcmd{qdelete}---delete a patch from the
|
bos@25
|
1045 \sfilename{series} file}
|
bos@25
|
1046
|
bos@25
|
1047 The \hgcmd{qdelete} command removes the entry for a patch from the
|
bos@25
|
1048 \sfilename{series} file in the \sdirname{.hg/patches} directory. It
|
bos@53
|
1049 does not pop the patch if the patch is already applied. By default,
|
bos@53
|
1050 it does not delete the patch file; use the \hgopt{qdel}{-f} option to
|
bos@53
|
1051 do that.
|
bos@53
|
1052
|
bos@53
|
1053 Options:
|
bos@53
|
1054 \begin{itemize}
|
bos@53
|
1055 \item[\hgopt{qdel}{-f}] Delete the patch file.
|
bos@53
|
1056 \end{itemize}
|
bos@25
|
1057
|
bos@25
|
1058 \subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch}
|
bos@25
|
1059
|
bos@25
|
1060 The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
|
bos@25
|
1061 It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
|
bos@25
|
1062
|
bos@55
|
1063 \subsection{\hgcmd{qfold}---merge (``fold'') several patches into one}
|
bos@55
|
1064
|
bos@55
|
1065 The \hgcmd{qfold} command merges multiple patches into the topmost
|
bos@55
|
1066 applied patch, so that the topmost applied patch makes the union of
|
bos@55
|
1067 all of the changes in the patches in question.
|
bos@55
|
1068
|
bos@55
|
1069 The patches to fold must not be applied; \hgcmd{qfold} will exit with
|
bos@55
|
1070 an error if any is. The order in which patches are folded is
|
bos@55
|
1071 significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
|
bos@55
|
1072 patch, followed by \texttt{a}, followed by \texttt{b}''.
|
bos@55
|
1073
|
bos@55
|
1074 The comments from the folded patches are appended to the comments of
|
bos@55
|
1075 the destination patch, with each block of comments separated by three
|
bos@55
|
1076 asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e}
|
bos@55
|
1077 option to edit the commit message for the combined patch/changeset
|
bos@55
|
1078 after the folding has completed.
|
bos@55
|
1079
|
bos@55
|
1080 Options:
|
bos@55
|
1081 \begin{itemize}
|
bos@55
|
1082 \item[\hgopt{qfold}{-e}] Edit the commit message and patch description
|
bos@55
|
1083 for the newly folded patch.
|
bos@55
|
1084 \item[\hgopt{qfold}{-l}] Use the contents of the given file as the new
|
bos@55
|
1085 commit message and patch description for the folded patch.
|
bos@55
|
1086 \item[\hgopt{qfold}{-m}] Use the given text as the new commit message
|
bos@55
|
1087 and patch description for the folded patch.
|
bos@55
|
1088 \end{itemize}
|
bos@55
|
1089
|
bos@53
|
1090 \subsection{\hgcmd{qheader}---display the header/description of a patch}
|
bos@53
|
1091
|
bos@53
|
1092 The \hgcmd{qheader} command prints the header, or description, of a
|
bos@53
|
1093 patch. By default, it prints the header of the topmost applied patch.
|
bos@53
|
1094 Given an argument, it prints the header of the named patch.
|
bos@53
|
1095
|
bos@25
|
1096 \subsection{\hgcmd{qimport}---import a third-party patch into the queue}
|
bos@25
|
1097
|
bos@25
|
1098 The \hgcmd{qimport} command adds an entry for an external patch to the
|
bos@25
|
1099 \sfilename{series} file, and copies the patch into the
|
bos@25
|
1100 \sdirname{.hg/patches} directory. It adds the entry immediately after
|
bos@25
|
1101 the topmost applied patch, but does not push the patch.
|
bos@25
|
1102
|
bos@25
|
1103 If the \sdirname{.hg/patches} directory is a repository,
|
bos@25
|
1104 \hgcmd{qimport} automatically does an \hgcmd{add} of the imported
|
bos@25
|
1105 patch.
|
bos@25
|
1106
|
bos@25
|
1107 \subsection{\hgcmd{qinit}---prepare a repository to work with MQ}
|
bos@25
|
1108
|
bos@25
|
1109 The \hgcmd{qinit} command prepares a repository to work with MQ. It
|
bos@25
|
1110 creates a directory called \sdirname{.hg/patches}.
|
bos@25
|
1111
|
bos@25
|
1112 Options:
|
bos@25
|
1113 \begin{itemize}
|
bos@25
|
1114 \item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
|
bos@25
|
1115 in its own right. Also creates a \sfilename{.hgignore} file that
|
bos@25
|
1116 will ignore the \sfilename{status} file.
|
bos@25
|
1117 \end{itemize}
|
bos@25
|
1118
|
bos@25
|
1119 When the \sdirname{.hg/patches} directory is a repository, the
|
bos@25
|
1120 \hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add}
|
bos@25
|
1121 new patches.
|
bos@25
|
1122
|
bos@25
|
1123 \subsection{\hgcmd{qnew}---create a new patch}
|
bos@25
|
1124
|
bos@25
|
1125 The \hgcmd{qnew} command creates a new patch. It takes one mandatory
|
bos@25
|
1126 argument, the name to use for the patch file. The newly created patch
|
bos@25
|
1127 is created empty by default. It is added to the \sfilename{series}
|
bos@25
|
1128 file after the current topmost applied patch, and is immediately
|
bos@25
|
1129 pushed on top of that patch.
|
bos@25
|
1130
|
bos@25
|
1131 If \hgcmd{qnew} finds modified files in the working directory, it will
|
bos@25
|
1132 refuse to create a new patch unless the \hgopt{qnew}{-f} option is
|
bos@25
|
1133 used (see below). This behaviour allows you to \hgcmd{qrefresh} your
|
bos@25
|
1134 topmost applied patch before you apply a new patch on top of it.
|
bos@25
|
1135
|
bos@25
|
1136 Options:
|
bos@25
|
1137 \begin{itemize}
|
bos@25
|
1138 \item[\hgopt{qnew}{-f}] Create a new patch if the contents of the
|
bos@25
|
1139 working directory are modified. Any outstanding modifications are
|
bos@25
|
1140 added to the newly created patch, so after this command completes,
|
bos@25
|
1141 the working directory will no longer be modified.
|
bos@25
|
1142 \item[\hgopt{qnew}{-m}] Use the given text as the commit message.
|
bos@25
|
1143 This text will be stored at the beginning of the patch file, before
|
bos@25
|
1144 the patch data.
|
bos@25
|
1145 \end{itemize}
|
bos@25
|
1146
|
bos@25
|
1147 \subsection{\hgcmd{qnext}---print the name of the next patch}
|
bos@25
|
1148
|
bos@25
|
1149 The \hgcmd{qnext} command prints the name name of the next patch in
|
bos@25
|
1150 the \sfilename{series} file after the topmost applied patch. This
|
bos@25
|
1151 patch will become the topmost applied patch if you run \hgcmd{qpush}.
|
bos@25
|
1152
|
bos@25
|
1153 \subsection{\hgcmd{qpop}---pop patches off the stack}
|
bos@25
|
1154
|
bos@25
|
1155 The \hgcmd{qpop} command removes applied patches from the top of the
|
bos@25
|
1156 stack of applied patches. By default, it removes only one patch.
|
bos@25
|
1157
|
bos@25
|
1158 This command removes the changesets that represent the popped patches
|
bos@25
|
1159 from the repository, and updates the working directory to undo the
|
bos@25
|
1160 effects of the patches.
|
bos@25
|
1161
|
bos@25
|
1162 This command takes an optional argument, which it uses as the name or
|
bos@25
|
1163 index of the patch to pop to. If given a name, it will pop patches
|
bos@50
|
1164 until the named patch is the topmost applied patch. If given a
|
bos@50
|
1165 number, \hgcmd{qpop} treats the number as an index into the entries in
|
bos@50
|
1166 the series file, counting from zero (empty lines and lines containing
|
bos@50
|
1167 only comments do not count). It pops patches until the patch
|
bos@50
|
1168 identified by the given index is the topmost applied patch.
|
bos@25
|
1169
|
bos@25
|
1170 The \hgcmd{qpop} command does not read or write patches or the
|
bos@25
|
1171 \sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that
|
bos@25
|
1172 you have removed from the \sfilename{series} file, or a patch that you
|
bos@25
|
1173 have renamed or deleted entirely. In the latter two cases, use the
|
bos@25
|
1174 name of the patch as it was when you applied it.
|
bos@25
|
1175
|
bos@25
|
1176 By default, the \hgcmd{qpop} command will not pop any patches if the
|
bos@25
|
1177 working directory has been modified. You can override this behaviour
|
bos@25
|
1178 using the \hgopt{qpop}{-f} option, which reverts all modifications in
|
bos@25
|
1179 the working directory.
|
bos@25
|
1180
|
bos@25
|
1181 Options:
|
bos@25
|
1182 \begin{itemize}
|
bos@25
|
1183 \item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the
|
bos@25
|
1184 repository to its state before you applied any patches.
|
bos@25
|
1185 \item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the
|
bos@25
|
1186 working directory when popping.
|
bos@25
|
1187 \item[\hgopt{qpop}{-n}] Pop a patch from the named queue.
|
bos@25
|
1188 \end{itemize}
|
bos@25
|
1189
|
bos@25
|
1190 The \hgcmd{qpop} command removes one line from the end of the
|
bos@25
|
1191 \sfilename{status} file for each patch that it pops.
|
bos@50
|
1192
|
bos@25
|
1193 \subsection{\hgcmd{qprev}---print the name of the previous patch}
|
bos@25
|
1194
|
bos@25
|
1195 The \hgcmd{qprev} command prints the name of the patch in the
|
bos@25
|
1196 \sfilename{series} file that comes before the topmost applied patch.
|
bos@25
|
1197 This will become the topmost applied patch if you run \hgcmd{qpop}.
|
bos@25
|
1198
|
bos@25
|
1199 \subsection{\hgcmd{qpush}---push patches onto the stack}
|
bos@26
|
1200 \label{sec:mq:cmd:qpush}
|
bos@25
|
1201
|
bos@25
|
1202 The \hgcmd{qpush} command adds patches onto the applied stack. By
|
bos@25
|
1203 default, it adds only one patch.
|
bos@25
|
1204
|
bos@25
|
1205 This command creates a new changeset to represent each applied patch,
|
bos@25
|
1206 and updates the working directory to apply the effects of the patches.
|
bos@25
|
1207
|
bos@26
|
1208 The default data used when creating a changeset are as follows:
|
bos@25
|
1209 \begin{itemize}
|
bos@25
|
1210 \item The commit date and time zone are the current date and time
|
bos@25
|
1211 zone. Because these data are used to compute the identity of a
|
bos@25
|
1212 changeset, this means that if you \hgcmd{qpop} a patch and
|
bos@25
|
1213 \hgcmd{qpush} it again, the changeset that you push will have a
|
bos@25
|
1214 different identity than the changeset you popped.
|
bos@25
|
1215 \item The author is the same as the default used by the \hgcmd{commit}
|
bos@25
|
1216 command.
|
bos@25
|
1217 \item The commit message is any text from the patch file that comes
|
bos@25
|
1218 before the first diff header. If there is no such text, a default
|
bos@25
|
1219 commit message is used that identifies the name of the patch.
|
bos@25
|
1220 \end{itemize}
|
bos@26
|
1221 If a patch contains a Mercurial patch header (XXX add link), the
|
bos@26
|
1222 information in the patch header overrides these defaults.
|
bos@25
|
1223
|
bos@25
|
1224 Options:
|
bos@25
|
1225 \begin{itemize}
|
bos@25
|
1226 \item[\hgopt{qpush}{-a}] Push all unapplied patches from the
|
bos@25
|
1227 \sfilename{series} file until there are none left to push.
|
bos@25
|
1228 \item[\hgopt{qpush}{-l}] Add the name of the patch to the end
|
bos@25
|
1229 of the commit message.
|
bos@25
|
1230 \item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the
|
bos@25
|
1231 entry for the patch in another saved queue to compute the parameters
|
bos@25
|
1232 for a three-way merge, and perform a three-way merge using the
|
bos@25
|
1233 normal Mercurial merge machinery. Use the resolution of the merge
|
bos@25
|
1234 as the new patch content.
|
bos@25
|
1235 \item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing.
|
bos@25
|
1236 \end{itemize}
|
bos@25
|
1237
|
bos@25
|
1238 The \hgcmd{qpush} command reads, but does not modify, the
|
bos@25
|
1239 \sfilename{series} file. It appends one line to the \hgcmd{status}
|
bos@25
|
1240 file for each patch that it pushes.
|
bos@25
|
1241
|
bos@25
|
1242 \subsection{\hgcmd{qrefresh}---update the topmost applied patch}
|
bos@25
|
1243
|
bos@25
|
1244 The \hgcmd{qrefresh} command updates the topmost applied patch. It
|
bos@25
|
1245 modifies the patch, removes the old changeset that represented the
|
bos@25
|
1246 patch, and creates a new changeset to represent the modified patch.
|
bos@25
|
1247
|
bos@25
|
1248 The \hgcmd{qrefresh} command looks for the following modifications:
|
bos@25
|
1249 \begin{itemize}
|
bos@25
|
1250 \item Changes to the commit message, i.e.~the text before the first
|
bos@25
|
1251 diff header in the patch file, are reflected in the new changeset
|
bos@25
|
1252 that represents the patch.
|
bos@25
|
1253 \item Modifications to tracked files in the working directory are
|
bos@25
|
1254 added to the patch.
|
bos@25
|
1255 \item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
|
bos@25
|
1256 \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename
|
bos@25
|
1257 destinations are added to the patch, while removed files and rename
|
bos@25
|
1258 sources are removed.
|
bos@25
|
1259 \end{itemize}
|
bos@25
|
1260
|
bos@25
|
1261 Even if \hgcmd{qrefresh} detects no changes, it still recreates the
|
bos@25
|
1262 changeset that represents the patch. This causes the identity of the
|
bos@25
|
1263 changeset to differ from the previous changeset that identified the
|
bos@25
|
1264 patch.
|
bos@25
|
1265
|
bos@53
|
1266 Options:
|
bos@53
|
1267 \begin{itemize}
|
bos@53
|
1268 \item[\hgopt{qrefresh}{-e}] Modify the commit and patch description,
|
bos@53
|
1269 using the preferred text editor.
|
bos@53
|
1270 \item[\hgopt{qrefresh}{-m}] Modify the commit message and patch
|
bos@53
|
1271 description, using the given text.
|
bos@53
|
1272 \item[\hgopt{qrefresh}{-l}] Modify the commit message and patch
|
bos@53
|
1273 description, using text from the given file.
|
bos@53
|
1274 \end{itemize}
|
bos@53
|
1275
|
bos@53
|
1276 \subsection{\hgcmd{qrename}---rename a patch}
|
bos@53
|
1277
|
bos@53
|
1278 The \hgcmd{qrename} command renames a patch, and changes the entry for
|
bos@53
|
1279 the patch in the \sfilename{series} file.
|
bos@53
|
1280
|
bos@53
|
1281 With a single argument, \hgcmd{qrename} renames the topmost applied
|
bos@53
|
1282 patch. With two arguments, it renames its first argument to its
|
bos@53
|
1283 second.
|
bos@53
|
1284
|
bos@26
|
1285 \subsection{\hgcmd{qrestore}---restore saved queue state}
|
bos@26
|
1286
|
bos@26
|
1287 XXX No idea what this does.
|
bos@26
|
1288
|
bos@26
|
1289 \subsection{\hgcmd{qsave}---save current queue state}
|
bos@26
|
1290
|
bos@26
|
1291 XXX Likewise.
|
bos@26
|
1292
|
bos@26
|
1293 \subsection{\hgcmd{qseries}---print the entire patch series}
|
bos@26
|
1294
|
bos@26
|
1295 The \hgcmd{qseries} command prints the entire patch series from the
|
bos@26
|
1296 \sfilename{series} file. It prints only patch names, not empty lines
|
bos@26
|
1297 or comments. It prints in order from first to be applied to last.
|
bos@26
|
1298
|
bos@26
|
1299 \subsection{\hgcmd{qtop}---print the name of the current patch}
|
bos@26
|
1300
|
bos@26
|
1301 The \hgcmd{qtop} prints the name of the topmost currently applied
|
bos@26
|
1302 patch.
|
bos@26
|
1303
|
bos@26
|
1304 \subsection{\hgcmd{qunapplied}---print patches not yet applied}
|
bos@26
|
1305
|
bos@26
|
1306 The \hgcmd{qunapplied} command prints the names of patches from the
|
bos@26
|
1307 \sfilename{series} file that are not yet applied. It prints them in
|
bos@26
|
1308 order from the next patch that will be pushed to the last.
|
bos@26
|
1309
|
bos@26
|
1310 \subsection{\hgcmd{qversion}}
|
bos@26
|
1311
|
bos@26
|
1312 The \hgcmd{qversion} command prints the version of MQ that is in use.
|
bos@26
|
1313
|
bos@26
|
1314 \subsection{\hgcmd{strip}---remove a revision and descendants}
|
bos@26
|
1315
|
bos@26
|
1316 The \hgcmd{strip} command removes a revision, and all of its
|
bos@26
|
1317 descendants, from the repository. It undoes the effects of the
|
bos@26
|
1318 removed revisions from the repository, and updates the working
|
bos@26
|
1319 directory to the first parent of the removed revision.
|
bos@26
|
1320
|
bos@26
|
1321 The \hgcmd{strip} command saves a backup of the removed changesets in
|
bos@26
|
1322 a bundle, so that they can be reapplied if removed in error.
|
bos@26
|
1323
|
bos@26
|
1324 Options:
|
bos@26
|
1325 \begin{itemize}
|
bos@26
|
1326 \item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
|
bos@26
|
1327 with the stripped changesets in the backup bundle.
|
bos@26
|
1328 \item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
|
bos@26
|
1329 heads. XXX This should be renamed, and use \texttt{-f} to strip revs
|
bos@26
|
1330 when there are pending changes.
|
bos@26
|
1331 \item[\hgopt{strip}{-n}] Do not save a backup bundle.
|
bos@26
|
1332 \end{itemize}
|
bos@53
|
1333
|
bos@25
|
1334 \section{MQ file reference}
|
bos@25
|
1335
|
bos@25
|
1336 \subsection{The \sfilename{series} file}
|
bos@25
|
1337
|
bos@26
|
1338 The \sfilename{series} file contains a list of the names of all
|
bos@26
|
1339 patches that MQ can apply. It is represented as a list of names, with
|
bos@26
|
1340 one name saved per line. Leading and trailing white space in each
|
bos@26
|
1341 line are ignored.
|
bos@26
|
1342
|
bos@26
|
1343 Lines may contain comments. A comment begins with the ``\texttt{\#}''
|
bos@26
|
1344 character, and extends to the end of the line. Empty lines, and lines
|
bos@26
|
1345 that contain only comments, are ignored.
|
bos@26
|
1346
|
bos@26
|
1347 You will often need to edit the \sfilename{series} file by hand, hence
|
bos@26
|
1348 the support for comments and empty lines noted above. For example,
|
bos@26
|
1349 you can comment out a patch temporarily, and \hgcmd{qpush} will skip
|
bos@26
|
1350 over that patch when applying patches. You can also change the order
|
bos@26
|
1351 in which patches are applied by reordering their entries in the
|
bos@26
|
1352 \sfilename{series} file.
|
bos@26
|
1353
|
bos@26
|
1354 Placing the \sfilename{series} file under revision control is also
|
bos@26
|
1355 supported; it is a good idea to place all of the patches that it
|
bos@26
|
1356 refers to under revision control, as well. If you create a patch
|
bos@26
|
1357 directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this
|
bos@26
|
1358 will be done for you automatically.
|
bos@53
|
1359
|
bos@25
|
1360 \subsection{The \sfilename{status} file}
|
bos@25
|
1361
|
bos@26
|
1362 The \sfilename{status} file contains the names and changeset hashes of
|
bos@26
|
1363 all patches that MQ currently has applied. Unlike the
|
bos@26
|
1364 \sfilename{series} file, this file is not intended for editing. You
|
bos@26
|
1365 should not place this file under revision control, or modify it in any
|
bos@26
|
1366 way. It is used by MQ strictly for internal book-keeping.
|
bos@19
|
1367
|
bos@1
|
1368 %%% Local Variables:
|
bos@1
|
1369 %%% mode: latex
|
bos@1
|
1370 %%% TeX-master: "00book"
|
bos@1
|
1371 %%% End:
|