Mercurial > hgbook
annotate en/mq-collab.tex @ 304:e87fe9497b27
add progress percentage to todo.txt
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Sat, 09 Feb 2008 00:23:15 +0900 |
parents | 8627f718517a |
children | 5561812fc5c9 |
rev | line source |
---|---|
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1 \chapter{Advanced uses of Mercurial Queues} |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
107
diff
changeset
|
2 \label{chap:mq-collab} |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 While it's easy to pick up straightforward uses of Mercurial Queues, |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
5 use of a little discipline and some of MQ's less frequently used |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
6 capabilities makes it possible to work in complicated development |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
7 environments. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
8 |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
9 In this chapter, I will use as an example a technique I have used to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
10 manage the development of an Infiniband device driver for the Linux |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
11 kernel. The driver in question is large (at least as drivers go), |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
12 with 25,000 lines of code spread across 35 source files. It is |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
13 maintained by a small team of developers. |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
14 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
15 While much of the material in this chapter is specific to Linux, the |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
16 same principles apply to any code base for which you're not the |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
17 primary owner, and upon which you need to do a lot of development. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
18 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
19 \section{The problem of many targets} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
20 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
21 The Linux kernel changes rapidly, and has never been internally |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
22 stable; developers frequently make drastic changes between releases. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
23 This means that a version of the driver that works well with a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
24 particular released version of the kernel will not even \emph{compile} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
25 correctly against, typically, any other version. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
26 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
27 To maintain a driver, we have to keep a number of distinct versions of |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
28 Linux in mind. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
29 \begin{itemize} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
30 \item One target is the main Linux kernel development tree. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
31 Maintenance of the code is in this case partly shared by other |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
32 developers in the kernel community, who make ``drive-by'' |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
33 modifications to the driver as they develop and refine kernel |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
34 subsystems. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
35 \item We also maintain a number of ``backports'' to older versions of |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
36 the Linux kernel, to support the needs of customers who are running |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
37 older Linux distributions that do not incorporate our drivers. (To |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
38 \emph{backport} a piece of code is to modify it to work in an older |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
39 version of its target environment than the version it was developed |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
40 for.) |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
41 \item Finally, we make software releases on a schedule that is |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
42 necessarily not aligned with those used by Linux distributors and |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
43 kernel developers, so that we can deliver new features to customers |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 without forcing them to upgrade their entire kernels or |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
45 distributions. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
46 \end{itemize} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
47 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
48 \subsection{Tempting approaches that don't work well} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
49 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
50 There are two ``standard'' ways to maintain a piece of software that |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
51 has to target many different environments. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
52 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
53 The first is to maintain a number of branches, each intended for a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
54 single target. The trouble with this approach is that you must |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
55 maintain iron discipline in the flow of changes between repositories. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
56 A new feature or bug fix must start life in a ``pristine'' repository, |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
57 then percolate out to every backport repository. Backport changes are |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
58 more limited in the branches they should propagate to; a backport |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
59 change that is applied to a branch where it doesn't belong will |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
60 probably stop the driver from compiling. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
61 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
62 The second is to maintain a single source tree filled with conditional |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
63 statements that turn chunks of code on or off depending on the |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
64 intended target. Because these ``ifdefs'' are not allowed in the |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
65 Linux kernel tree, a manual or automatic process must be followed to |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
66 strip them out and yield a clean tree. A code base maintained in this |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
67 fashion rapidly becomes a rat's nest of conditional blocks that are |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
68 difficult to understand and maintain. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
69 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
70 Neither of these approaches is well suited to a situation where you |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
71 don't ``own'' the canonical copy of a source tree. In the case of a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
72 Linux driver that is distributed with the standard kernel, Linus's |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
73 tree contains the copy of the code that will be treated by the world |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
74 as canonical. The upstream version of ``my'' driver can be modified |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
75 by people I don't know, without me even finding out about it until |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
76 after the changes show up in Linus's tree. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
77 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
78 These approaches have the added weakness of making it difficult to |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
79 generate well-formed patches to submit upstream. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
80 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
81 In principle, Mercurial Queues seems like a good candidate to manage a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
82 development scenario such as the above. While this is indeed the |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
83 case, MQ contains a few added features that make the job more |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
84 pleasant. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
85 |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
86 \section{Conditionally applying patches with |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
87 guards} |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
88 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
89 Perhaps the best way to maintain sanity with so many targets is to be |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
90 able to choose specific patches to apply for a given situation. MQ |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
91 provides a feature called ``guards'' (which originates with quilt's |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
92 \texttt{guards} command) that does just this. To start off, let's |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
93 create a simple repository for experimenting in. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
94 \interaction{mq.guards.init} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
95 This gives us a tiny repository that contains two patches that don't |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
96 have any dependencies on each other, because they touch different files. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
97 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
98 The idea behind conditional application is that you can ``tag'' a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
99 patch with a \emph{guard}, which is simply a text string of your |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
100 choosing, then tell MQ to select specific guards to use when applying |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
101 patches. MQ will then either apply, or skip over, a guarded patch, |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
102 depending on the guards that you have selected. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
103 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
104 A patch can have an arbitrary number of guards; |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
105 each one is \emph{positive} (``apply this patch if this guard is |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
106 selected'') or \emph{negative} (``skip this patch if this guard is |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
107 selected''). A patch with no guards is always applied. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
108 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
109 \section{Controlling the guards on a patch} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
110 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
111 The \hgxcmd{mq}{qguard} command lets you determine which guards should |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
112 apply to a patch, or display the guards that are already in effect. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
113 Without any arguments, it displays the guards on the current topmost |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
114 patch. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
115 \interaction{mq.guards.qguard} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
116 To set a positive guard on a patch, prefix the name of the guard with |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
117 a ``\texttt{+}''. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
118 \interaction{mq.guards.qguard.pos} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
119 To set a negative guard on a patch, prefix the name of the guard with |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
120 a ``\texttt{-}''. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
121 \interaction{mq.guards.qguard.neg} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
122 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
123 \begin{note} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
124 The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
125 doesn't \emph{modify} them. What this means is that if you run |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
126 \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
127 the same patch, the \emph{only} guard that will be set on it |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
128 afterwards is \texttt{+c}. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
129 \end{note} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
130 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
131 Mercurial stores guards in the \sfilename{series} file; the form in |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
132 which they are stored is easy both to understand and to edit by hand. |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
133 (In other words, you don't have to use the \hgxcmd{mq}{qguard} command if |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
134 you don't want to; it's okay to simply edit the \sfilename{series} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
135 file.) |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
136 \interaction{mq.guards.series} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
137 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
138 \section{Selecting the guards to use} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
139 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
140 The \hgxcmd{mq}{qselect} command determines which guards are active at a |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
141 given time. The effect of this is to determine which patches MQ will |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
142 apply the next time you run \hgxcmd{mq}{qpush}. It has no other effect; in |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
143 particular, it doesn't do anything to patches that are already |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
144 applied. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
145 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
146 With no arguments, the \hgxcmd{mq}{qselect} command lists the guards |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
147 currently in effect, one per line of output. Each argument is treated |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
148 as the name of a guard to apply. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
149 \interaction{mq.guards.qselect.foo} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
150 In case you're interested, the currently selected guards are stored in |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
151 the \sfilename{guards} file. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
152 \interaction{mq.guards.qselect.cat} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 We can see the effect the selected guards have when we run |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
154 \hgxcmd{mq}{qpush}. |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
155 \interaction{mq.guards.qselect.qpush} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
156 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
157 A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
158 character. The name of a guard must not contain white space, but most |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
159 othter characters are acceptable. If you try to use a guard with an |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
160 invalid name, MQ will complain: |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
161 \interaction{mq.guards.qselect.error} |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
162 Changing the selected guards changes the patches that are applied. |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
163 \interaction{mq.guards.qselect.quux} |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
164 You can see in the example below that negative guards take precedence |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
165 over positive guards. |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
166 \interaction{mq.guards.qselect.foobar} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
167 |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
168 \section{MQ's rules for applying patches} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
169 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
170 The rules that MQ uses when deciding whether to apply a patch |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
171 are as follows. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
172 \begin{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
173 \item A patch that has no guards is always applied. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
174 \item If the patch has any negative guard that matches any currently |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
175 selected guard, the patch is skipped. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
176 \item If the patch has any positive guard that matches any currently |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
177 selected guard, the patch is applied. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
178 \item If the patch has positive or negative guards, but none matches |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
179 any currently selected guard, the patch is skipped. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
180 \end{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
181 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
182 \section{Trimming the work environment} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
183 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
184 In working on the device driver I mentioned earlier, I don't apply the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
185 patches to a normal Linux kernel tree. Instead, I use a repository |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
186 that contains only a snapshot of the source files and headers that are |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
187 relevant to Infiniband development. This repository is~1\% the size |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
188 of a kernel repository, so it's easier to work with. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
189 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
190 I then choose a ``base'' version on top of which the patches are |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
191 applied. This is a snapshot of the Linux kernel tree as of a revision |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
192 of my choosing. When I take the snapshot, I record the changeset ID |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
193 from the kernel repository in the commit message. Since the snapshot |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
194 preserves the ``shape'' and content of the relevant parts of the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
195 kernel tree, I can apply my patches on top of either my tiny |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
196 repository or a normal kernel tree. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
197 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
198 Normally, the base tree atop which the patches apply should be a |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
199 snapshot of a very recent upstream tree. This best facilitates the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
200 development of patches that can easily be submitted upstream with few |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
201 or no modifications. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
202 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
203 \section{Dividing up the \sfilename{series} file} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
204 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
205 I categorise the patches in the \sfilename{series} file into a number |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
206 of logical groups. Each section of like patches begins with a block |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
207 of comments that describes the purpose of the patches that follow. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
208 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
209 The sequence of patch groups that I maintain follows. The ordering of |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
210 these groups is important; I'll describe why after I introduce the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
211 groups. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
212 \begin{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
213 \item The ``accepted'' group. Patches that the development team has |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
214 submitted to the maintainer of the Infiniband subsystem, and which |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
215 he has accepted, but which are not present in the snapshot that the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
216 tiny repository is based on. These are ``read only'' patches, |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
217 present only to transform the tree into a similar state as it is in |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
218 the upstream maintainer's repository. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
219 \item The ``rework'' group. Patches that I have submitted, but that |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
220 the upstream maintainer has requested modifications to before he |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
221 will accept them. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
222 \item The ``pending'' group. Patches that I have not yet submitted to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
223 the upstream maintainer, but which we have finished working on. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
224 These will be ``read only'' for a while. If the upstream maintainer |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
225 accepts them upon submission, I'll move them to the end of the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
226 ``accepted'' group. If he requests that I modify any, I'll move |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
227 them to the beginning of the ``rework'' group. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
228 \item The ``in progress'' group. Patches that are actively being |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
229 developed, and should not be submitted anywhere yet. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
230 \item The ``backport'' group. Patches that adapt the source tree to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
231 older versions of the kernel tree. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
232 \item The ``do not ship'' group. Patches that for some reason should |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
233 never be submitted upstream. For example, one such patch might |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
234 change embedded driver identification strings to make it easier to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
235 distinguish, in the field, between an out-of-tree version of the |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
236 driver and a version shipped by a distribution vendor. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
237 \end{itemize} |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
238 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
239 Now to return to the reasons for ordering groups of patches in this |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
240 way. We would like the lowest patches in the stack to be as stable as |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
241 possible, so that we will not need to rework higher patches due to |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
242 changes in context. Putting patches that will never be changed first |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
243 in the \sfilename{series} file serves this purpose. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
244 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
245 We would also like the patches that we know we'll need to modify to be |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
246 applied on top of a source tree that resembles the upstream tree as |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
247 closely as possible. This is why we keep accepted patches around for |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
248 a while. |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
249 |
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
250 The ``backport'' and ``do not ship'' patches float at the end of the |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
251 \sfilename{series} file. The backport patches must be applied on top |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
252 of all other patches, and the ``do not ship'' patches might as well |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
253 stay out of harm's way. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
254 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
255 \section{Maintaining the patch series} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
256 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
257 In my work, I use a number of guards to control which patches are to |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
258 be applied. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
259 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
260 \begin{itemize} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
261 \item ``Accepted'' patches are guarded with \texttt{accepted}. I |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
262 enable this guard most of the time. When I'm applying the patches |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
263 on top of a tree where the patches are already present, I can turn |
271 | 264 this patch off, and the patches that follow it will apply cleanly. |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
265 \item Patches that are ``finished'', but not yet submitted, have no |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
266 guards. If I'm applying the patch stack to a copy of the upstream |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
267 tree, I don't need to enable any guards in order to get a reasonably |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
268 safe source tree. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
269 \item Those patches that need reworking before being resubmitted are |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
270 guarded with \texttt{rework}. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
271 \item For those patches that are still under development, I use |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
272 \texttt{devel}. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
273 \item A backport patch may have several guards, one for each version |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
274 of the kernel to which it applies. For example, a patch that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
275 backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
276 \end{itemize} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
277 This variety of guards gives me considerable flexibility in |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
278 qdetermining what kind of source tree I want to end up with. For most |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
279 situations, the selection of appropriate guards is automated during |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
280 the build process, but I can manually tune the guards to use for less |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
281 common circumstances. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
282 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
283 \subsection{The art of writing backport patches} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
284 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
285 Using MQ, writing a backport patch is a simple process. All such a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
286 patch has to do is modify a piece of code that uses a kernel feature |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
287 not present in the older version of the kernel, so that the driver |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
288 continues to work correctly under that older version. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
289 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
290 A useful goal when writing a good backport patch is to make your code |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
291 look as if it was written for the older version of the kernel you're |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
292 targeting. The less obtrusive the patch, the easier it will be to |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
293 understand and maintain. If you're writing a collection of backport |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
294 patches to avoid the ``rat's nest'' effect of lots of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
295 \texttt{\#ifdef}s (hunks of source code that are only used |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
296 conditionally) in your code, don't introduce version-dependent |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
297 \texttt{\#ifdef}s into the patches. Instead, write several patches, |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
298 each of which makes unconditional changes, and control their |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
299 application using guards. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
300 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
301 There are two reasons to divide backport patches into a distinct |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
302 group, away from the ``regular'' patches whose effects they modify. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
303 The first is that intermingling the two makes it more difficult to use |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
304 a tool like the \hgext{patchbomb} extension to automate the process of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
305 submitting the patches to an upstream maintainer. The second is that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
306 a backport patch could perturb the context in which a subsequent |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
307 regular patch is applied, making it impossible to apply the regular |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
308 patch cleanly \emph{without} the earlier backport patch already being |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
309 applied. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
310 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
311 \section{Useful tips for developing with MQ} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
312 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
313 \subsection{Organising patches in directories} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
314 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
315 If you're working on a substantial project with MQ, it's not difficult |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
316 to accumulate a large number of patches. For example, I have one |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
317 patch repository that contains over 250 patches. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
318 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
319 If you can group these patches into separate logical categories, you |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
320 can if you like store them in different directories; MQ has no |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
321 problems with patch names that contain path separators. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
322 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
323 \subsection{Viewing the history of a patch} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
324 \label{mq-collab:tips:interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
325 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
326 If you're developing a set of patches over a long time, it's a good |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
327 idea to maintain them in a repository, as discussed in |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
328 section~\ref{sec:mq:repo}. If you do so, you'll quickly discover that |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
329 using the \hgcmd{diff} command to look at the history of changes to a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
330 patch is unworkable. This is in part because you're looking at the |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
331 second derivative of the real code (a diff of a diff), but also |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
332 because MQ adds noise to the process by modifying time stamps and |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
333 directory names when it updates a patch. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
334 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
335 However, you can use the \hgext{extdiff} extension, which is bundled |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
336 with Mercurial, to turn a diff of two versions of a patch into |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
337 something readable. To do this, you will need a third-party package |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
338 called \package{patchutils}~\cite{web:patchutils}. This provides a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
339 command named \command{interdiff}, which shows the differences between |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
340 two diffs as a diff. Used on two versions of the same diff, it |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
341 generates a diff that represents the diff from the first to the second |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
342 version. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
343 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
344 You can enable the \hgext{extdiff} extension in the usual way, by |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
345 adding a line to the \rcsection{extensions} section of your \hgrc. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
346 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
347 [extensions] |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
348 extdiff = |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
349 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
350 The \command{interdiff} command expects to be passed the names of two |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
351 files, but the \hgext{extdiff} extension passes the program it runs a |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
352 pair of directories, each of which can contain an arbitrary number of |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
353 files. We thus need a small program that will run \command{interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
354 on each pair of files in these two directories. This program is |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
355 available as \sfilename{hg-interdiff} in the \dirname{examples} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
356 directory of the source code repository that accompanies this book. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
357 \excode{hg-interdiff} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
358 |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
359 With the \sfilename{hg-interdiff} program in your shell's search path, |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
360 you can run it as follows, from inside an MQ patch directory: |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
361 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
362 hg extdiff -p hg-interdiff -r A:B my-change.patch |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
363 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
364 Since you'll probably want to use this long-winded command a lot, you |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
365 can get \hgext{hgext} to make it available as a normal Mercurial |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
366 command, again by editing your \hgrc. |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
367 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
368 [extdiff] |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
369 cmd.interdiff = hg-interdiff |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
370 \end{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
371 This directs \hgext{hgext} to make an \texttt{interdiff} command |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
372 available, so you can now shorten the previous invocation of |
238 | 373 \hgxcmd{extdiff}{extdiff} to something a little more wieldy. |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
374 \begin{codesample2} |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
375 hg interdiff -r A:B my-change.patch |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
105
diff
changeset
|
376 \end{codesample2} |
105
ecacb6b4c9fd
Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
377 |
107
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
378 \begin{note} |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
379 The \command{interdiff} command works well only if the underlying |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
380 files against which versions of a patch are generated remain the |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
381 same. If you create a patch, modify the underlying files, and then |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
382 regenerate the patch, \command{interdiff} may not produce useful |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
383 output. |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
384 \end{note} |
a0d7e11db169
A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
385 |
240
4119e57679f7
Twiddle wording trivially.
Bryan O'Sullivan <bos@serpentine.com>
parents:
239
diff
changeset
|
386 The \hgext{extdiff} extension is useful for more than merely improving |
239
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
387 the presentation of MQ~patches. To read more about it, go to |
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
388 section~\ref{sec:hgext:extdiff}. |
fe8598eb99c4
Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
238
diff
changeset
|
389 |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
390 %%% Local Variables: |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
391 %%% mode: latex |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
392 %%% TeX-master: "00book" |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
393 %%% End: |