| 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@2
|
129 \section{Getting started with Mercurial Queues}
|
|
bos@2
|
130 \label{sec:mq:start}
|
|
bos@1
|
131
|
|
bos@3
|
132 Because MQ is implemented as an extension, you must explicitly enable
|
|
bos@3
|
133 before you can use it. (You don't need to download anything; MQ ships
|
|
bos@3
|
134 with the standard Mercurial distribution.) To enable MQ, edit your
|
|
bos@4
|
135 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.
|
|
bos@2
|
136
|
|
bos@12
|
137 \begin{figure}[ht]
|
|
bos@4
|
138 \begin{codesample4}
|
|
bos@4
|
139 [extensions]
|
|
bos@4
|
140 hgext.mq =
|
|
bos@4
|
141 \end{codesample4}
|
|
bos@4
|
142 \label{ex:mq:config}
|
|
bos@4
|
143 \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
|
|
bos@4
|
144 \end{figure}
|
|
bos@3
|
145
|
|
bos@3
|
146 Once the extension is enabled, it will make a number of new commands
|
|
bos@7
|
147 available. To verify that the extension is working, you can use
|
|
bos@7
|
148 \hgcmd{help} to see if the \hgcmd{qinit} command is now available; see
|
|
bos@7
|
149 the example in figure~\ref{ex:mq:enabled}.
|
|
bos@3
|
150
|
|
bos@12
|
151 \begin{figure}[ht]
|
|
bos@4
|
152 \interaction{mq.qinit-help.help}
|
|
bos@4
|
153 \caption{How to verify that MQ is enabled}
|
|
bos@4
|
154 \label{ex:mq:enabled}
|
|
bos@4
|
155 \end{figure}
|
|
bos@1
|
156
|
|
bos@8
|
157 You can use MQ with \emph{any} Mercurial repository, and its commands
|
|
bos@8
|
158 only operate within that repository. To get started, simply prepare
|
|
bos@8
|
159 the repository using the \hgcmd{qinit} command (see
|
|
bos@7
|
160 figure~\ref{ex:mq:qinit}). This command creates an empty directory
|
|
bos@7
|
161 called \filename{.hg/patches}, where MQ will keep its metadata. As
|
|
bos@7
|
162 with many Mercurial commands, the \hgcmd{qinit} command prints nothing
|
|
bos@7
|
163 if it succeeds.
|
|
bos@7
|
164
|
|
bos@12
|
165 \begin{figure}[ht]
|
|
bos@7
|
166 \interaction{mq.tutorial.qinit}
|
|
bos@7
|
167 \caption{Preparing a repository for use with MQ}
|
|
bos@7
|
168 \label{ex:mq:qinit}
|
|
bos@7
|
169 \end{figure}
|
|
bos@7
|
170
|
|
bos@12
|
171 \begin{figure}[ht]
|
|
bos@7
|
172 \interaction{mq.tutorial.qnew}
|
|
bos@7
|
173 \caption{Creating a new patch}
|
|
bos@7
|
174 \label{ex:mq:qnew}
|
|
bos@7
|
175 \end{figure}
|
|
bos@7
|
176
|
|
bos@8
|
177 \subsection{Creating a new patch}
|
|
bos@8
|
178
|
|
bos@8
|
179 To begin work on a new patch, use the \hgcmd{qnew} command. This
|
|
bos@7
|
180 command takes one argument, the name of the patch to create. MQ will
|
|
bos@7
|
181 use this as the name of an actual file in the \filename{.hg/patches}
|
|
bos@7
|
182 directory, as you can see in figure~\ref{ex:mq:qnew}.
|
|
bos@7
|
183
|
|
bos@8
|
184 Also newly present in the \filename{.hg/patches} directory are two
|
|
bos@8
|
185 other files, \filename{series} and \filename{status}. The
|
|
bos@8
|
186 \filename{series} file lists all of the patches that MQ knows about
|
|
bos@8
|
187 for this repository, with one patch per line. Mercurial uses the
|
|
bos@8
|
188 \filename{status} file for internal book-keeping; it tracks all of the
|
|
bos@7
|
189 patches that MQ has \emph{applied} in this repository.
|
|
bos@7
|
190
|
|
bos@7
|
191 \begin{note}
|
|
bos@7
|
192 You may sometimes want to edit the \filename{series} file by hand;
|
|
bos@7
|
193 for example, to change the sequence in which some patches are
|
|
bos@7
|
194 applied. However, manually editing the \filename{status} file is
|
|
bos@7
|
195 almost always a bad idea, as it's easy to corrupt MQ's idea of what
|
|
bos@7
|
196 is happening.
|
|
bos@7
|
197 \end{note}
|
|
bos@7
|
198
|
|
bos@8
|
199 Once you have created your new patch, you can edit files in the
|
|
bos@8
|
200 working directory as you usually would. All of the normal Mercurial
|
|
bos@8
|
201 commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
|
|
bos@8
|
202 they did before.
|
|
bos@8
|
203 \subsection{Refreshing a patch}
|
|
bos@8
|
204
|
|
bos@8
|
205 When you reach a point where you want to save your work, use the
|
|
bos@8
|
206 \hgcmd{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
|
|
bos@8
|
207 you are working on. This command folds the changes you have made in
|
|
bos@8
|
208 the working directory into your patch, and updates its corresponding
|
|
bos@8
|
209 changeset to contain those changes.
|
|
bos@8
|
210
|
|
bos@12
|
211 \begin{figure}[ht]
|
|
bos@8
|
212 \interaction{mq.tutorial.qrefresh}
|
|
bos@8
|
213 \caption{Refreshing a patch}
|
|
bos@8
|
214 \label{ex:mq:qrefresh}
|
|
bos@8
|
215 \end{figure}
|
|
bos@8
|
216
|
|
bos@8
|
217 You can run \hgcmd{qrefresh} as often as you like, so it's a good way
|
|
bos@13
|
218 to ``checkpoint'' your work. Refresh your patch at an opportune
|
|
bos@8
|
219 time; try an experiment; and if the experiment doesn't work out,
|
|
bos@8
|
220 \hgcmd{revert} your modifications back to the last time you refreshed.
|
|
bos@8
|
221
|
|
bos@12
|
222 \begin{figure}[ht]
|
|
bos@8
|
223 \interaction{mq.tutorial.qrefresh2}
|
|
bos@8
|
224 \caption{Refresh a patch many times to accumulate changes}
|
|
bos@8
|
225 \label{ex:mq:qrefresh2}
|
|
bos@8
|
226 \end{figure}
|
|
bos@8
|
227
|
|
bos@8
|
228 \subsection{Stacking and tracking patches}
|
|
bos@8
|
229
|
|
bos@8
|
230 Once you have finished working on a patch, or need to work on another,
|
|
bos@8
|
231 you can use the \hgcmd{qnew} command again to create a new patch.
|
|
bos@8
|
232 Mercurial will apply this patch on top of your existing patch. See
|
|
bos@8
|
233 figure~\ref{ex:mq:qnew2} for an example. Notice that the patch
|
|
bos@8
|
234 contains the changes in our prior patch as part of its context (you
|
|
bos@8
|
235 can see this more clearly in the output of \hgcmd{annotate}).
|
|
bos@8
|
236
|
|
bos@12
|
237 \begin{figure}[ht]
|
|
bos@8
|
238 \interaction{mq.tutorial.qnew2}
|
|
bos@8
|
239 \caption{Stacking a second patch on top of the first}
|
|
bos@8
|
240 \label{ex:mq:qnew2}
|
|
bos@8
|
241 \end{figure}
|
|
bos@8
|
242
|
|
bos@8
|
243 So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've
|
|
bos@8
|
244 been careful to only use regular Mercurial commands. However, there
|
|
bos@8
|
245 are more ``natural'' commands you can use when thinking about patches
|
|
bos@8
|
246 with MQ, as illustrated in figure~\ref{ex:mq:qseries}:
|
|
bos@8
|
247
|
|
bos@8
|
248 \begin{itemize}
|
|
bos@8
|
249 \item The \hgcmd{qseries} command lists every patch that MQ knows
|
|
bos@8
|
250 about in this repository, from oldest to newest (most recently
|
|
bos@8
|
251 \emph{created}).
|
|
bos@8
|
252 \item The \hgcmd{qapplied} command lists every patch that MQ has
|
|
bos@8
|
253 \emph{applied} in this repository, again from oldest to newest (most
|
|
bos@8
|
254 recently applied).
|
|
bos@8
|
255 \end{itemize}
|
|
bos@8
|
256
|
|
bos@12
|
257 \begin{figure}[ht]
|
|
bos@8
|
258 \interaction{mq.tutorial.qseries}
|
|
bos@8
|
259 \caption{Understanding the patch stack with \hgcmd{qseries} and
|
|
bos@8
|
260 \hgcmd{qapplied}}
|
|
bos@8
|
261 \label{ex:mq:qseries}
|
|
bos@8
|
262 \end{figure}
|
|
bos@8
|
263
|
|
bos@8
|
264 \subsection{Manipulating the patch stack}
|
|
bos@8
|
265
|
|
bos@8
|
266 The previous discussion implied that there must be a difference
|
|
bos@11
|
267 between ``known'' and ``applied'' patches, and there is. MQ can
|
|
bos@11
|
268 manage a patch without it being applied in the repository.
|
|
bos@8
|
269
|
|
bos@8
|
270 An \emph{applied} patch has a corresponding changeset in the
|
|
bos@8
|
271 repository, and the effects of the patch and changeset are visible in
|
|
bos@8
|
272 the working directory. You can undo the application of a patch using
|
|
bos@12
|
273 the \hgcmd{qpop} command. MQ still \emph{knows about}, or manages, a
|
|
bos@12
|
274 popped patch, but the patch no longer has a corresponding changeset in
|
|
bos@12
|
275 the repository, and the working directory does not contain the changes
|
|
bos@12
|
276 made by the patch. Figure~\ref{fig:mq:stack} illustrates the
|
|
bos@12
|
277 difference between applied and tracked patches.
|
|
bos@12
|
278
|
|
bos@12
|
279 \begin{figure}[ht]
|
|
bos@12
|
280 \centering
|
|
bos@12
|
281 \grafix{mq-stack}
|
|
bos@12
|
282 \caption{Applied and unapplied patches in the MQ patch stack}
|
|
bos@12
|
283 \label{fig:mq:stack}
|
|
bos@8
|
284 \end{figure}
|
|
bos@8
|
285
|
|
bos@8
|
286 You can reapply an unapplied, or popped, patch using the \hgcmd{qpush}
|
|
bos@8
|
287 command. This creates a new changeset to correspond to the patch, and
|
|
bos@8
|
288 the patch's changes once again become present in the working
|
|
bos@8
|
289 directory. See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop}
|
|
bos@8
|
290 and \hgcmd{qpush} in action. Notice that once we have popped a patch
|
|
bos@8
|
291 or two patches, the output of \hgcmd{qseries} remains the same, while
|
|
bos@8
|
292 that of \hgcmd{qapplied} has changed.
|
|
bos@8
|
293
|
|
bos@12
|
294 \begin{figure}[ht]
|
|
bos@12
|
295 \interaction{mq.tutorial.qpop}
|
|
bos@12
|
296 \caption{Modifying the stack of applied patches}
|
|
bos@12
|
297 \label{ex:mq:qpop}
|
|
bos@11
|
298 \end{figure}
|
|
bos@11
|
299
|
|
bos@8
|
300 MQ does not limit you to pushing or popping one patch. You can have
|
|
bos@8
|
301 no patches, all of them, or any number in between applied at some
|
|
bos@8
|
302 point in time.
|
|
bos@8
|
303
|
|
bos@13
|
304 \subsection{Working on several patches at once}
|
|
bos@13
|
305
|
|
bos@13
|
306 The \hgcmd{qrefresh} command always refreshes the \emph{topmost}
|
|
bos@13
|
307 applied patch. This means that you can suspend work on one patch (by
|
|
bos@13
|
308 refreshing it), pop or push to make a different patch the top, and
|
|
bos@13
|
309 work on \emph{that} patch for a while.
|
|
bos@13
|
310
|
|
bos@13
|
311 Here's an example that illustrates how you can use this ability.
|
|
bos@13
|
312 Let's say you're developing a new feature as two patches. The first
|
|
bos@13
|
313 is a change to the core of your software, and the second--layered on
|
|
bos@13
|
314 top of the first--changes the user interface to use the code you just
|
|
bos@13
|
315 added to the core. If you notice a bug in the core while you're
|
|
bos@13
|
316 working on the UI patch, it's easy to fix the core. Simply
|
|
bos@13
|
317 \hgcmd{qrefresh} the UI patch to save your in-progress changes, and
|
|
bos@13
|
318 \hgcmd{qpop} down to the core patch. Fix the core bug,
|
|
bos@13
|
319 \hgcmd{qrefresh} the core patch, and \hgcmd{qpush} back to the UI
|
|
bos@13
|
320 patch to continue where you left off.
|
|
bos@13
|
321
|
|
bos@14
|
322 \section{Mercurial Queues and GNU patch}
|
|
bos@15
|
323 \label{sec:mq:patch}
|
|
bos@14
|
324
|
|
bos@14
|
325 MQ uses the GNU \command{patch} command to apply patches. It will
|
|
bos@14
|
326 help you to understand the data that MQ and \command{patch} work with,
|
|
bos@14
|
327 and a few aspects of how \command{patch} operates.
|
|
bos@14
|
328
|
|
bos@15
|
329 The \command{diff} command generates a list of modifications by
|
|
bos@15
|
330 comparing two files. The \command{patch} command applies a list of
|
|
bos@15
|
331 modifications to a file. The kinds of files that \command{diff} and
|
|
bos@15
|
332 \command{patch} work with are referred to as both ``diffs'' and
|
|
bos@15
|
333 ``patches;'' there is no difference between a diff and a patch.
|
|
bos@15
|
334
|
|
bos@14
|
335 A patch file can start with arbitrary text; MQ uses this text as the
|
|
bos@14
|
336 commit message when creating changesets. It treats the first line
|
|
bos@14
|
337 that starts with the string ``\texttt{diff~-}'' as the separator
|
|
bos@14
|
338 between header and content.
|
|
bos@14
|
339
|
|
bos@15
|
340 MQ works with \emph{unified} diffs (\command{patch} can accept several
|
|
bos@15
|
341 other diff formats, but MQ doesn't). A unified diff contains two
|
|
bos@14
|
342 kinds of header. The \emph{file header} describes the file being
|
|
bos@14
|
343 modified; it contains the name of the file to modify. When
|
|
bos@15
|
344 \command{patch} sees a new file header, it looks for a file with that
|
|
bos@14
|
345 name to start modifying.
|
|
bos@14
|
346
|
|
bos@15
|
347 After the file header comes a series of \emph{hunks}. Each hunk
|
|
bos@15
|
348 starts with a header; this identifies the range of line numbers within
|
|
bos@15
|
349 the file that the hunk should modify. Following the header, a hunk
|
|
bos@15
|
350 starts and ends with a few (usually three) lines of text from the
|
|
bos@15
|
351 unmodified file; these are called the \emph{context} for the hunk.
|
|
bos@15
|
352 Each unmodified line begins with a space characters. Within the hunk,
|
|
bos@15
|
353 a line that begins with ``\texttt{-}'' means ``remove this line,''
|
|
bos@15
|
354 while a line that begins with ``\texttt{+}'' means ``insert this
|
|
bos@15
|
355 line.'' For example, a line that is modified is represented by one
|
|
bos@15
|
356 deletion and one insertion.
|
|
bos@15
|
357
|
|
bos@15
|
358 The \command{diff} command runs hunks together when there's not enough
|
|
bos@15
|
359 context between modifications to justify
|
|
bos@14
|
360
|
|
bos@14
|
361 When \command{patch} applies a hunk, it tries a handful of
|
|
bos@14
|
362 successively less accurate strategies to try to make the hunk apply.
|
|
bos@14
|
363 This falling-back technique often makes it possible to take a patch
|
|
bos@14
|
364 that was generated against an old version of a file, and apply it
|
|
bos@14
|
365 against a newer version of that file.
|
|
bos@14
|
366
|
|
bos@14
|
367 First, \command{patch} tries an exact match, where the line numbers,
|
|
bos@14
|
368 the context, and the text to be modified must apply exactly. If it
|
|
bos@14
|
369 cannot make an exact match, it tries to find an exact match for the
|
|
bos@14
|
370 context, without honouring the line numbering information. If this
|
|
bos@14
|
371 succeeds, it prints a line of output saying that the hunk was applied,
|
|
bos@14
|
372 but at some \emph{offset} from the original line number.
|
|
bos@14
|
373
|
|
bos@14
|
374 If a context-only match fails, \command{patch} removes the first and
|
|
bos@14
|
375 last lines of the context, and tries a \emph{reduced} context-only
|
|
bos@14
|
376 match. If the hunk with reduced context succeeds, it prints a message
|
|
bos@14
|
377 saying that it applied the hunk with a \emph{fuzz factor} (the number
|
|
bos@14
|
378 after the fuzz factor indicates how many lines of context
|
|
bos@14
|
379 \command{patch} had to trim before the patch applied).
|
|
bos@14
|
380
|
|
bos@14
|
381 When neither of these techniques works, \command{patch} prints a
|
|
bos@14
|
382 message saying that the hunk in question was rejected. It saves
|
|
bos@14
|
383 rejected hunks to a file with the same name, and an added
|
|
bos@15
|
384 \filename{.rej} extension. It also saves an unmodified copy of the
|
|
bos@15
|
385 file with a \filename{.orig} extension; the copy of the file without
|
|
bos@15
|
386 any extensions will contain any changes made by hunks that \emph{did}
|
|
bos@15
|
387 apply cleanly. If you have a patch that modifies \filename{foo} with
|
|
bos@15
|
388 six hunks, and one of them fails to apply, you will have: an
|
|
bos@15
|
389 unmodified \filename{foo.orig}, a \filename{foo.rej} containing one
|
|
bos@15
|
390 hunk, and \filename{foo}, containing the changes made by the five
|
|
bos@15
|
391 successful five hunks.
|
|
bos@14
|
392
|
|
bos@14
|
393 \subsection{Beware the fuzz}
|
|
bos@14
|
394
|
|
bos@14
|
395 While applying a hunk at an offset, or with a fuzz factor, will often
|
|
bos@14
|
396 be completely successful, these inexact techniques naturally leave
|
|
bos@14
|
397 open the possibility of corrupting the patched file. The most common
|
|
bos@14
|
398 cases typically involve applying a patch twice, or at an incorrect
|
|
bos@14
|
399 location in the file. If \command{patch} or \hgcmd{qpush} ever
|
|
bos@14
|
400 mentions an offset or fuzz factor, you should make sure that the
|
|
bos@14
|
401 modified files are correct afterwards.
|
|
bos@14
|
402
|
|
bos@14
|
403 It's often a good idea to refresh a patch that has applied with an
|
|
bos@14
|
404 offset or fuzz factor; refreshing the patch generates new context
|
|
bos@14
|
405 information that will make it apply cleanly. I say ``often,'' not
|
|
bos@14
|
406 ``always,'' because sometimes refreshing a patch will make it fail to
|
|
bos@14
|
407 apply against a different revision of the underlying files. In some
|
|
bos@14
|
408 cases, such as when you're maintaining a patch that must sit on top of
|
|
bos@14
|
409 multiple versions of a source tree, it's acceptable to have a patch
|
|
bos@14
|
410 apply with some fuzz, provided you've verified the results of the
|
|
bos@14
|
411 patching process in such cases.
|
|
bos@14
|
412
|
|
bos@15
|
413 \subsection{Handling rejection}
|
|
bos@15
|
414
|
|
bos@15
|
415 If \hgcmd{qpush} fails to apply a patch, it will print an error
|
|
bos@15
|
416 message and exit. If it has left \filename{.rej} files behind, it is
|
|
bos@15
|
417 usually best to fix up the rejected hunks before you push more patches
|
|
bos@15
|
418 or do any further work.
|
|
bos@15
|
419
|
|
bos@15
|
420 If your patch \emph{used to} apply cleanly, and no longer does because
|
|
bos@15
|
421 you've changed the underlying code that your patches are based on,
|
|
bos@15
|
422 Mercurial Queues can help; see section~\ref{seq:mq:merge} for details.
|
|
bos@15
|
423
|
|
bos@15
|
424 Unfortunately, there aren't any great techniques for dealing with
|
|
bos@15
|
425 rejected hunks. Most often, you'll need to view the \filename{.rej}
|
|
bos@15
|
426 file and edit the target file, applying the rejected hunks by hand.
|
|
bos@15
|
427
|
|
bos@15
|
428 If you're feeling adventurous, Neil Brown, an Australian Linux kernel
|
|
bos@15
|
429 hacker, has written a tool called \command{wiggle}~\cite{web:wiggle},
|
|
bos@15
|
430 which is more vigorous than \command{patch} in its attempts to make a
|
|
bos@15
|
431 patch apply.
|
|
bos@15
|
432
|
|
bos@15
|
433 Another Linux kernel hacker, Chris Mason (the author of Mercurial
|
|
bos@15
|
434 Queues), wrote a similar tool called \command{rej}~\cite{web:rej},
|
|
bos@15
|
435 which takes a simple approach to automating the application of hunks
|
|
bos@15
|
436 rejected by \command{patch}. \command{rej} can help with four common
|
|
bos@15
|
437 reasons that a hunk may be rejected:
|
|
bos@15
|
438
|
|
bos@15
|
439 \begin{itemize}
|
|
bos@15
|
440 \item The context in the middle of a hunk has changed.
|
|
bos@15
|
441 \item A hunk is missing some context at the beginning or end.
|
|
bos@15
|
442 \item A large hunk might apply better--either entirely or in part--if
|
|
bos@15
|
443 it was broken up into smaller hunks.
|
|
bos@15
|
444 \item A hunk removes lines with slightly different content than those
|
|
bos@15
|
445 currently present in the file.
|
|
bos@15
|
446 \end{itemize}
|
|
bos@15
|
447
|
|
bos@15
|
448 If you use \command{wiggle} or \command{rej}, you should be doubly
|
|
bos@15
|
449 careful to check your results when you're done.
|
|
bos@15
|
450
|
|
bos@15
|
451 \section{Updating your patches when the underlying code changes}
|
|
bos@15
|
452 \label{sec:mq:merge}
|
|
bos@15
|
453
|
|
bos@15
|
454 XXX.
|
|
bos@13
|
455
|
|
bos@1
|
456 %%% Local Variables:
|
|
bos@1
|
457 %%% mode: latex
|
|
bos@1
|
458 %%% TeX-master: "00book"
|
|
bos@1
|
459 %%% End:
|
