annotate en/mq.tex @ 17:2668e15c76e9

MQ: write up patch rebasing.
author Bryan O'Sullivan <bos@serpentine.com>
date Tue, 04 Jul 2006 15:00:18 -0700
parents 81454425eee9
children e6f4088ebe52
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1 \chapter{Managing change with Mercurial Queues}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
2 \label{chap:mq}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
3
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
4 \section{The patch management problem}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
5 \label{sec:mq:patch-mgmt}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
6
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
7 Here is a common scenario: you need to install a software package from
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
8 source, but you find a bug that you must fix in the source before you
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
9 can start using the package. You make your changes, forget about the
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
10 package for a while, and a few months later you need to upgrade to a
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
11 newer version of the package. If the newer version of the package
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
12 still has the bug, you must extract your fix from the older source
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
13 tree and apply it against the newer version. This is a tedious task,
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
14 and it's easy to make mistakes.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
15
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
16 This is a simple case of the ``patch management'' problem. You have
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
17 an ``upstream'' source tree that you can't change; you need to make
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
18 some local changes on top of the upstream tree; and you'd like to be
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
19 able to keep those changes separate, so that you can apply them to
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
20 newer versions of the upstream source.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
21
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
22 The patch management problem arises in many situations. Probably the
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
23 most visible is that a user of an open source software project will
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
24 contribute a bug fix or new feature to the project's maintainers in the
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
25 form of a patch.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
26
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
27 Distributors of operating systems that include open source software
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
28 often need to make changes to the packages they distribute so that
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
29 they will build properly in their environments.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
30
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
31 When you have few changes to maintain, it is easy to manage a single
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
32 patch using the standard \texttt{diff} and \texttt{patch} programs
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
33 (see section~\ref{sec:mq:patch} for a discussion of these tools).
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
34 Once the number of changes grows, it starts to makes sense to maintain
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
35 patches as discrete ``chunks of work,'' so that for example a single
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
36 patch will contain only one bug fix (the patch might modify several
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
37 files, but it's doing ``only one thing''), and you may have a number
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
38 of such patches for different bugs you need fixed and local changes
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
39 you require. In this situation, if you submit a bug fix patch to the
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
40 upstream maintainers of a package and they include your fix in a
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
41 subsequent release, you can simply drop that single patch when you're
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
42 updating to the newer release.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
43
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
44 Maintaining a single patch against an upstream tree is a little
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
45 tedious and error-prone, but not difficult. However, the complexity
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
46 of the problem grows rapidly as the number of patches you have to
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
47 maintain increases. With more than a tiny number of patches in hand,
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
48 understanding which ones you have applied and maintaining them moves
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
49 from messy to overwhelming.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
50
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
51 Fortunately, Mercurial includes a powerful extension, Mercurial Queues
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
52 (or simply ``MQ''), that massively simplifies the patch management
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
53 problem.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
54
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
55 \section{The prehistory of Mercurial Queues}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
56 \label{sec:mq:history}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
57
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
58 During the late 1990s, several Linux kernel developers started to
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
59 maintain ``patch series'' that modified the behaviour of the Linux
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
60 kernel. Some of these series were focused on stability, some on
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
61 feature coverage, and others were more speculative.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
62
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
63 The sizes of these patch series grew rapidly. In 2002, Andrew Morton
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
64 published some shell scripts he had been using to automate the task of
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
65 managing his patch queues. Andrew was successfully using these
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
66 scripts to manage hundreds (sometimes thousands) of patches on top of
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
67 the Linux kernel.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
68
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
69 \subsection{A patchwork quilt}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
70 \label{sec:mq:quilt}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
71
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
72
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
73 In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
2
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
74 approach of Andrew's scripts and published a tool called ``patchwork
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
75 quilt''~\cite{web:quilt}, or simply ``quilt''
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
76 (see~\cite{gruenbacher:2005} for a paper describing it). Because
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
77 quilt substantially automated patch management, it rapidly gained a
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
78 large following among open source software developers.
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
79
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
80 Quilt manages a \emph{stack of patches} on top of a directory tree.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
81 To begin, you tell quilt to manage a directory tree; it stores away
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
82 the names and contents of all files in the tree. To fix a bug, you
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
83 create a new patch (using a single command), edit the files you need
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
84 to fix, then ``refresh'' the patch.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
85
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
86 The refresh step causes quilt to scan the directory tree; it updates
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
87 the patch with all of the changes you have made. You can create
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
88 another patch on top of the first, which will track the changes
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
89 required to modify the tree from ``tree with one patch applied'' to
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
90 ``tree with two patches applied''.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
91
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
92 You can \emph{change} which patches are applied to the tree. If you
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
93 ``pop'' a patch, the changes made by that patch will vanish from the
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
94 directory tree. Quilt remembers which patches you have popped,
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
95 though, so you can ``push'' a popped patch again, and the directory
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
96 tree will be restored to contain the modifications in the patch. Most
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
97 importantly, you can run the ``refresh'' command at any time, and the
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
98 topmost applied patch will be updated. This means that you can, at
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
99 any time, change both which patches are applied and what
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
100 modifications those patches make.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
101
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
102 Quilt knows nothing about revision control tools, so it works equally
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
103 well on top of an unpacked tarball or a Subversion repository.
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
104
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
105 \subsection{From patchwork quilt to Mercurial Queues}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
106 \label{sec:mq:quilt-mq}
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
107
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
108 In mid-2005, Chris Mason took the features of quilt and wrote an
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
109 extension that he called Mercurial Queues, which added quilt-like
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
110 behaviour to Mercurial.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
111
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
112 The key difference between quilt and MQ is that quilt knows nothing
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
113 about revision control systems, while MQ is \emph{integrated} into
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
114 Mercurial. Each patch that you push is represented as a Mercurial
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
115 changeset. Pop a patch, and the changeset goes away.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
116
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
117 This integration makes understanding patches and debugging their
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
118 effects \emph{enormously} easier. Since every applied patch has an
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
119 associated changeset, you can use \hgcmdargs{log}{\emph{filename}} to
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
120 see which changesets and patches affected a file. You can use the
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
121 \hgext{bisect} extension to binary-search through all changesets and
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
122 applied patches to see where a bug got introduced or fixed. You can
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
123 use the \hgcmd{annotate} command to see which changeset or patch
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
124 modified a particular line of a source file. And so on.
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
125
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
126 Because quilt does not care about revision control tools, it is still
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
127 a tremendously useful piece of software to know about for situations
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
128 where you cannot use Mercurial and MQ.
2
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
129 \section{Getting started with Mercurial Queues}
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
130 \label{sec:mq:start}
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
131
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
132 Because MQ is implemented as an extension, you must explicitly enable
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
133 before you can use it. (You don't need to download anything; MQ ships
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
134 with the standard Mercurial distribution.) To enable MQ, edit your
4
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
135 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.
2
379a802c0210 Add bibliography.
Bryan O'Sullivan <bos@serpentine.com>
parents: 1
diff changeset
136
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
137 \begin{figure}[ht]
4
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
138 \begin{codesample4}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
139 [extensions]
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
140 hgext.mq =
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
141 \end{codesample4}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
142 \label{ex:mq:config}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
143 \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
144 \end{figure}
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
145
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
146 Once the extension is enabled, it will make a number of new commands
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
147 available. To verify that the extension is working, you can use
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
148 \hgcmd{help} to see if the \hgcmd{qinit} command is now available; see
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
149 the example in figure~\ref{ex:mq:enabled}.
3
906d9021f9e5 Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents: 2
diff changeset
150
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
151 \begin{figure}[ht]
4
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
152 \interaction{mq.qinit-help.help}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
153 \caption{How to verify that MQ is enabled}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
154 \label{ex:mq:enabled}
33a2e7b9978d Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 3
diff changeset
155 \end{figure}
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
156
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
157 You can use MQ with \emph{any} Mercurial repository, and its commands
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
158 only operate within that repository. To get started, simply prepare
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
159 the repository using the \hgcmd{qinit} command (see
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
160 figure~\ref{ex:mq:qinit}). This command creates an empty directory
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
161 called \sdirname{.hg/patches}, where MQ will keep its metadata. As
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
162 with many Mercurial commands, the \hgcmd{qinit} command prints nothing
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
163 if it succeeds.
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
164
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
165 \begin{figure}[ht]
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
166 \interaction{mq.tutorial.qinit}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
167 \caption{Preparing a repository for use with MQ}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
168 \label{ex:mq:qinit}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
169 \end{figure}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
170
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
171 \begin{figure}[ht]
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
172 \interaction{mq.tutorial.qnew}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
173 \caption{Creating a new patch}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
174 \label{ex:mq:qnew}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
175 \end{figure}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
176
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
177 \subsection{Creating a new patch}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
178
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
179 To begin work on a new patch, use the \hgcmd{qnew} command. This
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
180 command takes one argument, the name of the patch to create. MQ will
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
181 use this as the name of an actual file in the \sdirname{.hg/patches}
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
182 directory, as you can see in figure~\ref{ex:mq:qnew}.
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
183
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
184 Also newly present in the \sdirname{.hg/patches} directory are two
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
185 other files, \sfilename{series} and \sfilename{status}. The
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
186 \sfilename{series} file lists all of the patches that MQ knows about
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
187 for this repository, with one patch per line. Mercurial uses the
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
188 \sfilename{status} file for internal book-keeping; it tracks all of the
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
189 patches that MQ has \emph{applied} in this repository.
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
190
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
191 \begin{note}
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
192 You may sometimes want to edit the \sfilename{series} file by hand;
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
193 for example, to change the sequence in which some patches are
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
194 applied. However, manually editing the \sfilename{status} file is
7
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
195 almost always a bad idea, as it's easy to corrupt MQ's idea of what
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
196 is happening.
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
197 \end{note}
339e75288632 More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents: 4
diff changeset
198
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
199 Once you have created your new patch, you can edit files in the
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
200 working directory as you usually would. All of the normal Mercurial
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
201 commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
202 they did before.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
203 \subsection{Refreshing a patch}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
204
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
205 When you reach a point where you want to save your work, use the
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
206 \hgcmd{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
207 you are working on. This command folds the changes you have made in
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
208 the working directory into your patch, and updates its corresponding
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
209 changeset to contain those changes.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
210
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
211 \begin{figure}[ht]
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
212 \interaction{mq.tutorial.qrefresh}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
213 \caption{Refreshing a patch}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
214 \label{ex:mq:qrefresh}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
215 \end{figure}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
216
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
217 You can run \hgcmd{qrefresh} as often as you like, so it's a good way
13
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
218 to ``checkpoint'' your work. Refresh your patch at an opportune
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
219 time; try an experiment; and if the experiment doesn't work out,
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
220 \hgcmd{revert} your modifications back to the last time you refreshed.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
221
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
222 \begin{figure}[ht]
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
223 \interaction{mq.tutorial.qrefresh2}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
224 \caption{Refresh a patch many times to accumulate changes}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
225 \label{ex:mq:qrefresh2}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
226 \end{figure}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
227
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
228 \subsection{Stacking and tracking patches}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
229
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
230 Once you have finished working on a patch, or need to work on another,
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
231 you can use the \hgcmd{qnew} command again to create a new patch.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
232 Mercurial will apply this patch on top of your existing patch. See
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
233 figure~\ref{ex:mq:qnew2} for an example. Notice that the patch
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
234 contains the changes in our prior patch as part of its context (you
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
235 can see this more clearly in the output of \hgcmd{annotate}).
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
236
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
237 \begin{figure}[ht]
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
238 \interaction{mq.tutorial.qnew2}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
239 \caption{Stacking a second patch on top of the first}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
240 \label{ex:mq:qnew2}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
241 \end{figure}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
242
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
243 So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
244 been careful to only use regular Mercurial commands. However, there
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
245 are more ``natural'' commands you can use when thinking about patches
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
246 with MQ, as illustrated in figure~\ref{ex:mq:qseries}:
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
247
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
248 \begin{itemize}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
249 \item The \hgcmd{qseries} command lists every patch that MQ knows
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
250 about in this repository, from oldest to newest (most recently
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
251 \emph{created}).
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
252 \item The \hgcmd{qapplied} command lists every patch that MQ has
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
253 \emph{applied} in this repository, again from oldest to newest (most
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
254 recently applied).
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
255 \end{itemize}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
256
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
257 \begin{figure}[ht]
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
258 \interaction{mq.tutorial.qseries}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
259 \caption{Understanding the patch stack with \hgcmd{qseries} and
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
260 \hgcmd{qapplied}}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
261 \label{ex:mq:qseries}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
262 \end{figure}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
263
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
264 \subsection{Manipulating the patch stack}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
265
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
266 The previous discussion implied that there must be a difference
11
e9d5b4c3d16b First SVG image!
Bryan O'Sullivan <bos@serpentine.com>
parents: 8
diff changeset
267 between ``known'' and ``applied'' patches, and there is. MQ can
e9d5b4c3d16b First SVG image!
Bryan O'Sullivan <bos@serpentine.com>
parents: 8
diff changeset
268 manage a patch without it being applied in the repository.
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
269
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
270 An \emph{applied} patch has a corresponding changeset in the
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
271 repository, and the effects of the patch and changeset are visible in
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
272 the working directory. You can undo the application of a patch using
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
273 the \hgcmd{qpop} command. MQ still \emph{knows about}, or manages, a
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
274 popped patch, but the patch no longer has a corresponding changeset in
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
275 the repository, and the working directory does not contain the changes
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
276 made by the patch. Figure~\ref{fig:mq:stack} illustrates the
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
277 difference between applied and tracked patches.
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
278
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
279 \begin{figure}[ht]
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
280 \centering
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
281 \grafix{mq-stack}
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
282 \caption{Applied and unapplied patches in the MQ patch stack}
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
283 \label{fig:mq:stack}
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
284 \end{figure}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
285
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
286 You can reapply an unapplied, or popped, patch using the \hgcmd{qpush}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
287 command. This creates a new changeset to correspond to the patch, and
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
288 the patch's changes once again become present in the working
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
289 directory. See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop}
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
290 and \hgcmd{qpush} in action. Notice that once we have popped a patch
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
291 or two patches, the output of \hgcmd{qseries} remains the same, while
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
292 that of \hgcmd{qapplied} has changed.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
293
12
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
294 \begin{figure}[ht]
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
295 \interaction{mq.tutorial.qpop}
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
296 \caption{Modifying the stack of applied patches}
1f692024d438 More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 11
diff changeset
297 \label{ex:mq:qpop}
11
e9d5b4c3d16b First SVG image!
Bryan O'Sullivan <bos@serpentine.com>
parents: 8
diff changeset
298 \end{figure}
e9d5b4c3d16b First SVG image!
Bryan O'Sullivan <bos@serpentine.com>
parents: 8
diff changeset
299
8
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
300 MQ does not limit you to pushing or popping one patch. You can have
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
301 no patches, all of them, or any number in between applied at some
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
302 point in time.
a25335b56825 Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents: 7
diff changeset
303
13
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
304 \subsection{Working on several patches at once}
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
305
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
306 The \hgcmd{qrefresh} command always refreshes the \emph{topmost}
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
307 applied patch. This means that you can suspend work on one patch (by
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
308 refreshing it), pop or push to make a different patch the top, and
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
309 work on \emph{that} patch for a while.
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
310
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
311 Here's an example that illustrates how you can use this ability.
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
312 Let's say you're developing a new feature as two patches. The first
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
313 is a change to the core of your software, and the second--layered on
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
314 top of the first--changes the user interface to use the code you just
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
315 added to the core. If you notice a bug in the core while you're
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
316 working on the UI patch, it's easy to fix the core. Simply
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
317 \hgcmd{qrefresh} the UI patch to save your in-progress changes, and
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
318 \hgcmd{qpop} down to the core patch. Fix the core bug,
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
319 \hgcmd{qrefresh} the core patch, and \hgcmd{qpush} back to the UI
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
320 patch to continue where you left off.
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
321
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
322 \section{Mercurial Queues and GNU patch}
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
323 \label{sec:mq:patch}
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
324
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
325 MQ uses the GNU \command{patch} command to apply patches. Because MQ
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
326 doesn't hide its patch-oriented nature, it is helpful to understand
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
327 the data that MQ and \command{patch} work with, and a few aspects of
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
328 how \command{patch} operates.
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
329
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
330 The \command{diff} command generates a list of modifications by
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
331 comparing two files. The \command{patch} command applies a list of
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
332 modifications to a file. The kinds of files that \command{diff} and
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
333 \command{patch} work with are referred to as both ``diffs'' and
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
334 ``patches;'' there is no difference between a diff and a patch.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
335
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
336 A patch file can start with arbitrary text; MQ uses this text as the
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
337 commit message when creating changesets. It treats the first line
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
338 that starts with the string ``\texttt{diff~-}'' as the separator
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
339 between header and content.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
340
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
341 MQ works with \emph{unified} diffs (\command{patch} can accept several
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
342 other diff formats, but MQ doesn't). A unified diff contains two
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
343 kinds of header. The \emph{file header} describes the file being
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
344 modified; it contains the name of the file to modify. When
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
345 \command{patch} sees a new file header, it looks for a file with that
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
346 name to start modifying.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
347
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
348 After the file header comes a series of \emph{hunks}. Each hunk
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
349 starts with a header; this identifies the range of line numbers within
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
350 the file that the hunk should modify. Following the header, a hunk
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
351 starts and ends with a few (usually three) lines of text from the
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
352 unmodified file; these are called the \emph{context} for the hunk.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
353 Each unmodified line begins with a space characters. Within the hunk,
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
354 a line that begins with ``\texttt{-}'' means ``remove this line,''
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
355 while a line that begins with ``\texttt{+}'' means ``insert this
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
356 line.'' For example, a line that is modified is represented by one
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
357 deletion and one insertion.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
358
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
359 The \command{diff} command runs hunks together when there's not enough
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
360 context between modifications to justify
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
361
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
362 When \command{patch} applies a hunk, it tries a handful of
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
363 successively less accurate strategies to try to make the hunk apply.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
364 This falling-back technique often makes it possible to take a patch
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
365 that was generated against an old version of a file, and apply it
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
366 against a newer version of that file.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
367
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
368 First, \command{patch} tries an exact match, where the line numbers,
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
369 the context, and the text to be modified must apply exactly. If it
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
370 cannot make an exact match, it tries to find an exact match for the
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
371 context, without honouring the line numbering information. If this
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
372 succeeds, it prints a line of output saying that the hunk was applied,
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
373 but at some \emph{offset} from the original line number.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
374
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
375 If a context-only match fails, \command{patch} removes the first and
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
376 last lines of the context, and tries a \emph{reduced} context-only
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
377 match. If the hunk with reduced context succeeds, it prints a message
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
378 saying that it applied the hunk with a \emph{fuzz factor} (the number
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
379 after the fuzz factor indicates how many lines of context
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
380 \command{patch} had to trim before the patch applied).
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
381
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
382 When neither of these techniques works, \command{patch} prints a
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
383 message saying that the hunk in question was rejected. It saves
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
384 rejected hunks (also simply called ``rejects'') to a file with the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
385 same name, and an added \sfilename{.rej} extension. It also saves an
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
386 unmodified copy of the file with a \sfilename{.orig} extension; the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
387 copy of the file without any extensions will contain any changes made
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
388 by hunks that \emph{did} apply cleanly. If you have a patch that
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
389 modifies \filename{foo} with six hunks, and one of them fails to
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
390 apply, you will have: an unmodified \filename{foo.orig}, a
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
391 \filename{foo.rej} containing one hunk, and \filename{foo}, containing
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
392 the changes made by the five successful five hunks.
14
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
393
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
394 \subsection{Beware the fuzz}
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
395
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
396 While applying a hunk at an offset, or with a fuzz factor, will often
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
397 be completely successful, these inexact techniques naturally leave
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
398 open the possibility of corrupting the patched file. The most common
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
399 cases typically involve applying a patch twice, or at an incorrect
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
400 location in the file. If \command{patch} or \hgcmd{qpush} ever
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
401 mentions an offset or fuzz factor, you should make sure that the
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
402 modified files are correct afterwards.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
403
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
404 It's often a good idea to refresh a patch that has applied with an
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
405 offset or fuzz factor; refreshing the patch generates new context
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
406 information that will make it apply cleanly. I say ``often,'' not
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
407 ``always,'' because sometimes refreshing a patch will make it fail to
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
408 apply against a different revision of the underlying files. In some
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
409 cases, such as when you're maintaining a patch that must sit on top of
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
410 multiple versions of a source tree, it's acceptable to have a patch
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
411 apply with some fuzz, provided you've verified the results of the
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
412 patching process in such cases.
e2aa527bafa0 Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents: 13
diff changeset
413
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
414 \subsection{Handling rejection}
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
415
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
416 If \hgcmd{qpush} fails to apply a patch, it will print an error
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
417 message and exit. If it has left \sfilename{.rej} files behind, it is
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
418 usually best to fix up the rejected hunks before you push more patches
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
419 or do any further work.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
420
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
421 If your patch \emph{used to} apply cleanly, and no longer does because
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
422 you've changed the underlying code that your patches are based on,
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
423 Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
424
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
425 Unfortunately, there aren't any great techniques for dealing with
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
426 rejected hunks. Most often, you'll need to view the \sfilename{.rej}
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
427 file and edit the target file, applying the rejected hunks by hand.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
428
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
429 If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
430 wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
431 vigorous than \command{patch} in its attempts to make a patch apply.
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
432
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
433 Another Linux kernel hacker, Chris Mason (the author of Mercurial
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
434 Queues), wrote a similar tool called \command{rej}~\cite{web:rej},
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
435 which takes a simple approach to automating the application of hunks
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
436 rejected by \command{patch}. \command{rej} can help with four common
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
437 reasons that a hunk may be rejected:
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
438
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
439 \begin{itemize}
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
440 \item The context in the middle of a hunk has changed.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
441 \item A hunk is missing some context at the beginning or end.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
442 \item A large hunk might apply better--either entirely or in part--if
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
443 it was broken up into smaller hunks.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
444 \item A hunk removes lines with slightly different content than those
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
445 currently present in the file.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
446 \end{itemize}
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
447
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
448 If you use \command{wiggle} or \command{rej}, you should be doubly
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
449 careful to check your results when you're done.
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
450
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
451 \section{Getting the best performance out of MQ}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
452
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
453 MQ is very efficient at handling a large number of patches. I ran
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
454 some performance experiments in mid-2006 for a talk that I gave at the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
455 2006 EuroPython conference~\cite{web:europython}. I used as my data
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
456 set the Linux 2.6.17-mm1 patch series, which consists of 1,738
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
457 patches. I applied thes on top of a Linux kernel repository
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
458 containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
459 2.6.17.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
460
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
461 On my old, slow laptop, I was able to
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
462 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes,
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
463 and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds. I
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
464 could \hgcmd{qrefresh} one of the biggest patches (which made 22,779
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
465 lines of changes to 287 files) in 6.6 seconds.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
466
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
467 Clearly, MQ is well suited to working in large trees, but there are a
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
468 few tricks you can use to get the best performance of it.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
469
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
470 First of all, try to ``batch'' operations together. Every time you
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
471 run \hgcmd{qpush} or \hgcmd{qpop}, these commands scan the working
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
472 directory once to make sure you haven't made some changes and then
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
473 forgotten to run \hgcmd{qrefresh}. On a small tree, the time that
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
474 this scan takes is unnoticeable. However, on a medium-sized tree
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
475 (containing tens of thousands of files), it can take a second or more.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
476
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
477 The \hgcmd{qpush} and \hgcmd{qpop} commands allow you to push and pop
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
478 multiple patches at a time. You can identify the ``destination
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
479 patch'' that you want to end up at. When you \hgcmd{qpush} with a
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
480 destination specified, it will push patches until that patch is at the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
481 top of the applied stack. When you \hgcmd{qpop} to a destination, MQ
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
482 will pop patches until the destination patch \emph{is no longer}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
483 applied.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
484
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
485 You can identify a destination patch using either the name of the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
486 patch, or by number. If you use numeric addressing, patches are
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
487 counted from zero; this means that the first patch is zero, the second
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
488 is one, and so on.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
489
15
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
490 \section{Updating your patches when the underlying code changes}
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
491 \label{sec:mq:merge}
b8ac9f312a47 Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents: 14
diff changeset
492
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
493 It's common to have a stack of patches on top of an underlying
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
494 repository that you don't modify directly. If you're working on
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
495 changes to third-party code, or on a feature that is taking longer to
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
496 develop than the rate of change of the code beneath, you will often
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
497 need to sync up with the underlying code, and fix up any hunks in your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
498 patches that no longer apply. This is called \emph{rebasing} your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
499 patch series.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
500
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
501 The simplest way to do this is to \hgcmdargs{qpop}{\hgopt{qpop}{-a}}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
502 your patches, then \hgcmd{pull} changes into the underlying
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
503 repository, and finally \hgcmdargs{qpush}{\hgopt{qpop}{-a}} your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
504 patches again. MQ will stop pushing any time it runs across a patch
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
505 that fails to apply during conflicts, allowing you to fix your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
506 conflicts, \hgcmd{qrefresh} the affected patch, and continue pushing
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
507 until you have fixed your entire stack.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
508
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
509 This approach is easy to use and works well if you don't expect
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
510 changes to the underlying code to affect how well your patches apply.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
511 If your patch stack touches code that is modified frequently or
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
512 invasively in the underlying repository, however, fixing up rejected
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
513 hunks by hand quickly becomes tiresome.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
514
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
515 It's possible to partially automate the rebasing process. If your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
516 patches apply cleanly against some revision of the underlying repo, MQ
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
517 can use this information to help you to resolve conflicts between your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
518 patches and a different revision.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
519
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
520 The process is a little involved.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
521 \begin{enumerate}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
522 \item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
523 the revision where you know that they apply cleanly.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
524 \item Save a backup copy of your patch directory using
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
525 \hgcmdargs{qsave}{\hgopt{qsave}{-e} \hgopt{qsave}{-c}}. This prints
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
526 the name of the directory that it has saved the patches in. It will
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
527 save the patches to a directory called
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
528 \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
529 integer. It also commits a ``save changeset'' on top of your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
530 applied patches; this is for internal book-keeping, and records the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
531 states of the \sfilename{series} and \sfilename{status} files.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
532 \item Use \hgcmd{pull} to bring new changes into the underlying
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
533 repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.)
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
534 \item Update to the new tip revision, using
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
535 \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
536 have pushed.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
537 \item Merge all patches using \hgcmdargs{qpush}{\hgopt{qpush}{-m}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
538 \hgopt{qpush}{-a}}. The \hgopt{qpush}{-m} option to \hgcmd{qpush}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
539 tells MQ to perform a three-way merge if the patch fails to apply.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
540 \end{enumerate}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
541
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
542 During the \hgcmdargs{qpush}{\hgopt{qpush}{-m}}, each patch in the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
543 \sfilename{series} file is applied normally. If a patch applies with
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
544 fuzz or rejects, MQ looks at the queue you \hgcmd{qsave}d, and
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
545 performs a three-way merge with the corresponding changeset. This
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
546 merge uses Mercurial's normal merge machinery, so it may pop up a GUI
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
547 merge tool to help you to resolve problems.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
548
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
549 When you finish resolving the effects of a patch, MQ refreshes your
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
550 patch based on the result of the merge.
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
551
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
552 At the end of this process, your repository will have one extra head
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
553 from the old patch queue, and a copy of the old patch queue will be in
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
554 \sdirname{.hg/patches.\emph{N}}. You can remove the extra head using
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
555 \hgcmdargs{qpop}{\hgopt{qpop}{-a} \hgopt{qpop}{-n} patches.\emph{N}}
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
556 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
557 you are sure that you no longer need it as a backup.
13
5c3966f6991b Add a parapgraph.
Bryan O'Sullivan <bos@serpentine.com>
parents: 12
diff changeset
558
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
559 \section{Managing patches in a repository}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
560
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
561 Because MQ's \sdirname{.hg/patches} directory resides outside a
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
562 Mercurial repository's working directory, the ``underlying'' Mercurial
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
563 repository knows nothing about the management or presence of patches.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
564
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
565 This presents the interesting possibility of managing the contents of
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
566 the patch directory as a Mercurial repository in its own right. This
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
567 can be a useful way to work. For example, you can work on a patch for
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
568 a while, \hgcmd{qrefresh} it, then \hgcmd{commit} the current state of
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
569 the patch. This lets you ``roll back'' to that version of the patch
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
570 later on.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
571
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
572 In addition, you can then share different versions of the same patch
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
573 stack among multiple underlying repositories. I use this when I am
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
574 developing a Linux kernel feature. I have a pristine copy of my
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
575 kernel sources for each of several CPU architectures, and a cloned
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
576 repository under each that contains the patches I am working on. When
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
577 I want to test a change on a different architecture, I push my current
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
578 patches to the patch repository associated with that kernel tree, pop
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
579 and push all of my patches, and build and test that kernel.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
580
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
581 Managing patches in a repository makes it possible for multiple
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
582 developers to work on the same patch series without colliding with
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
583 each other, all on top of an underlying source base that they may or
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
584 may not control.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
585
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
586 \subsection{MQ support for patch repositories}
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
587
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
588 MQ helps you to work with the \sdirname{.hg/patches} directory as a
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
589 repository; when you prepare a repository for working with patches
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
590 using \hgcmd{qinit}, you can pass the \hgopt{qinit}{-c} option to
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
591 create the \sdirname{.hg/patches} directory as a Mercurial repository.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
592
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
593 \begin{note}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
594 If you forget to use the \hgopt{qinit}{-c} option, you can simply go
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
595 into the \sdirname{.hg/patches} directory at any time and run
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
596 \hgcmd{init}. Don't forget to add an entry for the
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
597 \sfilename{status} file to the \sfilename{.hgignore} file, though
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
598 (\hgcmdargs{qinit}{\hgopt{qinit}{-c}} does this for you
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
599 automatically); you \emph{really} don't want to manage the
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
600 \sfilename{status} file.
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
601 \end{note}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
602
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
603 As a convenience, if MQ notices that the \dirname{.hg/patches}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
604 directory is a repository, it will automatically \hgcmd{add} every
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
605 patch that you create and import.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
606
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
607 Finally, MQ provides a shortcut command, \hgcmd{qcommit}, that runs
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
608 \hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
609 some cumbersome typing.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
610
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
611 \subsection{A few things to watch out for}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
612
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
613 MQ's support for working with a repository full of patches is limited
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
614 in a few small respects.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
615
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
616 MQ cannot automatically detect changes that you make to the patch
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
617 directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
618 changes to patches or the \sfilename{series} file, you will have to
17
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
619 \hgcmdargs{qpop}{\hgopt{qpop}{-a}} and then
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
620 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} in the underlying repository to
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
621 see those changes show up there. If you forget to do this, you can
2668e15c76e9 MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents: 16
diff changeset
622 confuse MQ's idea of which patches are applied.
16
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
623
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
624 \section{Commands for working with patches}
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
625
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
626 Once you've been working with patches for a while, you'll find
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
627 yourself hungry for tools that will help you to understand and
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
628 manipulate the patches you're dealing with.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
629
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
630 The \command{diffstat} command~\cite{web:diffstat} generates a
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
631 histogram of the modifications made to each file in a patch. It
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
632 provides a good way to ``get a sense of'' a patch--which files it
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
633 affects, and how much change it introduces to each file and as a
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
634 whole. (I find that it's a good idea to use \command{diffstat}'s
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
635 \texttt{-p} option as a matter of course, as otherwise it will try to
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
636 do clever things with prefixes of file names that inevitably confuse
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
637 at least me.)
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
638
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
639 The \package{patchutils} package~\cite{web:patchutils} is invaluable.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
640 It provides a set of small utilities that follow the ``Unix
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
641 philosophy;'' each does one useful thing with a patch. The
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
642 \package{patchutils} command I use most is \command{filterdiff}, which
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
643 extracts subsets from a patch file. For example, given a patch that
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
644 modifies hundreds of files across dozens of directories, a single
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
645 invocation of \command{filterdiff} can generate a smaller patch that
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
646 only touches files whose names match a particular glob pattern.
81454425eee9 Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents: 15
diff changeset
647
1
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
648 %%% Local Variables:
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
649 %%% mode: latex
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
650 %%% TeX-master: "00book"
04e469de601e Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
651 %%% End: