hgbook

annotate es/hgext.tex @ 451:f4904a9b4fdb

find changesets by author, revision, files, or words in the commit message
Started translating hgext
author Igor TAmara <igor@tamarapatino.org>
date Sat Dec 13 23:55:07 2008 -0500 (2008-12-13)
parents aeda195f54a6
children 3cb3f9b418ea
rev   line source
igor@440 1 \chapter{Añadir funcionalidad con extensiones}
jerojasro@336 2 \label{chap:hgext}
jerojasro@336 3
igor@451 4 A pesar de que el corazón de Mercurial es muy completo desde el punto
igor@451 5 de vista de funcionalidad, carece de características rimbombantes
igor@451 6 deliberadamente. Esta aproximación de preservar la simplicidad
igor@451 7 mantiene el programa sencillo tanto para mantenedores como para
igor@451 8 usuarios.
igor@451 9
igor@451 10 Si embargo Mercurial no le cierra las posibilidades a un conjunto
igor@451 11 inflexible de órdenes: usted puede añadir características como
igor@451 12 \emph{extensiones} (aveces llamadas \emph{añadidos}\ndt{plugins}). Ya
igor@451 13 hemos discutido algunas de estas extensiones en capítulos anteriores:
jerojasro@336 14 \begin{itemize}
igor@451 15 \item La sección~\ref{sec:tour-merge:fetch} cubre la extensión
igor@451 16 \hgext{fetch}; que combina jalar cambios y fusionarlos con los
igor@451 17 cambios locales en una sola orden: \hgxcmd{fetch}{fetch}.
igor@451 18 \item En el capítulo~\ref{chap:hook}, cubrimos muchas extensiones que
igor@451 19 son útiles en funcionalidades relacionadas con ganchos: Los
igor@451 20 \hgext{acl} añaden listas de control de acceso; \hgext{bugzilla}
igor@451 21 añade integración con el sistema de seguimiento de fallos Bugzilla; y
igor@451 22 \hgext{notify} envía notificaciones por correo de nuevos cambios.
igor@451 23 \item La extensión de administración de parches MQ es tan invaluable
igor@451 24 que amerita dos capítulos y un apéndice por sí misma.
igor@451 25 El capítulo~\ref{chap:mq} cubre lo básico; el
igor@451 26 capítulo~\ref{chap:mq-collab} discute temas avanzados; y el
igor@451 27 apéndice~\ref{chap:mqref} muestra en detalle cada orden.
jerojasro@336 28 \end{itemize}
jerojasro@336 29
igor@451 30 En este capítulo cubriremos algunas extensiones adicionales
igor@451 31 disponibles para Mercurial, y daremos un vistazo a la maquinaria que
igor@451 32 necesita conocer en caso de que desee escribir una extensión.
jerojasro@336 33 \begin{itemize}
igor@451 34 \item En la sección~\ref{sec:hgext:inotify}, discutiremos la
igor@451 35 posibilidad de mejorar el desempeño \emph{en gran medida} con la extensión
igor@451 36 \hgext{inotify}.
jerojasro@336 37 \end{itemize}
jerojasro@336 38
igor@451 39 \section{Mejorar el desempeño con la extensión \hgext{inotify}}
jerojasro@336 40 \label{sec:hgext:inotify}
jerojasro@336 41
igor@451 42 ¿Desea lograr que las operaciones más comunmente usadas de Mercurial se
igor@451 43 ejecuten centenas de veces más rápido? ¡A leer!
igor@451 44
igor@451 45 Mercurial tiene gran desempeño bajo circunstancias normales. Por
igor@451 46 ejemplo, cuando ejecuta la orden \hgcmd{status}, Mercurial tiene que
igor@451 47 revisar casi todos los ficheros y directorios en su repositorio de
igor@451 48 forma que pueda desplegar el estado de los ficheros. Muchas otras
igor@451 49 órdenes tienen que hacer tal trabajo tras bambalinas; por ejemplo la
igor@451 50 orden \hgcmd{diff} usa la maquinaria de estado para evitar hacer
igor@451 51 operaciones de comparación costosas en ficheros que obviamente no han
igor@451 52 cambiado.
igor@451 53
igor@451 54 Dado que obtener el estado de los ficheros es crucial para obtener
igor@451 55 buen desempeño, los autores de Mercurial han optimizado este código en
igor@451 56 la medida de lo posible. Sin embargo, no puede obviarse el hecho de
igor@451 57 que cuando ejecuta \hgcmd{status}, Mercurial tendrá que hacer por lo
igor@451 58 menos una costosa llamada al sistema por cada archivo administrado
igor@451 59 para determinar si ha cambiado desde la última vez que se consignó.
igor@451 60 Para un repositorio suficientemente grande, puede tardar bastante
igor@451 61 tiempo.
igor@451 62
igor@451 63 Para mostrar en números la magnitud de este efect, creé un repositorio
igor@451 64 que contenía 150.000 archivos administrador. Tardó diez segundos para
igor@451 65 ejecutar \hgcmd{status}, a pesar de que \emph{ninguno} de los ficheros
igor@451 66 había sido modificado.
igor@451 67
igor@451 68 Muchos sistemas operativos modernos contienen una facilidad de
igor@451 69 notificación de archivos. Si un programa se registra con un servicio
igor@451 70 apropiado, el sistema operativo le notificará siempre que un fichero
igor@451 71 de interés haya sido creado, modificado o borrado. En sistemas Linux,
igor@451 72 el componente del núcleo que lo hace se llama \texttt{inotify}.
igor@451 73
igor@451 74 La extensión \hgext{inotify} habla con el componente \texttt{inotify}
igor@451 75 del núcleo para optimizar las órdenes de \hgcmd{status}. La extensión
igor@451 76 tiene dos componentes. Un daemonio está en el fondo recibiendo
igor@451 77 notificaciones del subsistema \texttt{inotify}. También escucha
igor@451 78 conexiones de una orden regular de Mercurial. La extensión modifica
igor@451 79 el comportamiento de Mercurial de tal forma que, en lugar de revisar
igor@451 80 el sistema de ficheros, le pregunta al daemonio. Dado que el daemonio
igor@451 81 tiene información perfecta acerca del estado del repositorio, puede
igor@451 82 responder instantáneamente con el resultado, evitando la necesidad de
igor@451 83 revisar cada directorio y fichero del repositorio.
igor@451 84
igor@451 85 Retomando los diez segundos que medí al ejecutar la orden
igor@451 86 \hgcmd{status} de Mercurial sobre un repositorio de 150.000
igor@451 87 ficheros. Con la extensión \hgext{inotify} habilitada, el tiempo se
igor@451 88 disipó a 0.1~seconds, un factor \emph{cien veces} más rápido.
igor@451 89
igor@451 90 Antes de continuar, tenga en cuenta algunos detalles:
jerojasro@336 91 \begin{itemize}
igor@451 92 \item La extensión \hgext{inotify} es específica de Linux. Porque se
igor@451 93 enlaza directamente con el subsistema \texttt{inotify} del núcleo
igor@451 94 Linux, no funciona en otros sistemas operativos.
igor@451 95 \item Debería funcionar en cualquier distribución Linux a partir de
igor@451 96 comienzos del 2005. Las distribuciones más antiguas deben tener un
igor@451 97 kernel sin \texttt{inotify}, o una versión de \texttt{glibc} que no
igor@451 98 tiene necesariamente el soporte para la interfaz.
igor@451 99 \item No todos los sistemas de ficheros pueden usarse con la extensión
igor@451 100 \hgext{inotify}. Los sistemas de ficheros tales como NFS no lo
igor@451 101 soportan, por ejemplo, si está corriendo Mercurial en vaios
igor@451 102 sistemas, montados todos sobre el mismo sistema de ficheros en red.
igor@451 103 El sistema \texttt{inotify} del kernel no tiene forma de saber
igor@451 104 acerca de los cambios hechos en otro sistema. La mayoría de
igor@451 105 sistemas de ficheros locales (p.e.~ext3, XFS, ReiserFS) deberían
igor@451 106 funcionar bien.
jerojasro@336 107 \end{itemize}
jerojasro@336 108
igor@451 109 Hacia mayo de 2007 la extensión \hgext{inotify} no venía de forma
igor@451 110 predeterminada en Mercurial\ndt{Desde el 2008 para kernels 2.6 viene
igor@451 111 en Mercurial, pero no está activada de forma predeterminada}, y es
igor@451 112 un poco más compleja de activar que otras extensiones. Pero la mejora
igor@451 113 en el desempeño bien vale la pena!
igor@451 114
igor@451 115 La extensión venía en dos partes: un conjunto de parches al código
igor@451 116 fuente de Mercurial, y una librería de interfaces de Python hacia el
igor@451 117 subsistema \texttt{inotify}.
jerojasro@336 118 \begin{note}
igor@451 119 Hay \emph{dos} librerías de enlace de Python hacia \texttt{inotify}.
igor@451 120 Una de ellas se llama \texttt{pyinotify}, y en algunas
igor@451 121 distribuciones de Linux se encuentra como \texttt{python-inotify}.
igor@451 122 Esta es la que \emph{no} necesita, puesto que tiene muchos fallos,
igor@451 123 y es ineficiente para ser práctica.
jerojasro@336 124 \end{note}
igor@451 125 Para comenzar, es mejor tener una copia de Mercurial funcional
igor@451 126 instalada:
jerojasro@336 127 \begin{note}
igor@451 128 Si sigue las instrucciones a continuación, estará
igor@451 129 \emph{reemplazando} y sobreescribiendo cualquier instalación previa
igor@451 130 de Mercurial que pudiera tener, con el código de Mercurial ``más
igor@451 131 reciente y peligrosa''. No diga que no se le advirtio!
jerojasro@336 132 \end{note}
jerojasro@336 133 \begin{enumerate}
igor@451 134 \item Clone el repositorio de interfaz entre Python e
igor@451 135 \texttt{inotify}. Ármelo e instálelo:
jerojasro@336 136 \begin{codesample4}
jerojasro@336 137 hg clone http://hg.kublai.com/python/inotify
jerojasro@336 138 cd inotify
jerojasro@336 139 python setup.py build --force
jerojasro@336 140 sudo python setup.py install --skip-build
jerojasro@336 141 \end{codesample4}
igor@451 142 \item Clone el repositorio \dirname{crew} de Mercurial. Clone el
igor@451 143 repositorio de parches de \hgext{inotify} de forma tal que las colas
igor@451 144 de Mercurial puedan aplicar los parches sobre el repositorio \dirname{crew}.
jerojasro@336 145 \begin{codesample4}
jerojasro@336 146 hg clone http://hg.intevation.org/mercurial/crew
jerojasro@336 147 hg clone crew inotify
jerojasro@336 148 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
jerojasro@336 149 \end{codesample4}
igor@451 150 \item Asegúrese de instalar la extensión Colas de Mercurial
igor@451 151 \hgext{mq} y que estén habilitadas. Si nunca ha usado MQ, lea la
igor@451 152 sección~\ref{sec:mq:start} para poder comenzar rápidamente.
igor@451 153 \item Vaya al repositorio de \dirname{inotify} y aplique todos los
igor@451 154 parches de \hgext{inotify} con la opción \hgxopt{mq}{qpush}{-a} de
igor@451 155 la orden \hgxcmd{mq}{qpush}.
jerojasro@336 156 \begin{codesample4}
jerojasro@336 157 cd inotify
jerojasro@336 158 hg qpush -a
jerojasro@336 159 \end{codesample4}
igor@451 160 Si obtiene un mensaje de error de \hgxcmd{mq}{qpush}, no debería
igor@451 161 continuar. Mejor pida ayuda.
igor@451 162 \item Arme e instale la versión parchada de Mercurial.
jerojasro@336 163 \begin{codesample4}
jerojasro@336 164 python setup.py build --force
jerojasro@336 165 sudo python setup.py install --skip-build
jerojasro@336 166 \end{codesample4}
jerojasro@336 167 \end{enumerate}
igor@451 168 Una vez que haya armado una versión funcional parchada de Mercurial,
igor@451 169 todo lo que necesita es habilitar la extensión \hgext{inotify}
igor@451 170 colocando una entrada en su \hgrc.
jerojasro@336 171 \begin{codesample2}
jerojasro@336 172 [extensions]
jerojasro@336 173 inotify =
jerojasro@336 174 \end{codesample2}
igor@451 175 Cuando la extensión \hgext{inotify} esté habilitada, Mercurial
igor@451 176 iniciará transparente y automáticamente el daemonio de estado la
igor@451 177 primera vez que ejecute un comando que requiera estado del
igor@451 178 repositorio. Ejecuta un daemoniot de estado por repositorio.
igor@451 179
igor@451 180 El daemonio de estado se inicia silenciosamente y se ejecuta en el
igor@451 181 fondo. Si mira a la lista de procesos en ejecución después de
igor@451 182 habilitar la extensión \hgext{inotify} y ejecuta unos pocos comandos
igor@451 183 en diferentes repositorios, verá que hay algunos procesos de
igor@451 184 \texttt{hg} por ahí, esperando actualizaciones del kernel y
igor@451 185 solicitudes de Mercurial.
igor@451 186
igor@451 187 La primera vez que ejecuta un comando de Mercurial en un repositorio
igor@451 188 cuando tiene la extensión \hgext{inotify} habilitada, correrá casi con
igor@451 189 el mismo desempeño que una orden usual de Mercurial. Esto es debido a
igor@451 190 que el estado del daemonio necesita aplicar una búsqueda normal sobre
igor@451 191 el estado para poder tener una línea de partida frente a la cual
igor@451 192 aplicar posteriormente actualizaciones del núcleo. De todas formas,
igor@451 193 \emph{todo} comando posterior que haga cualquier clase de revisión del
igor@451 194 estado debería ser notablemente más rápido en repositorios con incluso
igor@451 195 un tamaño modesto. Aún mejor, a medida que su repositorio sea más
igor@451 196 grande, mejor desempeño verá. El daemonio \hgext{inotify} hace
igor@451 197 operaciones de estado de forma casi instantánea en repositorios de
igor@451 198 todos los tamaños!
igor@451 199
igor@451 200 Si lo desea, puede iniciar manualmente un daemonio de estado con la orden
igor@451 201 \hgxcmd{inotify}{inserve}. Esto le da un control un poco más fino
igor@451 202 acerca de cómo debería ejecutarse el daemonio. Esta orden solamente
igor@451 203 estará disponible cuando haya habilitado la extensión \hgext{inotify}.
igor@451 204
igor@451 205 Cuando esté usando la extensión \hgext{inotify},
igor@451 206 \emph{no debería ver diferencia} en el comportamiento de Mercurial,
igor@451 207 con la única excepción de que los comandos relacionados con el estado
igor@451 208 deberían ejectuarse mucho más rápido que como solían hacerlo. Debería
igor@451 209 esperar específicamente que las órdenes no deberían ofrecer salidas
igor@451 210 distintas; ni ofrecer resultados diferentes. Si alguna de estas
igor@451 211 situaciones ocurre, por favor reporte el fallo.
igor@451 212
igor@451 213 \section{Soporte flexible de diff con la extensión \hgext{extdiff}}
jerojasro@336 214 \label{sec:hgext:extdiff}
jerojasro@336 215
igor@451 216 La orden predeterminada \hgcmd{diff} de Mercurial despliega diffs en
igor@451 217 texto plano unificadas.
jerojasro@336 218 \interaction{extdiff.diff}
igor@451 219 Si dese emplear una herramienta externa para desplegar las
igor@451 220 modificaciones, querrá usar la extensión \hgext{extdiff}. Esta le
igor@451 221 permitirá usar por ejemplo una herramienta gráfica de diff.
igor@451 222
igor@451 223 La extensión \hgext{extdiff} viene con Mercurial, y es fácil
igor@451 224 configurarl. En la sección \rcsection{extensions} de su \hgrc,
igor@451 225 basta con añadir una entrada de una línea para habilitar la extensión.
jerojasro@336 226 \begin{codesample2}
jerojasro@336 227 [extensions]
jerojasro@336 228 extdiff =
jerojasro@336 229 \end{codesample2}
igor@451 230 Esto introduce una orden llamada \hgxcmd{extdiff}{extdiff}, que de
igor@451 231 forma predeterminada usa su orden del sistema \command{diff} para
igor@451 232 generar un diff unificado de la misma forma que lo hace el comando
igor@451 233 predeterminado \hgcmd{diff}.
jerojasro@336 234 \interaction{extdiff.extdiff}
igor@451 235 El resultado no será exactamente el mismo que con la orden interna
igor@451 236 \hgcmd{diff}, puesto que la salida de \command{diff} varía de un
igor@451 237 sistema a otro, incluso pasando las mismas opciones.
jerojasro@336 238
jerojasro@336 239 As the ``\texttt{making snapshot}'' lines of output above imply, the
jerojasro@336 240 \hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
jerojasro@336 241 your source tree. The first snapshot is of the source revision; the
jerojasro@336 242 second, of the target revision or working directory. The
jerojasro@336 243 \hgxcmd{extdiff}{extdiff} command generates these snapshots in a
jerojasro@336 244 temporary directory, passes the name of each directory to an external
jerojasro@336 245 diff viewer, then deletes the temporary directory. For efficiency, it
jerojasro@336 246 only snapshots the directories and files that have changed between the
jerojasro@336 247 two revisions.
jerojasro@336 248
jerojasro@336 249 Snapshot directory names have the same base name as your repository.
jerojasro@336 250 If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
jerojasro@336 251 will be the name of each snapshot directory. Each snapshot directory
jerojasro@336 252 name has its changeset ID appended, if appropriate. If a snapshot is
jerojasro@336 253 of revision \texttt{a631aca1083f}, the directory will be named
jerojasro@336 254 \dirname{foo.a631aca1083f}. A snapshot of the working directory won't
jerojasro@336 255 have a changeset ID appended, so it would just be \dirname{foo} in
jerojasro@336 256 this example. To see what this looks like in practice, look again at
jerojasro@336 257 the \hgxcmd{extdiff}{extdiff} example above. Notice that the diff has
jerojasro@336 258 the snapshot directory names embedded in its header.
jerojasro@336 259
jerojasro@336 260 The \hgxcmd{extdiff}{extdiff} command accepts two important options.
jerojasro@336 261 The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
jerojasro@336 262 view differences with, instead of \command{diff}. With the
jerojasro@336 263 \hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
jerojasro@336 264 \hgxcmd{extdiff}{extdiff} passes to the program (by default, these
jerojasro@336 265 options are ``\texttt{-Npru}'', which only make sense if you're
jerojasro@336 266 running \command{diff}). In other respects, the
jerojasro@336 267 \hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
jerojasro@336 268 \hgcmd{diff} command: you use the same option names, syntax, and
jerojasro@336 269 arguments to specify the revisions you want, the files you want, and
jerojasro@336 270 so on.
jerojasro@336 271
jerojasro@336 272 As an example, here's how to run the normal system \command{diff}
jerojasro@336 273 command, getting it to generate context diffs (using the
jerojasro@336 274 \cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
jerojasro@336 275 context instead of the default three (passing \texttt{5} as the
jerojasro@336 276 argument to the \cmdopt{diff}{-C} option).
jerojasro@336 277 \interaction{extdiff.extdiff-ctx}
jerojasro@336 278
jerojasro@336 279 Launching a visual diff tool is just as easy. Here's how to launch
jerojasro@336 280 the \command{kdiff3} viewer.
jerojasro@336 281 \begin{codesample2}
jerojasro@336 282 hg extdiff -p kdiff3 -o ''
jerojasro@336 283 \end{codesample2}
jerojasro@336 284
jerojasro@336 285 If your diff viewing command can't deal with directories, you can
jerojasro@336 286 easily work around this with a little scripting. For an example of
jerojasro@336 287 such scripting in action with the \hgext{mq} extension and the
jerojasro@336 288 \command{interdiff} command, see
jerojasro@336 289 section~\ref{mq-collab:tips:interdiff}.
jerojasro@336 290
jerojasro@336 291 \subsection{Defining command aliases}
jerojasro@336 292
jerojasro@336 293 It can be cumbersome to remember the options to both the
jerojasro@336 294 \hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use,
jerojasro@336 295 so the \hgext{extdiff} extension lets you define \emph{new} commands
jerojasro@336 296 that will invoke your diff viewer with exactly the right options.
jerojasro@336 297
jerojasro@336 298 All you need to do is edit your \hgrc, and add a section named
jerojasro@336 299 \rcsection{extdiff}. Inside this section, you can define multiple
jerojasro@336 300 commands. Here's how to add a \texttt{kdiff3} command. Once you've
jerojasro@336 301 defined this, you can type ``\texttt{hg kdiff3}'' and the
jerojasro@336 302 \hgext{extdiff} extension will run \command{kdiff3} for you.
jerojasro@336 303 \begin{codesample2}
jerojasro@336 304 [extdiff]
jerojasro@336 305 cmd.kdiff3 =
jerojasro@336 306 \end{codesample2}
jerojasro@336 307 If you leave the right hand side of the definition empty, as above,
jerojasro@336 308 the \hgext{extdiff} extension uses the name of the command you defined
jerojasro@336 309 as the name of the external program to run. But these names don't
jerojasro@336 310 have to be the same. Here, we define a command named ``\texttt{hg
jerojasro@336 311 wibble}'', which runs \command{kdiff3}.
jerojasro@336 312 \begin{codesample2}
jerojasro@336 313 [extdiff]
jerojasro@336 314 cmd.wibble = kdiff3
jerojasro@336 315 \end{codesample2}
jerojasro@336 316
jerojasro@336 317 You can also specify the default options that you want to invoke your
jerojasro@336 318 diff viewing program with. The prefix to use is ``\texttt{opts.}'',
jerojasro@336 319 followed by the name of the command to which the options apply. This
jerojasro@336 320 example defines a ``\texttt{hg vimdiff}'' command that runs the
jerojasro@336 321 \command{vim} editor's \texttt{DirDiff} extension.
jerojasro@336 322 \begin{codesample2}
jerojasro@336 323 [extdiff]
jerojasro@336 324 cmd.vimdiff = vim
jerojasro@336 325 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
jerojasro@336 326 \end{codesample2}
jerojasro@336 327
jerojasro@336 328 \section{Cherrypicking changes with the \hgext{transplant} extension}
jerojasro@336 329 \label{sec:hgext:transplant}
jerojasro@336 330
jerojasro@336 331 Need to have a long chat with Brendan about this.
jerojasro@336 332
jerojasro@336 333 \section{Send changes via email with the \hgext{patchbomb} extension}
jerojasro@336 334 \label{sec:hgext:patchbomb}
jerojasro@336 335
jerojasro@336 336 Many projects have a culture of ``change review'', in which people
jerojasro@336 337 send their modifications to a mailing list for others to read and
jerojasro@336 338 comment on before they commit the final version to a shared
jerojasro@336 339 repository. Some projects have people who act as gatekeepers; they
jerojasro@336 340 apply changes from other people to a repository to which those others
jerojasro@336 341 don't have access.
jerojasro@336 342
jerojasro@336 343 Mercurial makes it easy to send changes over email for review or
jerojasro@336 344 application, via its \hgext{patchbomb} extension. The extension is so
jerojasro@336 345 namd because changes are formatted as patches, and it's usual to send
jerojasro@336 346 one changeset per email message. Sending a long series of changes by
jerojasro@336 347 email is thus much like ``bombing'' the recipient's inbox, hence
jerojasro@336 348 ``patchbomb''.
jerojasro@336 349
jerojasro@336 350 As usual, the basic configuration of the \hgext{patchbomb} extension
jerojasro@336 351 takes just one or two lines in your \hgrc.
jerojasro@336 352 \begin{codesample2}
jerojasro@336 353 [extensions]
jerojasro@336 354 patchbomb =
jerojasro@336 355 \end{codesample2}
jerojasro@336 356 Once you've enabled the extension, you will have a new command
jerojasro@336 357 available, named \hgxcmd{patchbomb}{email}.
jerojasro@336 358
jerojasro@336 359 The safest and best way to invoke the \hgxcmd{patchbomb}{email}
jerojasro@336 360 command is to \emph{always} run it first with the
jerojasro@336 361 \hgxopt{patchbomb}{email}{-n} option. This will show you what the
jerojasro@336 362 command \emph{would} send, without actually sending anything. Once
jerojasro@336 363 you've had a quick glance over the changes and verified that you are
jerojasro@336 364 sending the right ones, you can rerun the same command, with the
jerojasro@336 365 \hgxopt{patchbomb}{email}{-n} option removed.
jerojasro@336 366
jerojasro@336 367 The \hgxcmd{patchbomb}{email} command accepts the same kind of
jerojasro@336 368 revision syntax as every other Mercurial command. For example, this
jerojasro@336 369 command will send every revision between 7 and \texttt{tip},
jerojasro@336 370 inclusive.
jerojasro@336 371 \begin{codesample2}
jerojasro@336 372 hg email -n 7:tip
jerojasro@336 373 \end{codesample2}
jerojasro@336 374 You can also specify a \emph{repository} to compare with. If you
jerojasro@336 375 provide a repository but no revisions, the \hgxcmd{patchbomb}{email}
jerojasro@336 376 command will send all revisions in the local repository that are not
jerojasro@336 377 present in the remote repository. If you additionally specify
jerojasro@336 378 revisions or a branch name (the latter using the
jerojasro@336 379 \hgxopt{patchbomb}{email}{-b} option), this will constrain the
jerojasro@336 380 revisions sent.
jerojasro@336 381
jerojasro@336 382 It's perfectly safe to run the \hgxcmd{patchbomb}{email} command
jerojasro@336 383 without the names of the people you want to send to: if you do this,
jerojasro@336 384 it will just prompt you for those values interactively. (If you're
jerojasro@336 385 using a Linux or Unix-like system, you should have enhanced
jerojasro@336 386 \texttt{readline}-style editing capabilities when entering those
jerojasro@336 387 headers, too, which is useful.)
jerojasro@336 388
jerojasro@336 389 When you are sending just one revision, the \hgxcmd{patchbomb}{email}
jerojasro@336 390 command will by default use the first line of the changeset
jerojasro@336 391 description as the subject of the single email message it sends.
jerojasro@336 392
jerojasro@336 393 If you send multiple revisions, the \hgxcmd{patchbomb}{email} command
jerojasro@336 394 will usually send one message per changeset. It will preface the
jerojasro@336 395 series with an introductory message, in which you should describe the
jerojasro@336 396 purpose of the series of changes you're sending.
jerojasro@336 397
jerojasro@336 398 \subsection{Changing the behaviour of patchbombs}
jerojasro@336 399
jerojasro@336 400 Not every project has exactly the same conventions for sending changes
jerojasro@336 401 in email; the \hgext{patchbomb} extension tries to accommodate a
jerojasro@336 402 number of variations through command line options.
jerojasro@336 403 \begin{itemize}
jerojasro@336 404 \item You can write a subject for the introductory message on the
jerojasro@336 405 command line using the \hgxopt{patchbomb}{email}{-s} option. This
jerojasro@336 406 takes one argument, the text of the subject to use.
jerojasro@336 407 \item To change the email address from which the messages originate,
jerojasro@336 408 use the \hgxopt{patchbomb}{email}{-f} option. This takes one
jerojasro@336 409 argument, the email address to use.
jerojasro@336 410 \item The default behaviour is to send unified diffs (see
jerojasro@336 411 section~\ref{sec:mq:patch} for a description of the format), one per
jerojasro@336 412 message. You can send a binary bundle instead with the
jerojasro@336 413 \hgxopt{patchbomb}{email}{-b} option.
jerojasro@336 414 \item Unified diffs are normally prefaced with a metadata header. You
jerojasro@336 415 can omit this, and send unadorned diffs, with the
jerojasro@336 416 \hgxopt{patchbomb}{email}{--plain} option.
jerojasro@336 417 \item Diffs are normally sent ``inline'', in the same body part as the
jerojasro@336 418 description of a patch. This makes it easiest for the largest
jerojasro@336 419 number of readers to quote and respond to parts of a diff, as some
jerojasro@336 420 mail clients will only quote the first MIME body part in a message.
jerojasro@336 421 If you'd prefer to send the description and the diff in separate
jerojasro@336 422 body parts, use the \hgxopt{patchbomb}{email}{-a} option.
jerojasro@336 423 \item Instead of sending mail messages, you can write them to an
jerojasro@336 424 \texttt{mbox}-format mail folder using the
jerojasro@336 425 \hgxopt{patchbomb}{email}{-m} option. That option takes one
jerojasro@336 426 argument, the name of the file to write to.
jerojasro@336 427 \item If you would like to add a \command{diffstat}-format summary to
jerojasro@336 428 each patch, and one to the introductory message, use the
jerojasro@336 429 \hgxopt{patchbomb}{email}{-d} option. The \command{diffstat}
jerojasro@336 430 command displays a table containing the name of each file patched,
jerojasro@336 431 the number of lines affected, and a histogram showing how much each
jerojasro@336 432 file is modified. This gives readers a qualitative glance at how
jerojasro@336 433 complex a patch is.
jerojasro@336 434 \end{itemize}
jerojasro@336 435
jerojasro@336 436 %%% Local Variables:
jerojasro@336 437 %%% mode: latex
jerojasro@336 438 %%% TeX-master: "00book"
jerojasro@336 439 %%% End: