Mercurial > hgbook
annotate es/mq-collab.tex @ 584:039ed6f5935b
translated a section
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Mon, 05 Jan 2009 23:55:35 -0500 |
parents | 6cf30b3ed48f |
children | b1ae672fd92b |
rev | line source |
---|---|
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
1 \chapter{Usos avanzados de las Colas de Mercurial} |
435 | 2 \label{chap:mq-collab} |
3 | |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
4 Auunque es fácil aprender los usos más directos de las Colas de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
5 Mercurial, tener algo de disciplina junto con algunas de las |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
6 capacidadees menos usadas de MQ hace posible trabajar en entornos de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
7 desarrollo complejos. |
435 | 8 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
9 En este capítulo, usaré como ejemplo una técnica que he usado para |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
10 administrar el desarrollo de un controlador de dispositivo Infiniband |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
11 para el kernel de Linux. El controlador en cuestión es grande |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
12 (al menos en lo que se refiere a controladores), con 25,000 líneas de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
13 código esparcidas en 35 ficheros fuente. Es mantenido por un equipo |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
14 pequeño de desarrolladores. |
435 | 15 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
16 Aunque mucho del material en este capítulo es específico de Linux, los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
17 mismos principios aplican a cualquier base de código de la que usted |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
18 no sea el propietario principal, y sobre la que usted necesita hacer |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
19 un montón de desarrollo. |
435 | 20 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
21 \section{El problema de múltiples objetivos} |
435 | 22 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
23 El kernel de Linux cambia con rapidez, y nunca ha sido estable |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
24 internamente; los desarrolladores hacen cambios drásticos entre |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
25 %TODO no encontré una traducción adecuada para "release". Por eso el |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
26 %cambio |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
27 versiones frecuentemente. Esto significa que una versión del |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
28 controlador que funciona bien con una versión particular del kernel ni |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
29 siquiera \emph{compilará} correctamente contra, típicamente, cualquier |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
30 otra versión. |
435 | 31 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
32 Para mantener un controlador, debemos tener en cuenta una buena |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
33 cantidad de versiones de Linux en mente. |
435 | 34 \begin{itemize} |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
35 \item Un objetivo es el árbol de desarrollo principal del kernel de |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
36 Linux. En este caso el mantenimiento del código es compartido |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
37 parcialmente por otros desarrolladores en la comunidad del kernel, |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
38 %TODO drive-by. |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
39 quienes hacen modificaciones ``de-afán'' al controlador a medida que |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
40 desarrollan y refinan subsistemas en el kernel. |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
41 %TODO backport |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
42 \item También mantenemos algunos ``backports'' para versiones antiguas |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
43 del kernel de Linux, para dar soporte a las necesidades de los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
44 clientes que están corriendo versiones antiguas de Linux que no |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
45 incorporan nuestros controladores. (Hacer el \emph{backport} de un |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
46 pedazo de código es modificarlo para que trabaje en una versión |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
47 de su entorno objetivo anterior a aquella para la cual fue escrito.) |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
48 \item Finalmente, nosotros liberamos nuestro software de acuerdo a un |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
49 cronograma que no necesariamente está alineado con el que usan los |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
50 distribuidores de Linux y los desarrolladores del kernel, así que |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
51 podemos entregar nuevas características a los clientes sin forzarlos |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
52 a actualizar kernels completos o distribuciones. |
435 | 53 \end{itemize} |
54 | |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
55 \subsection{Aproximaciones tentadoras que no funcionan adecuadamente} |
435 | 56 |
580
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
57 Hay dos maneras estándar de mantener una porción de software que debe |
6cf30b3ed48f
translated some paragraphs
Javier Rojas <jerojasro@devnull.li>
parents:
435
diff
changeset
|
58 funcionar en muchos entornos diferentes. |
435 | 59 |
584 | 60 La primera es mantener varias ramas, cada una pensada para un único |
61 entorno. El problema de esta aproximación es que usted debe tener una | |
62 disciplina férrea con el flujo de cambios entre repositorios. Una | |
63 nueva característica o un arreglo de fallo deben empezar su vida en un | |
64 repositorio ``prístino'', y luego propagarse a cada repositorio de | |
65 backport. Los cambios para backports están más limitados respecto a | |
66 las ramas a las que deberían propagarse; un cambio para backport que | |
67 es aplicado a una rama en la que no corresponde probablemente hará que | |
68 el controlador no compile. | |
69 | |
70 La segunda es mantener un único árbol de código fuente lleno de | |
71 declaraciones que activen o desactiven secciones de código dependiendo | |
72 del entorno objetivo. Ya que estos ``ifdefs'' no están permitidos en | |
73 el árbol del kernel de Linux, debe seguirse algún proceso manual o | |
74 automático para eliminarlos y producir un árbol limpio. Una base de | |
75 código mantenida de esta manera se convierte rápidamente en un nido de | |
76 ratas de bloques condicionales que son difíciles de entender y | |
77 mantener. | |
435 | 78 |
584 | 79 %TODO canónica? |
80 Ninguno de estos enfoques es adecuado para situaciones en las que | |
81 usted no es ``dueño'' de la copia canónica de un árbol de fuentes. En | |
82 el caso de un controlador de Linux que es distribuido con el kernel | |
83 estándar, el árbol de Linux contiene la copia del código que será | |
84 considerada por el mundo como la canónica. La versión oficial de | |
85 ``mi'' controlador puede ser modificada por gente que no conozco, sin | |
86 que yo siquiera me entere de ello hasta después de que los cambios | |
87 aparecen en el árbol de Linus. | |
435 | 88 |
584 | 89 Estos enfoques tienen la debilidad adicional de dificultar la |
90 %TODO upstream. no no es río arriba | |
91 generación de parches bien formados para enviarlos a la versión | |
92 oficial. | |
435 | 93 |
584 | 94 En principio, las Colas de Mercurial parecen ser un buen candidato |
95 para administrar un escenario de desarrollo como el de arriba. Aunque | |
96 este es de hecho el caso, MQ tiene unas cuantas características | |
97 adicionales que hacen el trabajo más agradable. | |
435 | 98 |
99 \section{Conditionally applying patches with | |
100 guards} | |
101 | |
102 Perhaps the best way to maintain sanity with so many targets is to be | |
103 able to choose specific patches to apply for a given situation. MQ | |
104 provides a feature called ``guards'' (which originates with quilt's | |
105 \texttt{guards} command) that does just this. To start off, let's | |
106 create a simple repository for experimenting in. | |
107 \interaction{mq.guards.init} | |
108 This gives us a tiny repository that contains two patches that don't | |
109 have any dependencies on each other, because they touch different files. | |
110 | |
111 The idea behind conditional application is that you can ``tag'' a | |
112 patch with a \emph{guard}, which is simply a text string of your | |
113 choosing, then tell MQ to select specific guards to use when applying | |
114 patches. MQ will then either apply, or skip over, a guarded patch, | |
115 depending on the guards that you have selected. | |
116 | |
117 A patch can have an arbitrary number of guards; | |
118 each one is \emph{positive} (``apply this patch if this guard is | |
119 selected'') or \emph{negative} (``skip this patch if this guard is | |
120 selected''). A patch with no guards is always applied. | |
121 | |
122 \section{Controlling the guards on a patch} | |
123 | |
124 The \hgxcmd{mq}{qguard} command lets you determine which guards should | |
125 apply to a patch, or display the guards that are already in effect. | |
126 Without any arguments, it displays the guards on the current topmost | |
127 patch. | |
128 \interaction{mq.guards.qguard} | |
129 To set a positive guard on a patch, prefix the name of the guard with | |
130 a ``\texttt{+}''. | |
131 \interaction{mq.guards.qguard.pos} | |
132 To set a negative guard on a patch, prefix the name of the guard with | |
133 a ``\texttt{-}''. | |
134 \interaction{mq.guards.qguard.neg} | |
135 | |
136 \begin{note} | |
137 The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it | |
138 doesn't \emph{modify} them. What this means is that if you run | |
139 \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on | |
140 the same patch, the \emph{only} guard that will be set on it | |
141 afterwards is \texttt{+c}. | |
142 \end{note} | |
143 | |
144 Mercurial stores guards in the \sfilename{series} file; the form in | |
145 which they are stored is easy both to understand and to edit by hand. | |
146 (In other words, you don't have to use the \hgxcmd{mq}{qguard} command if | |
147 you don't want to; it's okay to simply edit the \sfilename{series} | |
148 file.) | |
149 \interaction{mq.guards.series} | |
150 | |
151 \section{Selecting the guards to use} | |
152 | |
153 The \hgxcmd{mq}{qselect} command determines which guards are active at a | |
154 given time. The effect of this is to determine which patches MQ will | |
155 apply the next time you run \hgxcmd{mq}{qpush}. It has no other effect; in | |
156 particular, it doesn't do anything to patches that are already | |
157 applied. | |
158 | |
159 With no arguments, the \hgxcmd{mq}{qselect} command lists the guards | |
160 currently in effect, one per line of output. Each argument is treated | |
161 as the name of a guard to apply. | |
162 \interaction{mq.guards.qselect.foo} | |
163 In case you're interested, the currently selected guards are stored in | |
164 the \sfilename{guards} file. | |
165 \interaction{mq.guards.qselect.cat} | |
166 We can see the effect the selected guards have when we run | |
167 \hgxcmd{mq}{qpush}. | |
168 \interaction{mq.guards.qselect.qpush} | |
169 | |
170 A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' | |
171 character. The name of a guard must not contain white space, but most | |
172 other characters are acceptable. If you try to use a guard with an | |
173 invalid name, MQ will complain: | |
174 \interaction{mq.guards.qselect.error} | |
175 Changing the selected guards changes the patches that are applied. | |
176 \interaction{mq.guards.qselect.quux} | |
177 You can see in the example below that negative guards take precedence | |
178 over positive guards. | |
179 \interaction{mq.guards.qselect.foobar} | |
180 | |
181 \section{MQ's rules for applying patches} | |
182 | |
183 The rules that MQ uses when deciding whether to apply a patch | |
184 are as follows. | |
185 \begin{itemize} | |
186 \item A patch that has no guards is always applied. | |
187 \item If the patch has any negative guard that matches any currently | |
188 selected guard, the patch is skipped. | |
189 \item If the patch has any positive guard that matches any currently | |
190 selected guard, the patch is applied. | |
191 \item If the patch has positive or negative guards, but none matches | |
192 any currently selected guard, the patch is skipped. | |
193 \end{itemize} | |
194 | |
195 \section{Trimming the work environment} | |
196 | |
197 In working on the device driver I mentioned earlier, I don't apply the | |
198 patches to a normal Linux kernel tree. Instead, I use a repository | |
199 that contains only a snapshot of the source files and headers that are | |
200 relevant to Infiniband development. This repository is~1\% the size | |
201 of a kernel repository, so it's easier to work with. | |
202 | |
203 I then choose a ``base'' version on top of which the patches are | |
204 applied. This is a snapshot of the Linux kernel tree as of a revision | |
205 of my choosing. When I take the snapshot, I record the changeset ID | |
206 from the kernel repository in the commit message. Since the snapshot | |
207 preserves the ``shape'' and content of the relevant parts of the | |
208 kernel tree, I can apply my patches on top of either my tiny | |
209 repository or a normal kernel tree. | |
210 | |
211 Normally, the base tree atop which the patches apply should be a | |
212 snapshot of a very recent upstream tree. This best facilitates the | |
213 development of patches that can easily be submitted upstream with few | |
214 or no modifications. | |
215 | |
216 \section{Dividing up the \sfilename{series} file} | |
217 | |
218 I categorise the patches in the \sfilename{series} file into a number | |
219 of logical groups. Each section of like patches begins with a block | |
220 of comments that describes the purpose of the patches that follow. | |
221 | |
222 The sequence of patch groups that I maintain follows. The ordering of | |
223 these groups is important; I'll describe why after I introduce the | |
224 groups. | |
225 \begin{itemize} | |
226 \item The ``accepted'' group. Patches that the development team has | |
227 submitted to the maintainer of the Infiniband subsystem, and which | |
228 he has accepted, but which are not present in the snapshot that the | |
229 tiny repository is based on. These are ``read only'' patches, | |
230 present only to transform the tree into a similar state as it is in | |
231 the upstream maintainer's repository. | |
232 \item The ``rework'' group. Patches that I have submitted, but that | |
233 the upstream maintainer has requested modifications to before he | |
234 will accept them. | |
235 \item The ``pending'' group. Patches that I have not yet submitted to | |
236 the upstream maintainer, but which we have finished working on. | |
237 These will be ``read only'' for a while. If the upstream maintainer | |
238 accepts them upon submission, I'll move them to the end of the | |
239 ``accepted'' group. If he requests that I modify any, I'll move | |
240 them to the beginning of the ``rework'' group. | |
241 \item The ``in progress'' group. Patches that are actively being | |
242 developed, and should not be submitted anywhere yet. | |
243 \item The ``backport'' group. Patches that adapt the source tree to | |
244 older versions of the kernel tree. | |
245 \item The ``do not ship'' group. Patches that for some reason should | |
246 never be submitted upstream. For example, one such patch might | |
247 change embedded driver identification strings to make it easier to | |
248 distinguish, in the field, between an out-of-tree version of the | |
249 driver and a version shipped by a distribution vendor. | |
250 \end{itemize} | |
251 | |
252 Now to return to the reasons for ordering groups of patches in this | |
253 way. We would like the lowest patches in the stack to be as stable as | |
254 possible, so that we will not need to rework higher patches due to | |
255 changes in context. Putting patches that will never be changed first | |
256 in the \sfilename{series} file serves this purpose. | |
257 | |
258 We would also like the patches that we know we'll need to modify to be | |
259 applied on top of a source tree that resembles the upstream tree as | |
260 closely as possible. This is why we keep accepted patches around for | |
261 a while. | |
262 | |
263 The ``backport'' and ``do not ship'' patches float at the end of the | |
264 \sfilename{series} file. The backport patches must be applied on top | |
265 of all other patches, and the ``do not ship'' patches might as well | |
266 stay out of harm's way. | |
267 | |
268 \section{Maintaining the patch series} | |
269 | |
270 In my work, I use a number of guards to control which patches are to | |
271 be applied. | |
272 | |
273 \begin{itemize} | |
274 \item ``Accepted'' patches are guarded with \texttt{accepted}. I | |
275 enable this guard most of the time. When I'm applying the patches | |
276 on top of a tree where the patches are already present, I can turn | |
277 this patch off, and the patches that follow it will apply cleanly. | |
278 \item Patches that are ``finished'', but not yet submitted, have no | |
279 guards. If I'm applying the patch stack to a copy of the upstream | |
280 tree, I don't need to enable any guards in order to get a reasonably | |
281 safe source tree. | |
282 \item Those patches that need reworking before being resubmitted are | |
283 guarded with \texttt{rework}. | |
284 \item For those patches that are still under development, I use | |
285 \texttt{devel}. | |
286 \item A backport patch may have several guards, one for each version | |
287 of the kernel to which it applies. For example, a patch that | |
288 backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard. | |
289 \end{itemize} | |
290 This variety of guards gives me considerable flexibility in | |
291 qdetermining what kind of source tree I want to end up with. For most | |
292 situations, the selection of appropriate guards is automated during | |
293 the build process, but I can manually tune the guards to use for less | |
294 common circumstances. | |
295 | |
296 \subsection{The art of writing backport patches} | |
297 | |
298 Using MQ, writing a backport patch is a simple process. All such a | |
299 patch has to do is modify a piece of code that uses a kernel feature | |
300 not present in the older version of the kernel, so that the driver | |
301 continues to work correctly under that older version. | |
302 | |
303 A useful goal when writing a good backport patch is to make your code | |
304 look as if it was written for the older version of the kernel you're | |
305 targeting. The less obtrusive the patch, the easier it will be to | |
306 understand and maintain. If you're writing a collection of backport | |
307 patches to avoid the ``rat's nest'' effect of lots of | |
308 \texttt{\#ifdef}s (hunks of source code that are only used | |
309 conditionally) in your code, don't introduce version-dependent | |
310 \texttt{\#ifdef}s into the patches. Instead, write several patches, | |
311 each of which makes unconditional changes, and control their | |
312 application using guards. | |
313 | |
314 There are two reasons to divide backport patches into a distinct | |
315 group, away from the ``regular'' patches whose effects they modify. | |
316 The first is that intermingling the two makes it more difficult to use | |
317 a tool like the \hgext{patchbomb} extension to automate the process of | |
318 submitting the patches to an upstream maintainer. The second is that | |
319 a backport patch could perturb the context in which a subsequent | |
320 regular patch is applied, making it impossible to apply the regular | |
321 patch cleanly \emph{without} the earlier backport patch already being | |
322 applied. | |
323 | |
324 \section{Useful tips for developing with MQ} | |
325 | |
326 \subsection{Organising patches in directories} | |
327 | |
328 If you're working on a substantial project with MQ, it's not difficult | |
329 to accumulate a large number of patches. For example, I have one | |
330 patch repository that contains over 250 patches. | |
331 | |
332 If you can group these patches into separate logical categories, you | |
333 can if you like store them in different directories; MQ has no | |
334 problems with patch names that contain path separators. | |
335 | |
336 \subsection{Viewing the history of a patch} | |
337 \label{mq-collab:tips:interdiff} | |
338 | |
339 If you're developing a set of patches over a long time, it's a good | |
340 idea to maintain them in a repository, as discussed in | |
341 section~\ref{sec:mq:repo}. If you do so, you'll quickly discover that | |
342 using the \hgcmd{diff} command to look at the history of changes to a | |
343 patch is unworkable. This is in part because you're looking at the | |
344 second derivative of the real code (a diff of a diff), but also | |
345 because MQ adds noise to the process by modifying time stamps and | |
346 directory names when it updates a patch. | |
347 | |
348 However, you can use the \hgext{extdiff} extension, which is bundled | |
349 with Mercurial, to turn a diff of two versions of a patch into | |
350 something readable. To do this, you will need a third-party package | |
351 called \package{patchutils}~\cite{web:patchutils}. This provides a | |
352 command named \command{interdiff}, which shows the differences between | |
353 two diffs as a diff. Used on two versions of the same diff, it | |
354 generates a diff that represents the diff from the first to the second | |
355 version. | |
356 | |
357 You can enable the \hgext{extdiff} extension in the usual way, by | |
358 adding a line to the \rcsection{extensions} section of your \hgrc. | |
359 \begin{codesample2} | |
360 [extensions] | |
361 extdiff = | |
362 \end{codesample2} | |
363 The \command{interdiff} command expects to be passed the names of two | |
364 files, but the \hgext{extdiff} extension passes the program it runs a | |
365 pair of directories, each of which can contain an arbitrary number of | |
366 files. We thus need a small program that will run \command{interdiff} | |
367 on each pair of files in these two directories. This program is | |
368 available as \sfilename{hg-interdiff} in the \dirname{examples} | |
369 directory of the source code repository that accompanies this book. | |
370 \excode{hg-interdiff} | |
371 | |
372 With the \sfilename{hg-interdiff} program in your shell's search path, | |
373 you can run it as follows, from inside an MQ patch directory: | |
374 \begin{codesample2} | |
375 hg extdiff -p hg-interdiff -r A:B my-change.patch | |
376 \end{codesample2} | |
377 Since you'll probably want to use this long-winded command a lot, you | |
378 can get \hgext{hgext} to make it available as a normal Mercurial | |
379 command, again by editing your \hgrc. | |
380 \begin{codesample2} | |
381 [extdiff] | |
382 cmd.interdiff = hg-interdiff | |
383 \end{codesample2} | |
384 This directs \hgext{hgext} to make an \texttt{interdiff} command | |
385 available, so you can now shorten the previous invocation of | |
386 \hgxcmd{extdiff}{extdiff} to something a little more wieldy. | |
387 \begin{codesample2} | |
388 hg interdiff -r A:B my-change.patch | |
389 \end{codesample2} | |
390 | |
391 \begin{note} | |
392 The \command{interdiff} command works well only if the underlying | |
393 files against which versions of a patch are generated remain the | |
394 same. If you create a patch, modify the underlying files, and then | |
395 regenerate the patch, \command{interdiff} may not produce useful | |
396 output. | |
397 \end{note} | |
398 | |
399 The \hgext{extdiff} extension is useful for more than merely improving | |
400 the presentation of MQ~patches. To read more about it, go to | |
401 section~\ref{sec:hgext:extdiff}. | |
402 | |
403 %%% Local Variables: | |
404 %%% mode: latex | |
405 %%% TeX-master: "00book" | |
406 %%% End: |