
igor@440: \chapter{Añadir funcionalidad con extensiones}
jerojasro@336: \label{chap:hgext}
jerojasro@336: 
igor@451: A pesar de que el corazón de Mercurial es muy completo desde el punto
igor@451: de vista de funcionalidad, carece de características rimbombantes
igor@451: deliberadamente.  Esta aproximación de preservar la simplicidad
igor@451: mantiene el programa sencillo tanto para mantenedores como para
igor@451: usuarios.
igor@451: 
igor@451: Si embargo Mercurial no le cierra las posibilidades a un conjunto
igor@451: inflexible de órdenes: usted puede añadir características como
igor@451: \emph{extensiones} (aveces llamadas \emph{añadidos}\ndt{plugins}).  Ya
igor@451: hemos discutido algunas de estas extensiones en capítulos anteriores:
jerojasro@336: \begin{itemize}
igor@451: \item La sección~\ref{sec:tour-merge:fetch} cubre la extensión
igor@451:   \hgext{fetch}; que combina jalar cambios y fusionarlos con los
igor@451:   cambios locales en una sola orden: \hgxcmd{fetch}{fetch}.
igor@451: \item En el capítulo~\ref{chap:hook}, cubrimos muchas extensiones que
igor@451:   son útiles en funcionalidades relacionadas con ganchos: Los
igor@451:   \hgext{acl} añaden listas de control de acceso; \hgext{bugzilla}
igor@451:   añade integración con el sistema de seguimiento de fallos Bugzilla; y
igor@451:   \hgext{notify} envía notificaciones por correo de nuevos cambios.
igor@451: \item La extensión de administración de parches MQ es tan invaluable
igor@451:   que amerita dos capítulos y un apéndice por sí misma.
igor@451:   El capítulo~\ref{chap:mq} cubre lo básico; el
igor@451:   capítulo~\ref{chap:mq-collab} discute temas avanzados; y el
igor@451:   apéndice~\ref{chap:mqref} muestra en detalle cada orden.
jerojasro@336: \end{itemize}
jerojasro@336: 
igor@451: En este capítulo cubriremos algunas extensiones adicionales
igor@451: disponibles para Mercurial, y daremos un vistazo a la maquinaria que
igor@451: necesita conocer en caso de que desee escribir una extensión.
jerojasro@336: \begin{itemize}
igor@451: \item En la sección~\ref{sec:hgext:inotify}, discutiremos la
igor@451:   posibilidad de mejorar el desempeño \emph{en gran medida} con la extensión
igor@451:   \hgext{inotify}.
jerojasro@336: \end{itemize}
jerojasro@336: 
igor@451: \section{Mejorar el desempeño con la extensión \hgext{inotify}}
jerojasro@336: \label{sec:hgext:inotify}
jerojasro@336: 
igor@451: ¿Desea lograr que las operaciones más comunmente usadas de Mercurial se
igor@451: ejecuten centenas de veces más rápido? ¡A leer!
igor@451: 
igor@451: Mercurial tiene gran desempeño bajo circunstancias normales.  Por
igor@451: ejemplo, cuando ejecuta la orden \hgcmd{status}, Mercurial tiene que
igor@451: revisar casi todos los ficheros y directorios en su repositorio de
igor@451: forma que pueda desplegar el estado de los ficheros.  Muchas otras
igor@451: órdenes tienen que hacer tal trabajo tras bambalinas;  por ejemplo la
igor@451: orden \hgcmd{diff} usa la maquinaria de estado para evitar hacer
igor@451: operaciones de comparación costosas en ficheros que obviamente no han
igor@451: cambiado.
igor@451: 
igor@451: Dado que obtener el estado de los ficheros es crucial para obtener
igor@451: buen desempeño, los autores de Mercurial han optimizado este código en
igor@451: la medida de lo posible.  Sin embargo, no puede obviarse el hecho de
igor@451: que cuando ejecuta \hgcmd{status}, Mercurial tendrá que hacer por lo
igor@451: menos una costosa llamada al sistema por cada archivo administrado
igor@451: para determinar si ha cambiado desde la última vez que se consignó.
igor@451: Para un repositorio suficientemente grande, puede tardar bastante
igor@451: tiempo.
igor@451: 
igor@451: Para mostrar en números la magnitud de este efect, creé un repositorio
igor@451: que contenía 150.000 archivos administrador.  Tardó diez segundos para
igor@451: ejecutar \hgcmd{status}, a pesar de que \emph{ninguno} de los ficheros
igor@451: había sido modificado.
igor@451: 
igor@451: Muchos sistemas operativos modernos contienen una facilidad de
igor@451: notificación de archivos.  Si un programa se registra con un servicio
igor@451: apropiado, el sistema operativo le notificará siempre que un fichero
igor@451: de interés haya sido creado, modificado o borrado.  En sistemas Linux,
igor@451: el componente del núcleo que lo hace se llama \texttt{inotify}.
igor@451: 
igor@451: La extensión \hgext{inotify} habla con el componente \texttt{inotify}
igor@451: del núcleo para optimizar las órdenes de \hgcmd{status}.  La extensión
igor@451: tiene dos componentes.  Un daemonio está en el fondo recibiendo
igor@451: notificaciones del subsistema \texttt{inotify}.  También escucha
igor@451: conexiones de una orden regular de Mercurial.  La extensión modifica
igor@451: el comportamiento de Mercurial de tal forma que, en lugar de revisar
igor@451: el sistema de ficheros, le pregunta al daemonio.  Dado que el daemonio
igor@451: tiene información perfecta acerca del estado del repositorio, puede
igor@451: responder instantáneamente con el resultado, evitando la necesidad de
igor@451: revisar cada directorio y fichero del repositorio.
igor@451: 
igor@451: Retomando los diez segundos que medí al ejecutar la orden
igor@451: \hgcmd{status} de Mercurial sobre un repositorio de 150.000
igor@451: ficheros. Con la extensión \hgext{inotify} habilitada, el tiempo se
igor@451: disipó a 0.1~seconds, un factor \emph{cien veces} más rápido.
igor@451: 
igor@451: Antes de continuar, tenga en cuenta algunos detalles:
jerojasro@336: \begin{itemize}
igor@451: \item La extensión \hgext{inotify} es específica de Linux.  Porque se
igor@451:   enlaza directamente con el subsistema \texttt{inotify} del núcleo
igor@451:   Linux, no funciona en otros sistemas operativos.
igor@451: \item Debería funcionar en cualquier distribución Linux a partir de
igor@451:   comienzos del 2005.  Las distribuciones más antiguas deben tener un
igor@451:   kernel sin \texttt{inotify}, o una versión de \texttt{glibc} que no
igor@451:   tiene necesariamente el soporte para la interfaz.
igor@451: \item No todos los sistemas de ficheros pueden usarse con la extensión
igor@451:   \hgext{inotify}.  Los sistemas de ficheros tales como NFS no lo
igor@451:   soportan, por ejemplo, si está corriendo Mercurial en vaios
igor@451:   sistemas, montados todos sobre el mismo sistema de ficheros en red.
igor@451:   El sistema \texttt{inotify} del kernel no tiene forma de saber
igor@451:   acerca de los cambios hechos en otro sistema.  La mayoría de
igor@451:   sistemas de ficheros locales (p.e.~ext3, XFS, ReiserFS) deberían
igor@451:   funcionar bien.
jerojasro@336: \end{itemize}
jerojasro@336: 
igor@451: Hacia mayo de 2007 la extensión \hgext{inotify} no venía de forma
igor@451: predeterminada en Mercurial\ndt{Desde el 2008 para kernels 2.6 viene
igor@451:   en Mercurial, pero no está activada de forma predeterminada}, y es
igor@451: un poco más compleja de activar que otras extensiones.  Pero la mejora
igor@451: en el desempeño bien vale la pena!
igor@451: 
igor@451: La extensión venía en dos partes: un conjunto de parches al código
igor@451: fuente de Mercurial, y una librería de interfaces de Python hacia el
igor@451: subsistema \texttt{inotify}.
jerojasro@336: \begin{note}
igor@451:   Hay \emph{dos} librerías de enlace de Python hacia \texttt{inotify}.
igor@451:   Una de ellas se llama \texttt{pyinotify}, y en algunas
igor@451:   distribuciones de Linux se encuentra como \texttt{python-inotify}.
igor@451:   Esta es la que \emph{no} necesita, puesto que tiene muchos fallos,
igor@451:   y es ineficiente para ser práctica.
jerojasro@336: \end{note}
igor@451: Para comenzar, es mejor tener una copia de Mercurial funcional
igor@451: instalada:
jerojasro@336: \begin{note}
igor@451:   Si sigue las instrucciones a continuación, estará
igor@451:   \emph{reemplazando} y sobreescribiendo cualquier instalación previa
igor@451:   de Mercurial que pudiera tener, con el código de Mercurial ``más
igor@451:   reciente y peligrosa''.  No diga que no se le advirtio!
jerojasro@336: \end{note}
jerojasro@336: \begin{enumerate}
igor@451: \item Clone el repositorio de interfaz entre Python e
igor@451:   \texttt{inotify}. Ármelo e instálelo:
jerojasro@336:   \begin{codesample4}
jerojasro@336:     hg clone http://hg.kublai.com/python/inotify
jerojasro@336:     cd inotify
jerojasro@336:     python setup.py build --force
jerojasro@336:     sudo python setup.py install --skip-build
jerojasro@336:   \end{codesample4}
igor@451: \item Clone el repositorio \dirname{crew} de Mercurial.  Clone el
igor@451:   repositorio de parches de \hgext{inotify} de forma tal que las colas
igor@451:   de Mercurial puedan aplicar los parches sobre el repositorio \dirname{crew}.
jerojasro@336:   \begin{codesample4}
jerojasro@336:     hg clone http://hg.intevation.org/mercurial/crew
jerojasro@336:     hg clone crew inotify
jerojasro@336:     hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
jerojasro@336:   \end{codesample4}
igor@451: \item Asegúrese de instalar la extensión Colas de Mercurial
igor@451:   \hgext{mq} y que estén habilitadas.  Si nunca ha usado MQ, lea la
igor@451:   sección~\ref{sec:mq:start} para poder comenzar rápidamente.
igor@451: \item Vaya al repositorio de \dirname{inotify} y aplique todos los
igor@451:   parches de \hgext{inotify} con la opción \hgxopt{mq}{qpush}{-a} de
igor@451:   la orden \hgxcmd{mq}{qpush}.
jerojasro@336:   \begin{codesample4}
jerojasro@336:     cd inotify
jerojasro@336:     hg qpush -a
jerojasro@336:   \end{codesample4}
igor@451:   Si obtiene un mensaje de error de \hgxcmd{mq}{qpush}, no debería
igor@451:   continuar.  Mejor pida ayuda.
igor@451: \item Arme e instale la versión parchada de Mercurial.
jerojasro@336:   \begin{codesample4}
jerojasro@336:     python setup.py build --force
jerojasro@336:     sudo python setup.py install --skip-build
jerojasro@336:   \end{codesample4}
jerojasro@336: \end{enumerate}
igor@451: Una vez que haya armado una versión funcional parchada de Mercurial,
igor@451: todo lo que necesita es habilitar la extensión \hgext{inotify}
igor@451: colocando una entrada en su \hgrc.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extensions]
jerojasro@336:   inotify =
jerojasro@336: \end{codesample2}
igor@451: Cuando la extensión \hgext{inotify} esté habilitada, Mercurial
igor@451: iniciará transparente y automáticamente el daemonio de estado la
igor@451: primera vez que ejecute un comando que requiera estado del
igor@451: repositorio.  Ejecuta un daemoniot de estado por repositorio.
igor@451: 
igor@451: El daemonio de estado se inicia silenciosamente y se ejecuta en el
igor@451: fondo. Si mira a la lista de procesos en ejecución después de
igor@451: habilitar la extensión \hgext{inotify} y ejecuta unos pocos comandos
igor@451: en diferentes repositorios, verá que hay algunos procesos de
igor@451: \texttt{hg} por ahí, esperando actualizaciones del kernel y
igor@451: solicitudes de Mercurial.
igor@451: 
igor@451: La primera vez que ejecuta un comando de Mercurial en un repositorio
igor@451: cuando tiene la extensión \hgext{inotify} habilitada, correrá casi con
igor@451: el mismo desempeño que una orden usual de Mercurial.  Esto es debido a
igor@451: que el estado del daemonio necesita aplicar una búsqueda normal sobre
igor@451: el estado para poder tener una línea de partida frente a la cual
igor@451: aplicar posteriormente actualizaciones del núcleo.  De todas formas,
igor@451: \emph{todo} comando posterior que haga cualquier clase de revisión del
igor@451: estado debería ser notablemente más rápido en repositorios con incluso
igor@451: un tamaño modesto.  Aún mejor, a medida que su repositorio sea más
igor@451: grande, mejor desempeño verá.  El daemonio \hgext{inotify} hace
igor@451: operaciones de estado de forma casi instantánea en repositorios de
igor@451: todos los tamaños!
igor@451: 
igor@451: Si lo desea, puede iniciar manualmente un daemonio de estado con la orden
igor@451: \hgxcmd{inotify}{inserve}.  Esto le da un control un poco más fino
igor@451: acerca de cómo debería ejecutarse el daemonio.  Esta orden solamente
igor@451: estará disponible cuando haya habilitado la extensión \hgext{inotify}.
igor@451: 
igor@451: Cuando esté usando la extensión \hgext{inotify},
igor@451: \emph{no debería ver diferencia} en el comportamiento de Mercurial,
igor@451: con la única excepción de que los comandos relacionados con el estado
igor@451: deberían ejectuarse mucho más rápido que como solían hacerlo.  Debería
igor@451: esperar específicamente que las órdenes no deberían ofrecer salidas
igor@451: distintas; ni ofrecer resultados diferentes.  Si alguna de estas
igor@451: situaciones ocurre, por favor reporte el fallo.
igor@451: 
igor@451: \section{Soporte flexible de diff con la extensión \hgext{extdiff}}
jerojasro@336: \label{sec:hgext:extdiff}
jerojasro@336: 
igor@451: La orden predeterminada \hgcmd{diff} de Mercurial despliega diffs en
igor@451: texto plano unificadas.
jerojasro@336: \interaction{extdiff.diff}
igor@451: Si dese emplear una herramienta externa para desplegar las
igor@451: modificaciones, querrá usar la extensión \hgext{extdiff}.  Esta le
igor@451: permitirá usar por ejemplo una herramienta gráfica de diff.
igor@451: 
igor@451: La extensión \hgext{extdiff} viene con Mercurial, y es fácil
igor@451: configurarl.  En la sección \rcsection{extensions} de su \hgrc,
igor@451: basta con añadir una entrada de una línea para habilitar la extensión.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extensions]
jerojasro@336:   extdiff =
jerojasro@336: \end{codesample2}
igor@451: Esto introduce una orden llamada \hgxcmd{extdiff}{extdiff}, que de
igor@451: forma predeterminada usa su orden del sistema \command{diff} para
igor@451: generar un diff unificado de la misma forma que lo hace el comando
igor@451: predeterminado \hgcmd{diff}.
jerojasro@336: \interaction{extdiff.extdiff}
igor@451: El resultado no será exactamente el mismo que con la orden interna
igor@451: \hgcmd{diff}, puesto que la salida de \command{diff} varía de un
igor@451: sistema a otro, incluso pasando las mismas opciones.
jerojasro@336: 
igor@453: Como lo indican las líneas``\texttt{making snapshot}'', la orden
igor@453: \hgxcmd{extdiff}{extdiff} funciona creando dos instantáneas de su
igor@453: árbol de fuentes.  La primera instantánea es la revisión fuente; la
igor@453: segunda es la revisión objetivo del directorio de trabajo.  La orden
igor@453: \hgxcmd{extdiff}{extdiff} genera estas instantáneas en un directorio
igor@453: temporal, pasa el nombre de cada directorio a un visor de diffs
igor@453: temporal y borra los directorios temporales.  Por cuestiones de
igor@453: eficiencia solamente genera instantáneas de los directorios y ficheros
igor@453: que han cambiado entre dos revisiones.
igor@453: 
igor@453: Los nombres de los directorios de instantáneas tienen los mismos
igor@453: nombres base de su repositorio.  Si su repositorio tiene por ruta
igor@453: \dirname{/quux/bar/foo}, \dirname{foo} será el nombre de cada
igor@453: instantánea de directorio.  Cada instantánea de directorio tiene sus
igor@453: identificadores de conjuntos de cambios al final del nombre en caso de
igor@453: que sea apropiado.  Si una instantánea viene de la revisión
igor@453: \texttt{a631aca1083f}, el directorio se llamará
igor@453: \dirname{foo.a631aca1083f}.  Una instantánea del directorio de trabajo
igor@453: no tendrá el identificador del conjunto de cambios, y por lo tanto
igor@453: será solamente \dirname{foo} en este ejemplo.  Para ver cómo luce en
igor@453: la práctica, veamos de nuevo el ejemplo \hgxcmd{extdiff}{extdiff}
igor@453: antes mencionado.  Tenga en cuenta que los diffs tienen los nombres de
igor@453: las instantáneas de directorio dentro de su encabezado.
igor@453: 
igor@453: La orden \hgxcmd{extdiff}{extdiff} acepta dos opciones importantes.
igor@453: La opción \hgxopt{extdiff}{extdiff}{-p} le permite elegir un programa
igor@453: para ver las diferencias, en lugar de \command{diff}.  Con la opción
igor@453: \hgxopt{extdiff}{extdiff}{-o} puede cambiar las opciones que
igor@453: \hgxcmd{extdiff}{extdiff} pasa a tal programa(de forma predeterminada
igor@453: las opciones son``\texttt{-Npru}'', que tienen sentido únicamente si
igor@453: está usando \command{diff}).  En otros aspectos, la orden
igor@453: \hgxcmd{extdiff}{extdiff} actúa de forma similar a como lo hace la
igor@453: orden \hgcmd{diff} de Mercurial: usted usa los mismos nombres de
igor@453: opciones, sintaxis y argumentos para especificar las revisiones y los
igor@453: ficheros que quiere, y así sucesivamente.
igor@453: 
igor@453: Por ejemplo, para ejecutar la orden usual del sistema \command{diff},
igor@453: para lograr que se generen diferencias de contexto (con la opción
igor@453: \cmdopt{diff}{-c}) en lugar de diferencias unificadas, y cinco líneas
igor@453: de contexto en lugar de las tres predeterminadas(pasando \texttt{5}
igor@453: como argumento a la opción \cmdopt{diff}{-C}).
jerojasro@336: \interaction{extdiff.extdiff-ctx}
jerojasro@336: 
igor@453: Es sencillo lanzar unas herramienta usual de diferencias.  Para lanzar
igor@453: el visor \command{kdiff3}:
jerojasro@336: \begin{codesample2}
jerojasro@336:   hg extdiff -p kdiff3 -o ''
jerojasro@336: \end{codesample2}
jerojasro@336: 
igor@453: Si su orden para visualizar diferencias no puede tratar con
igor@453: directorios, puede usar un poco de scripting para lograrlo.  Un
igor@453: ejemplo de un script con la extensión \hgext{mq} junto con la orden
igor@453: \command{interdiff} está en la sección~\ref{mq-collab:tips:interdiff}.
igor@453: 
igor@453: \subsection{Definición de alias de comandos}
jerojasro@336: 
jerojasro@336: It can be cumbersome to remember the options to both the
jerojasro@336: \hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use,
jerojasro@336: so the \hgext{extdiff} extension lets you define \emph{new} commands
jerojasro@336: that will invoke your diff viewer with exactly the right options.
jerojasro@336: 
jerojasro@336: All you need to do is edit your \hgrc, and add a section named
jerojasro@336: \rcsection{extdiff}.  Inside this section, you can define multiple
jerojasro@336: commands.  Here's how to add a \texttt{kdiff3} command.  Once you've
jerojasro@336: defined this, you can type ``\texttt{hg kdiff3}'' and the
jerojasro@336: \hgext{extdiff} extension will run \command{kdiff3} for you.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extdiff]
jerojasro@336:   cmd.kdiff3 =
jerojasro@336: \end{codesample2}
jerojasro@336: If you leave the right hand side of the definition empty, as above,
jerojasro@336: the \hgext{extdiff} extension uses the name of the command you defined
jerojasro@336: as the name of the external program to run.  But these names don't
jerojasro@336: have to be the same.  Here, we define a command named ``\texttt{hg
jerojasro@336:   wibble}'', which runs \command{kdiff3}.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extdiff]
jerojasro@336:   cmd.wibble = kdiff3
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: You can also specify the default options that you want to invoke your
jerojasro@336: diff viewing program with.  The prefix to use is ``\texttt{opts.}'',
jerojasro@336: followed by the name of the command to which the options apply.  This
jerojasro@336: example defines a ``\texttt{hg vimdiff}'' command that runs the
jerojasro@336: \command{vim} editor's \texttt{DirDiff} extension.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extdiff]  
jerojasro@336:   cmd.vimdiff = vim
jerojasro@336:   opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \section{Cherrypicking changes with the \hgext{transplant} extension}
jerojasro@336: \label{sec:hgext:transplant}
jerojasro@336: 
jerojasro@336: Need to have a long chat with Brendan about this.
jerojasro@336: 
jerojasro@336: \section{Send changes via email with the \hgext{patchbomb} extension}
jerojasro@336: \label{sec:hgext:patchbomb}
jerojasro@336: 
jerojasro@336: Many projects have a culture of ``change review'', in which people
jerojasro@336: send their modifications to a mailing list for others to read and
jerojasro@336: comment on before they commit the final version to a shared
jerojasro@336: repository.  Some projects have people who act as gatekeepers; they
jerojasro@336: apply changes from other people to a repository to which those others
jerojasro@336: don't have access.
jerojasro@336: 
jerojasro@336: Mercurial makes it easy to send changes over email for review or
jerojasro@336: application, via its \hgext{patchbomb} extension.  The extension is so
jerojasro@336: namd because changes are formatted as patches, and it's usual to send
jerojasro@336: one changeset per email message.  Sending a long series of changes by
jerojasro@336: email is thus much like ``bombing'' the recipient's inbox, hence
jerojasro@336: ``patchbomb''.
jerojasro@336: 
jerojasro@336: As usual, the basic configuration of the \hgext{patchbomb} extension
jerojasro@336: takes just one or two lines in your \hgrc.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [extensions]
jerojasro@336:   patchbomb =
jerojasro@336: \end{codesample2}
jerojasro@336: Once you've enabled the extension, you will have a new command
jerojasro@336: available, named \hgxcmd{patchbomb}{email}.
jerojasro@336: 
jerojasro@336: The safest and best way to invoke the \hgxcmd{patchbomb}{email}
jerojasro@336: command is to \emph{always} run it first with the
jerojasro@336: \hgxopt{patchbomb}{email}{-n} option.  This will show you what the
jerojasro@336: command \emph{would} send, without actually sending anything.  Once
jerojasro@336: you've had a quick glance over the changes and verified that you are
jerojasro@336: sending the right ones, you can rerun the same command, with the
jerojasro@336: \hgxopt{patchbomb}{email}{-n} option removed.
jerojasro@336: 
jerojasro@336: The \hgxcmd{patchbomb}{email} command accepts the same kind of
jerojasro@336: revision syntax as every other Mercurial command.  For example, this
jerojasro@336: command will send every revision between 7 and \texttt{tip},
jerojasro@336: inclusive.
jerojasro@336: \begin{codesample2}
jerojasro@336:   hg email -n 7:tip
jerojasro@336: \end{codesample2}
jerojasro@336: You can also specify a \emph{repository} to compare with.  If you
jerojasro@336: provide a repository but no revisions, the \hgxcmd{patchbomb}{email}
jerojasro@336: command will send all revisions in the local repository that are not
jerojasro@336: present in the remote repository.  If you additionally specify
jerojasro@336: revisions or a branch name (the latter using the
jerojasro@336: \hgxopt{patchbomb}{email}{-b} option), this will constrain the
jerojasro@336: revisions sent.
jerojasro@336: 
jerojasro@336: It's perfectly safe to run the \hgxcmd{patchbomb}{email} command
jerojasro@336: without the names of the people you want to send to: if you do this,
jerojasro@336: it will just prompt you for those values interactively.  (If you're
jerojasro@336: using a Linux or Unix-like system, you should have enhanced
jerojasro@336: \texttt{readline}-style editing capabilities when entering those
jerojasro@336: headers, too, which is useful.)
jerojasro@336: 
jerojasro@336: When you are sending just one revision, the \hgxcmd{patchbomb}{email}
jerojasro@336: command will by default use the first line of the changeset
jerojasro@336: description as the subject of the single email message it sends.
jerojasro@336: 
jerojasro@336: If you send multiple revisions, the \hgxcmd{patchbomb}{email} command
jerojasro@336: will usually send one message per changeset.  It will preface the
jerojasro@336: series with an introductory message, in which you should describe the
jerojasro@336: purpose of the series of changes you're sending.
jerojasro@336: 
jerojasro@336: \subsection{Changing the behaviour of patchbombs}
jerojasro@336: 
jerojasro@336: Not every project has exactly the same conventions for sending changes
jerojasro@336: in email; the \hgext{patchbomb} extension tries to accommodate a
jerojasro@336: number of variations through command line options.
jerojasro@336: \begin{itemize}
jerojasro@336: \item You can write a subject for the introductory message on the
jerojasro@336:   command line using the \hgxopt{patchbomb}{email}{-s} option.  This
jerojasro@336:   takes one argument, the text of the subject to use.
jerojasro@336: \item To change the email address from which the messages originate,
jerojasro@336:   use the \hgxopt{patchbomb}{email}{-f} option.  This takes one
jerojasro@336:   argument, the email address to use.
jerojasro@336: \item The default behaviour is to send unified diffs (see
jerojasro@336:   section~\ref{sec:mq:patch} for a description of the format), one per
jerojasro@336:   message.  You can send a binary bundle instead with the
jerojasro@336:   \hgxopt{patchbomb}{email}{-b} option.  
jerojasro@336: \item Unified diffs are normally prefaced with a metadata header.  You
jerojasro@336:   can omit this, and send unadorned diffs, with the
jerojasro@336:   \hgxopt{patchbomb}{email}{--plain} option.
jerojasro@336: \item Diffs are normally sent ``inline'', in the same body part as the
jerojasro@336:   description of a patch.  This makes it easiest for the largest
jerojasro@336:   number of readers to quote and respond to parts of a diff, as some
jerojasro@336:   mail clients will only quote the first MIME body part in a message.
jerojasro@336:   If you'd prefer to send the description and the diff in separate
jerojasro@336:   body parts, use the \hgxopt{patchbomb}{email}{-a} option.
jerojasro@336: \item Instead of sending mail messages, you can write them to an
jerojasro@336:   \texttt{mbox}-format mail folder using the
jerojasro@336:   \hgxopt{patchbomb}{email}{-m} option.  That option takes one
jerojasro@336:   argument, the name of the file to write to.
jerojasro@336: \item If you would like to add a \command{diffstat}-format summary to
jerojasro@336:   each patch, and one to the introductory message, use the
jerojasro@336:   \hgxopt{patchbomb}{email}{-d} option.  The \command{diffstat}
jerojasro@336:   command displays a table containing the name of each file patched,
jerojasro@336:   the number of lines affected, and a histogram showing how much each
jerojasro@336:   file is modified.  This gives readers a qualitative glance at how
jerojasro@336:   complex a patch is.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: %%% Local Variables: 
jerojasro@336: %%% mode: latex
jerojasro@336: %%% TeX-master: "00book"
jerojasro@336: %%% End: 




