Mercurial > hgbook
annotate en/mq-collab.tex @ 104:32bf9a5f22c0
Refactor MQ chapter into three.
Start text on guards.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri, 20 Oct 2006 16:56:20 -0700 |
parents | |
children | ecacb6b4c9fd |
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} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
2 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 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
|
4 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
|
5 capabilities makes it possible to work in complicated development |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
6 environments. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
7 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
8 In this chapter, I will discuss a technique I have developed to manage |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
9 the development of an Infiniband device driver for the Linux kernel. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
10 The driver in question is large (at least as drivers go), with 25,000 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
11 lines of code spread across 35 source files. It is maintained by a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
12 small team of developers. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
13 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
14 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
|
15 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
|
16 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
|
17 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
18 \section{The problem of many targets} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
19 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
20 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
|
21 stable; developers frequently make drastic changes between releases. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
22 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
|
23 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
|
24 correctly against, typically, any other version. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
25 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
26 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
|
27 Linux in mind. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
28 \begin{itemize} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
29 \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
|
30 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
|
31 developers in the kernel community, who make ``drive-by'' |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
32 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
|
33 subsystems. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
34 \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
|
35 the Linux kernel, to support the needs of customers who are running |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
36 older Linux distributions that do not incorporate our drivers. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
37 \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
|
38 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
|
39 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
|
40 without forcing them to upgrade their entire kernels or |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
41 distributions. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
42 \end{itemize} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
43 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 \subsection{Tempting approaches that don't work well} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
45 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
46 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
|
47 has to target many different environments. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
48 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
49 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
|
50 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
|
51 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
|
52 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
|
53 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
|
54 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
|
55 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
|
56 probably stop the driver from compiling. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
57 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
58 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
|
59 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
|
60 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
|
61 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
|
62 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
|
63 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
|
64 difficult to understand and maintain. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
65 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
66 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
|
67 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
|
68 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
|
69 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
|
70 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
|
71 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
|
72 after the changes show up in Linus's tree. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
73 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
74 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
|
75 generate well-formed patches to submit upstream. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
76 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
77 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
|
78 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
|
79 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
|
80 pleasant. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
81 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
82 \section{Conditionally applying patches with guards} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
83 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
84 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
|
85 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
|
86 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
|
87 \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
|
88 create a simple repository for experimenting in. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
89 \interaction{mq.guards.init} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
90 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
|
91 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
|
92 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
93 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
|
94 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
|
95 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
|
96 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
|
97 depending on the guards that you have selected. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
98 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
99 A patch can have an arbitrary number of guards; |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
100 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
|
101 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
|
102 selected''). A patch with no guards is always applied. |
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 \section{Controlling the guards on a patch} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
105 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
106 The \hgcmd{qguard} command lets you determine which guards should |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
107 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
|
108 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
|
109 patch. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
110 \interaction{mq.guards.qguard} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
111 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
|
112 a ``\texttt{+}''. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
113 \interaction{mq.guards.qguard.pos} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
114 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
|
115 a ``\texttt{-}''. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
116 \interaction{mq.guards.qguard.neg} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
117 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
118 \begin{note} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
119 The \hgcmd{qguard} command \emph{sets} the guards on a patch; it |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
120 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
|
121 \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
|
122 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
|
123 afterwards is \texttt{+c}. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
124 \end{note} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
125 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
126 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
|
127 which they are stored is easy both to understand and to edit by hand. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
128 (In other words, you don't have to use the \hgcmd{qguard} command if |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
129 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
|
130 file.) |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
131 \interaction{mq.guards.series} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
132 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
133 \section{Selecting the guards to use} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
134 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
135 The \hgcmd{qselect} command determines which guards are active at a |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
136 given time. The effect of this is to determine which patches MQ will |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
137 apply the next time you run \hgcmd{qpush}. It has no other effect; in |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
138 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
|
139 applied. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
140 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
141 With no arguments, the \hgcmd{qselect} command lists the guards |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
142 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
|
143 as the name of a guard to apply. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
144 \interaction{mq.guards.qselect.foo} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
145 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
|
146 the \sfilename{guards} file. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
147 \interaction{mq.guards.qselect.cat} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
148 We can see the effect the selected guards have when we run |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
149 \hgcmd{qpush}. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
150 \interaction{mq.guards.qselect.qpush} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
151 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
152 A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 character. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
154 \interaction{mq.guards.qselect.error} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
155 Changing the selected guards changes the patches that are applied. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
156 \interaction{mq.guards.qselect.quux} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
157 You can see here that negative guards take precedence over positive |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
158 guards. |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
159 \interaction{mq.guards.qselect.foobar} |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
160 |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
161 %%% Local Variables: |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
162 %%% mode: latex |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
163 %%% TeX-master: "00book" |
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
164 %%% End: |