annotate en/mq.tex @ 37:9fd0c59b009a

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