
jerojasro@437: \chapter{Manejo de eventos en repositorios mediante ganchos}
jerojasro@336: \label{chap:hook}
jerojasro@336: 
jerojasro@435: Mercurial ofrece un poderoso mecanismo para permitirle a usted
jerojasro@435: automatizar la ejecución de acciones en respuesta a eventos que
jerojasro@435: ocurran en un repositorio. En algunos casos, usted puede controlar
jerojasro@435: incluso la respuesta de Mercurial a dichos eventos.
jerojasro@435: 
jerojasro@435: Mercurial usa el término \emph{gancho} para identificar estas
jerojasro@435: acciones. Los ganchos son conocidos como ``disparadores'' en algunos
jerojasro@435: sistemas de control de revisiones, pero los dos nombres se refieren al
jerojasro@435: mismo concepto.
jerojasro@435: 
jerojasro@435: \section{Vistazo general de ganchos en Mercurial}
jerojasro@435: 
jerojasro@435: A continuación se encuentra una breve lista de los ganchos que
jerojasro@435: Mercurial soporta. Volveremos a cada uno de estos ganchos con más
jerojasro@435: detalle después, en la sección~\ref{sec:hook:ref}.
jerojasro@435: 
jerojasro@435: \begin{itemize}
jerojasro@435: \item[\small\hook{changegroup}] Es ejecutado luego de que un grupo de
jerojasro@435:     conjuntos de cambios ha sido traído al repositorio desde algún
jerojasro@435:     otro sitio.
jerojasro@435: \item[\small\hook{commit}] Es ejecutado después de la creación de
jerojasro@435:     un conjunto de cambios en el repositorio local.
jerojasro@435: \item[\small\hook{incoming}] Es ejecutado una vez por cada conjunto de
jerojasro@435:     cambios traído al repositorio desde otra ubicación. Note la
jerojasro@435:     diferencia respecto al gancho \hook{changegroup}, que es ejecutado
jerojasro@435:     una vez por cada \emph{grupo} de conjuntos de cambios que se
jerojasro@435:     traiga.
jerojasro@435: \item[\small\hook{outgoing}] Es ejecutado luego de que un grupo de
jerojasro@435:     conjuntos de cambios ha sido transmitido desde el repositorio.
jerojasro@435: \item[\small\hook{prechangegroup}] Es ejecutado antes de iniciar la
jerojasro@435:     recepción de un grupo de conjuntos de cambios en el repositorio.
jerojasro@435: \item[\small\hook{precommit}] De control. Es ejecutado antes de
jerojasro@435:     iniciar una consignación.
jerojasro@435: \item[\small\hook{preoutgoing}] De control. Es ejecutado antes de
jerojasro@435:     iniciar la transmisión de un grupo de conjuntos de cambios desde
jerojasro@435:     el repositorio.
jerojasro@435: \item[\small\hook{pretag}] De control. Es ejecutado antes de crear una
jerojasro@435:     etiqueta.
jerojasro@435: \item[\small\hook{pretxnchangegroup}] De control. Es ejecutado después
jerojasro@435:     de haber recibido un grupo de conjuntos de cambios en el
jerojasro@435:     repositorio local, pero antes de que la transacción se complete y
jerojasro@435:     los cambios sean permanentes dentro del repositorio.
jerojasro@435: \item[\small\hook{pretxncommit}] De control. Es ejecutado luego de la
jerojasro@435:     creación de un conjunto de cambios en el repositorio local, pero
jerojasro@435:     antes de que la transacción que hace permanente el cambio sea
jerojasro@435:     completada.
jerojasro@435: \item[\small\hook{preupdate}] De control. Es ejecutado antes de
jerojasro@435:     iniciar una actualización o fusión en el directorio de trabajo.
jerojasro@435: \item[\small\hook{tag}] Es ejecutado después de la creación de una
jerojasro@435:     etiqueta.
jerojasro@435: \item[\small\hook{update}] Es ejecutado después de que termina una
jerojasro@435:     actualización o una fusión.
jerojasro@435: \end{itemize}
jerojasro@435: Cada uno de los ganchos cuya descripción empieza con la frase
jerojasro@435: ``de control'' tiene la facultad de determinar si una actividad puede
jerojasro@435: continuar. Si el gancho se ejecuta con éxito, la actividad puede
jerojasro@435: continuar; si falla, o bien la actividad no es permitida, o se
jerojasro@435: deshacen los cambios que se puedan haber llevado a cabo, dependiendo
jerojasro@435: del gancho involucrado.
jerojasro@435: 
jerojasro@435: \section{Ganchos y seguridad}
jerojasro@435: 
jerojasro@435: \subsection{Los ganchos se ejecutan con sus privilegios de usuario}
jerojasro@435: 
jerojasro@435: Cuando usted ejecuta un comando de Mercurial en un repositorio, y el
jerojasro@435: comando causa la ejecución de un gancho, dicho gancho se ejecuta en
jerojasro@435: \emph{su} sistema, en \emph{su} cuenta de usuario, con \emph{sus}
jerojasro@435: privilegios. Ya que los ganchos son elementos arbitrarios de código
jerojasro@435: ejecutable, usted debería tratarlos con un nivel adecuado de
jerojasro@435: desconfianza. No instale un gancho a menos en que confíe en quien lo
jerojasro@435: creó y en lo que el gancho hace.
jerojasro@435: 
jerojasro@435: En algunos casos, usted puede estar expuesto a ganchos que usted no
jerojasro@435: %TODO acá introduzco algo de texto por mi cuenta, por claridad
jerojasro@435: instaló. Si usted usa Mercurial en un sistema extraño, tenga en cuenta
jerojasro@435: que Mercurial ejecutará los ganchos definidos en el fichero \hgrc.
jerojasro@435: 
jerojasro@435: Si está trabajando con un repositorio propiedad de otro usuario,
jerojasro@435: Mercurial podrá ejecutar los ganchos definidos en el repositorio de
jerojasro@435: dicho usuario, pero los ejecutará como ``usted''. Por ejemplo, si
jerojasro@435: usted jala (\hgcmd{pull}) desde ese repositorio, y el
jerojasro@435: \sfilename{.hg/hgrc} define un gancho saliente (\hook{outgoing}),
jerojasro@435: dicho gancho se ejecuta bajo su cuenta de usuario, aun cuando usted no
jerojasro@435: es el propietario del repositorio.
jerojasro@336: 
jerojasro@336: \begin{note}
jerojasro@435:   Esto sólo aplica si usted está jalando desde un repositorio en un
jerojasro@435:   sistema de ficheros local o de red. Si está jalando a través de http
jerojasro@435:   o ssh, cualquier gancho saliente (\hook{outgoing}) se ejecutará bajo
jerojasro@435:   la cuenta que está ejecutando el proceso servidor, en el servidor.
jerojasro@336: \end{note}
jerojasro@336: 
jerojasro@435: XXX Para ver qué ganchos han sido definidos en un repositorio, use el
jerojasro@435: comando \hgcmdargs{config}{hooks}. Si usted está trabajando en un
jerojasro@435: repositorio, pero comunicándose con otro que no le pertenece
jerojasro@435: (por ejemplo, usando \hgcmd{pull} o \hgcmd{incoming}), recuerde que
jerojasro@435: los ganchos que debe considerar son los del otro repositorio, no los
jerojasro@435: del suyo.
jerojasro@435: 
jerojasro@435: \subsection{Los ganchos no se propagan}
jerojasro@435: 
jerojasro@435: En Mercurial, no se hace control de revisiones de los ganchos, y no se
jerojasro@435: propagan cuando usted clona, o jala de, un repositorio. El motivo para
jerojasro@435: esto es simple: un gancho es código ejecutable arbitrario. Se ejecuta
jerojasro@435: bajo su identidad, con su nivel de privilegios, en su máquina.
jerojasro@435: 
jerojasro@435: Sería extremadamente descuidado de parte de cualquier sistema
jerojasro@435: distribuido de control de revisiones el implementar control de
jerojasro@435: revisiones para ganchos, ya que esto ofrecería maneras fácilmente
jerojasro@435: %TODO subvertir
jerojasro@435: aprovechables de subvertir las cuentas de los usuarios del sistema de
jerojasro@435: control de revisiones.
jerojasro@435: 
jerojasro@435: Ya que Mercurial no propaga los ganchos, si usted está colaborando con
jerojasro@435: otras personas en un proyecto común, no debería asumir que ellos están
jerojasro@435: usando los mismos ganchos para Mercurial que usted usa, o que los de
jerojasro@435: ellos están configurado correctamente. Usted debería documentar los
jerojasro@435: ganchos que usted espera que la gente use.
jerojasro@336: 
jerojasro@437: En una intranet corporativa, esto es algo más fácil de manejar, ya que
jerojasro@437: usted puede, por ejemplo, proveer una instalación ``estándar'' de
jerojasro@437: Mercurial en un sistema de ficheros NFS, y usar un fichero \hgrc\
jerojasro@437: global para definir los ganchos que verán todos los usuarios. Sin
jerojasro@437: embargo, este enfoque tiene sus límites; vea más abajo.
jerojasro@336: 
jerojasro@441: \subsection{Es posible hacer caso omiso de los ganchos}
jerojasro@441: 
jerojasro@441: Mercurial le permite hacer caso omiso de la deficinión de un gancho,
jerojasro@441: a través de la redefinición del mismo. Usted puede deshabilitar el
jerojasro@441: gancho fijando su valor como una cadena vacía, o cambiar su
jerojasro@441: comportamiento como desee.
jerojasro@441: 
jerojasro@441: Si usted instala un fichero \hgrc\ a nivel de sistema o sitio completo
jerojasro@441: que define algunos ganchos, debe entender que sus usuarios pueden
jerojasro@441: deshabilitar o hacer caso omiso de los mismos.
jerojasro@441: 
jerojasro@441: \subsection{Asegurarse de que ganchos críticos sean ejecutados}
jerojasro@441: 
jerojasro@441: Algunas veces usted puede querer hacer respetar una política, y no
jerojasro@441: permitir que los demás sean capaces de evitarla. Por ejemplo, usted
jerojasro@441: puede tener como requerimiento que cada conjunto de cambios debe pasar
jerojasro@441: un riguroso conjunto de pruebas. Definir este requerimientos a través
jerojasro@441: de un gancho en un fichero \hgrc\ global no servirá con usuarios
jerojasro@441: remotos en computadoras portátiles, y por supuesto que los usuarios
jerojasro@441: locales pueden evitar esto a voluntad haciendo caso omiso del gancho.
jerojasro@441: 
jerojasro@441: En vez de eso, usted puede definir las políticas para usar Mercurial
jerojasro@441: de tal forma que se espere que los usuarios propaguen los cambios a
jerojasro@441: través de un servidor ``canónico'' bien conocido que usted ha
jerojasro@441: asegurado y configurado apropiadamente.
jerojasro@441: 
jerojasro@441: Una manera de hacer esto es a través de una combinación de ingeniería
jerojasro@441: socual y tecnología. Cree una cuenta de acceso restringido; los
jerojasro@441: usuarios pueden empujar cambios a través de la red a los repositorios
jerojasro@441: administrados por esta cuenta, pero no podrán ingresar a dicha cuenta
jerojasro@441: para ejecutar órdenes en el intérprete de comandos. En este escenario,
jerojasro@441: un usuario puede enviar un conjunto de cambios que contenga la
jerojasro@441: porquería que él desee.
jerojasro@441: 
jerojasro@441: Cuando alguien empuja un conjunto de cambios al servidor del que todos
jerojasro@441: jalan, el servidor probará el conjunto de cambios antes de aceptarlo
jerojasro@441: como permanente, y lo rechazará si no logra pasar el conjunto de
jerojasro@441: pruebas. Si la gente sólo jala cambios desde este servidor de filtro,
jerojasro@441: servirá para asegurarse de que todos los cambios que la gente jala han
jerojasro@441: sido examinados automáticamente
jerojasro@441: 
jerojasro@441: \section{Precauciones con ganchos \texttt{pretxn} en un repositorio de
jerojasro@441: acceso compartido}
jerojasro@441: 
jerojasro@441: Si usted desea usar ganchos para llevar a cabo automáticamente algún
jerojasro@441: trabajo en un repositorio al que varias personas tienen acceso
jerojasro@441: compartido, debe tener cuidado con la forma de hacerlo.
jerojasro@441: 
jerojasro@441: Mercurial sólo bloquea un repositorio cuando está escribiendo al
jerojasro@441: mismo, y sólo las partes de Mercurial que escriben al repositorio le
jerojasro@441: prestan atención a los bloqueos. Los bloqueos de escritura son
jerojasro@441: necesarios para evitar que múltiples escritores simultáneos
jerojasro@441: interfieran entre sí, corrompiendo el repositorio.
jerojasro@441: 
jerojasro@441: Ya que Mercurial tiene cuidado con el orden en que lee y escribe
jerojasro@441: datos, no necesita adquirir un bloqueo cuando desea leer datos del
jerojasro@441: repositorio. Las partes de Mercurial que leen del repositorio nunca le
jerojasro@441: prestan atención a los bloqueos. Este esquema de lectura libre de
jerojasro@441: bloqueos incremententa en gran medida el desempeño y la concurrencia.
jerojasro@441: 
jerojasro@441: Sin embargo, para tener un gran desempeño es necesario hacer
jerojasro@441: sacrificios, uno de los cuales tiene el potencial de causarle
jerojasro@441: problemas a menos de que usted esté consciente de él. Describirlo
jerojasro@441: requiere algo de detalle respecto a cómo Mercurial añade conjuntos de
jerojasro@441: cambios al repositorio y cómo lee esos cambios de vuelta.
jerojasro@441: 
jerojasro@441: Cuando Mercurial \emph{escribe} metadatos, los escribe directamente en
jerojasro@441: el fichero de destino. Primero escribe los datos del fichero, luego
jerojasro@441: los datos del manifiesto (que contienen punteros a los nuevos datos
jerojasro@441: del fichero), luego datos de la bitácora de cambios (que contienen
jerojasro@441: punteros a los nuevos datos del manifiesto). Antes de la primera
jerojasro@441: escritura a cada fichero, se guarda un registro de dónde estaba el
jerojasro@441: final de fichero en su registro de transacciones. Si la transacción
jerojasro@441: debe ser deshecha, Mercurial simplemente trunca cada fichero de vuelta
jerojasro@441: al tamaño que tenía antes de que empezara la transacción.
jerojasro@441: 
jerojasro@441: Cuando Mercurial \emph{lee} metadatos, lee la bitácora de cambios
jerojasro@441: primero, y luego todo lo demás. Como un lector sólo accederá a las
jerojasro@441: partes del manifiesto o de los metadatos de fichero que él puede ver
jerojasro@441: en la bitácora de cambios, nunca puede ver datos parcialmente
jerojasro@441: escritos.
jerojasro@441: 
jerojasro@441: Algunos ganchos de control (\hook{pretxncommit} y
jerojasro@441: \hook{pretxnchangegroup}) se ejecutan cuando una transacción está casi
jerojasro@441: completa. Todos los metadatos han sido escritos, pero Mercurial aún
jerojasro@441: puede deshacer la transacción y hacer que los datos recién escritos
jerojasro@441: desaparezcan.
jerojasro@441: 
jerojasro@441: Si alguno de estos ganchos permanece en ejecución por mucho tiempo,
jerojasro@441: abre una ventana de tiempo en la que un lector puede ver los metadatos
jerojasro@441: de conjuntos de cambios que aún no son permanentes y que no debería
jerojasro@441: considerarse que estén ``realmante ahí''. Entre más tiempo tome la
jerojasro@441: ejecución del gancho, más tiempo estará abierta esta ventana.
jerojasro@441: 
jerojasro@441: \subsection{Ilustración del problema}
jerojasro@441: 
jerojasro@441: En principio, un buen uso del gancho \hook{pretxnchangegroup} sería
jerojasro@441: ensamblar y probar automáticamente todos los cambios entrantes antes
jerojasro@441: de que sean aceptados en un repositorio central. Esto le permitiría a
jerojasro@441: usted garantizar que nadie pueda empujar cambios que ``rompan el
jerojasro@441: ensamblaje''. Pero si un cliente puede jalar cambios mientras están
jerojasro@441: siendo probados, la utilidad de esta prueba es nula; alguien confiado
jerojasro@441: puede jalar cambios sin probar, lo que potencialmente podría romper su
jerojasro@441: proceso de ensamblaje.
jerojasro@441: 
jerojasro@441: La respuesta técnica más segura frente a este retos es montar dicho
jerojasro@441: repositorio ``guardián'' como \emph{unidireccional}. Permita que
jerojasro@441: reciba cambios desde el exterior, pero no permita que nadie jale
jerojasro@441: cambios de él (use el gancho \hook{preoutgoing} para bloquear esto).
jerojasro@441: Configure un gancho \hook{changegroup} para que si el ensamblaje o
jerojasro@441: prueba tiene éxito, el gancho empuje los nuevos cambios a otro
jerojasro@441: repositorio del que la gente \emph{pueda} jalar.
jerojasro@441: 
jerojasro@441: En la práctica, montar un cuello de botella centralizado como éste a
jerojasro@441: menudo no es una buena idea, y la visibilidad de las transacciones no
jerojasro@441: tiene nada que ver con el problema. A medida que el tamaño de un
jerojasro@441: proyecto---y el tiempo que toma ensamblarlo y probarlo---crece, usted
jerojasro@441: se acerca rápidamente a un límite con este enfoque ``pruebe antes de
jerojasro@441: comprar'', en el que tiene más conjuntos de cambios a probar que
jerojasro@441: tiempo para ocuparse de ellos. El resultado inevitable es frustración
jerojasro@441: para todos los que estén involucrados.
jerojasro@441: 
jerojasro@441: Una aproximación que permite manejar mejor el crecimiento es hacer que
jerojasro@441: la gente ensamble y pruebe antes de empujar, y ejecutar el ensamble y
jerojasro@441: pruebas automáticas centralmente \emph{después} de empujar, para
jerojasro@441: asegurarse de que todo esté bien. La ventaja de este enfoque es que no
jerojasro@441: impone un límite a la rata en la que un repositorio puede aceptar
jerojasro@441: cambios.
jerojasro@441: 
jerojasro@441: \section{Tutorial corto de uso de ganchos}
jerojasro@336: \label{sec:hook:simple}
jerojasro@336: 
jerojasro@442: Escribir un gancho para Mercurial es fácil. Empecemos con un gancho
jerojasro@442: que se ejecute cuando usted termine un \hgcmd{commit}, y simplemente
jerojasro@442: muestre el hash del conjunto de cambios que usted acaba de crear. El
jerojasro@442: gancho se llamará \hook{commit}.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.simple.init}
jerojasro@442:   \caption{Un gancho simple que se ejecuta al hacer la consignación de
jerojasro@442:   un conjunto de cambios}
jerojasro@336:   \label{ex:hook:init}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@442: Todos los ganchos siguen el patrón del ejemplo~\ref{ex:hook:init}.
jerojasro@442: Usted puede añadir una entrada a la sección \rcsection{hooks} de su
jerojasro@442: fichero \hgrc.  A la izquierda está el nombre del evento respecto al
jerojasro@442: cual dispararse; a la derecha está la acción a llevar a cabo. Como
jerojasro@442: puede ver, es posible ejecutar cualquier orden de la línea de comandos
jerojasro@442: en un gancho. Mercurial le pasa información extra al gancho usando
jerojasro@442: variables de entorno (busque \envar{HG\_NODE} en el ejemplo).
jerojasro@442: 
jerojasro@442: \subsection{Llevar a cabo varias acciones por evento}
jerojasro@442: 
jerojasro@442: A menudo, usted querrá definir más de un gancho para un tipo de evento
jerojasro@442: particular, como se muestra en el ejemplo~\ref{ex:hook:ext}. 
jerojasro@442: Mercurial le permite hacer esto añadiendo una \emph{extensión} al
jerojasro@442: final del nombre de un gancho. Usted extiende el nombre del gancho
jerojasro@442: %TODO Yuk, no me gusta ese "parada completa"
jerojasro@442: poniendo el nombre del gancho, seguido por una parada completa (el
jerojasro@442: caracter ``\texttt{.}''), seguido de algo más de texto de su elección.
jerojasro@442: Por ejemplo, Mercurial ejecutará tanto \texttt{commit.foo} como
jerojasro@442: \texttt{commit.bar} cuando ocurra el evento \texttt{commit}.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.simple.ext}
jerojasro@442:   \caption{Definición de un segundo gancho \hook{commit}}
jerojasro@336:   \label{ex:hook:ext}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@442: Para dar un orden bien definido de ejecución cuando hay múltiples
jerojasro@442: ganchos definidos para un evento, Mercurial ordena los ganchos de
jerojasro@442: acuerdo a su extensión, y los ejecuta en dicho orden. En el ejemplo de
jerojasro@442: arribam \texttt{commit.bar} se ejecutará antes que
jerojasro@442: \texttt{commit.foo}, y \texttt{commit} se ejecutará antes de ambos.
jerojasro@442: 
jerojasro@442: Es una buena idea usar una extensión descriptiva cuando usted define
jerojasro@442: un gancho. Esto le ayudará a recordar para qué se usa el gancho. Si el
jerojasro@442: gancho falla, usted recibirá un mensaje de error que contiene el
jerojasro@442: nombre y la extensión del gancho, así que usar una extensión
jerojasro@442: descriptiva le dará una pista inmediata de porqué el gancho falló (vea
jerojasro@442: un ejemplo en la sección~\ref{sec:hook:perm}).
jerojasro@442: 
jerojasro@442: \subsection{Controlar cuándo puede llevarse a cabo una actividad}
jerojasro@336: \label{sec:hook:perm}
jerojasro@336: 
jerojasro@442: En los ejemplos anteriores, usamos el gancho \hook{commit}, que es
jerojasro@442: ejecutado después de que se ha completado una consignación. Este es
jerojasro@442: uno de los varios ganchos que Mercurial ejecuta luego de que una
jerojasro@442: actividad termina. Tales ganchos no tienen forma de influenciar la
jerojasro@442: actividad como tal.
jerojasro@442: 
jerojasro@442: Mercurial define un número de eventos que ocurren antes de que una
jerojasro@442: actividad empiece; o luego de que empiece, pero antes de que termine.
jerojasro@442: Los ganchos que se disparan con estos eventos tienen la capacidad
jerojasro@442: adicional de elegir si la actividad puede continuar, o si su ejecución
jerojasro@442: es abortada.
jerojasro@442: 
jerojasro@442: El gancho \hook{pretxncommit} se ejecuta justo antes de que una
jerojasro@442: consignación se ejecute. En otras palabras, los metadatos que
jerojasro@442: representan el conjunto de cambios han sido escritos al disco, pero no
jerojasro@442: se ha terminado la transacción. El gancho \hook{pretxncommit} tiene la
jerojasro@442: capacidad de decidir si una transacción se completa, o debe
jerojasro@442: deshacerse.
jerojasro@442: 
jerojasro@442: Si el gancho \hook{pretxncommit} termina con un código de salida de
jerojasro@442: cero, se permite que la transacción se complete; la consignación
jerojasro@442: termina; y el gancho \hook{commit} es ejecutado. Si el gancho
jerojasro@442: \hook{pretxncommit} termina con un código de salida diferente de cero,
jerojasro@442: la transacción es revertida; los metadatos representando el conjunto
jerojasro@442: de cambios son borrados; y el gancho \hook{commit} no es ejecutado.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.simple.pretxncommit}
jerojasro@442:   \caption{Uso del gancho \hook{pretxncommit} hook to control commits}
jerojasro@336:   \label{ex:hook:pretxncommit}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@452: El gancho en el ejemplo~\ref{ex:hook:pretxncommit} revisa si el
jerojasro@452: mensaje de consignación contiene el ID de algún fallo. Si lo contiene,
jerojasro@452: la consignación puede continuar. Si no, la consignación es cancelada.
jerojasro@452: 
jerojasro@452: \section{Escribir sus propios ganchos}
jerojasro@452: 
jerojasro@452: Cuando usted escriba un gancho, puede encontrar útil el ejecutar
jerojasro@452: Mercurial o bien pasándole la opción \hggopt{-v}, o con el valor de
jerojasro@452: configuración \rcitem{ui}{verbose} fijado en ``true'' (verdadero).
jerojasro@452: Cuando lo haga, Mercurial imprimirá un mensaje antes de llamar cada
jerojasro@452: gancho.
jerojasro@452: 
jerojasro@452: \subsection{Escoger cómo debe ejecutarse su gancho}
jerojasro@336: \label{sec:hook:lang}
jerojasro@336: 
jerojasro@452: Usted puede escribir un gancho que funcione como un programa normal
jerojasro@452: ---típicamente un guión de línea de comandos---o como una función de
jerojasro@452: Python que se ejecuta dentro del proceso Mercurial.
jerojasro@452: 
jerojasro@452: Escribir un gancho como un programa externo tiene la ventaja de que no
jerojasro@452: requiere ningún conocimiento del funcionamiento interno de Mercurial.
jerojasro@452: Usted puede ejecutar comandos Mercurial normales para obtener la
jerojasro@452: informción extra que pueda necesitar. La contraparte de esto es que
jerojasro@452: los ganchos externos son más lentos que los ganchos internos
jerojasro@452: ejecutados dentro del proceso.
jerojasro@452: 
jerojasro@452: Un gancho Python interno tiene acceso completo a la API de Mercurial,
jerojasro@452: y no se ``externaliza'' a otro proceso, así que es inherentemente más
jerojasro@452: rápido que un gancho externo. Adicionalmente es más fácil obtener la
jerojasro@452: mayoría de la información que un gancho requiere a través de llamadas
jerojasro@452: directas a la API de Mercurial que hacerlo ejecutando comandos
jerojasro@452: Mercurial.
jerojasro@452: 
jerojasro@452: Si se siente a gusto con Python, o requiere un alto desempeño,
jerojasro@452: escribir sus ganchos en Python puede ser una buena elección. Sin
jerojasro@452: embargo, cuando usted tiene un gancho bastante directo por escribir y
jerojasro@452: no le importa el desempeño (el caso de la mayoría de los ganchos), es
jerojasro@452: perfectamente admisible un guión de línea de comandos.
jerojasro@336: 
jerojasro@461: \subsection{Parámetros para ganchos}
jerojasro@336: \label{sec:hook:param}
jerojasro@336: 
jerojasro@461: Mercurial llama cada gancho con un conjunto de paŕametros bien
jerojasro@461: definidos. En Python, un parámetro se pasa como argumento de palabra
jerojasro@461: clave a su función de gancho. Para un programa externo, los parámetros
jerojasro@461: son pasados como variables de entornos.
jerojasro@461: 
jerojasro@461: Sin importar si su gancho está escrito en Python o como guión de línea
jerojasro@461: de comandos, los nombres y valores de los parámetros específicos de
jerojasro@461: los ganchos serán los mismos. Un parámetro booleano será representado
jerojasro@461: como un valor booleano en Python, pero como el número 1 (para
jerojasro@461: ``verdadero'') o 0 (para falso) en una variable de entorno para un
jerojasro@461: gancho externo. Si un parámetro se llama \texttt{foo}, el argumento de
jerojasro@461: palabra clave para un gancho en Python también se llamará
jerojasro@461: \texttt{foo}, mientras que la variable de entorno para un gancho
jerojasro@461: externo se llamará \texttt{HG\_FOO}.
jerojasro@461: 
jerojasro@461: \subsection{Valores de retorno de ganchos y control de actividades}
jerojasro@461: 
jerojasro@461: Un gancho que se ejecuta exitosamente debe terminar con un código de
jerojasro@461: salida de cero, si es externo, o retornar el valor booleano
jerojasro@461: ``falso'', si es interno. Un fallo se indica con un código de salida
jerojasro@461: diferente de cero desde un gancho externo, o un valor de retorno
jerojasro@461: booleano ``verdadero''. Si un gancho interno genera una excepción, se
jerojasro@461: considera que el gancho ha fallado.
jerojasro@461: 
jerojasro@461: Para los ganchos que controlan si una actividad puede continuar o no,
jerojasro@461: cero/falso quiere decir ``permitir'', mientras que
jerojasro@461: % TODO me suena mejor "no permitir" que "denegar"
jerojasro@461: no-cero/verdadero/excepción quiere decir ``no permitir''.
jerojasro@461: 
jerojasro@461: \subsection{Escribir un gancho externo}
jerojasro@461: 
jerojasro@461: Cuando usted define un gancho externo en su fichero \hgrc\ y el mismo
jerojasro@461: es ejecutado, dicha definición pasa a su intérprete de comandos, que
jerojasro@461: hace la interpretación correspondiente. Esto significa que usted puede
jerojasro@461: usar elementos normales del intérprete en el cuerpo del gancho.
jerojasro@461: 
jerojasro@461: Un gancho ejecutable siempre es ejecutado con su directorio actual
jerojasro@461: fijado al directorio raíz del repositorio.
jerojasro@461: 
jerojasro@461: Cada parámetro para el gancho es pasado como una variable de entorno;
jerojasro@461: el nombre está en mayúsculas, y tiene como prefijo la cadena
jerojasro@461: ``\texttt{HG\_}''.
jerojasro@461: 
jerojasro@461: Con la excepción de los parámetros para los ganchos, Mercurial no
jerojasro@461: define o modifica ninguna variable de entorno al ejecutar un gancho.
jerojasro@461: Es útil recordar esto al escribir un gancho global que podría ser
jerojasro@461: ejecutado por varios usuarios con distintas variables de entorno
jerojasro@461: fijadas. En situaciones con múltiples usuarios, usted no debería
jerojasro@461: asumir la existencia de ninguna variable de entorno, ni que sus
jerojasro@461: valores sean los mismos que tenían cuando usted probó el gancho en su
jerojasro@461: ambiente de trabajo.
jerojasro@461: 
jerojasro@461: \subsection{Indicar a Mercurial que use un gancho interno}
jerojasro@461: 
jerojasro@461: La sintaxis para definir un gancho interno en el fichero \hgrc\ es
jerojasro@461: ligeramente diferente de la usada para un gancho externo. El valor del
jerojasro@461: gancho debe comenzar con el texto ``\texttt{python:}'', y continuar
jerojasro@461: con el nombre completamente cualificado de un objeto invocable que se
jerojasro@461: usará como el valor del gancho.
jerojasro@461: 
jerojasro@461: El módulo en que vive un gancho es importado automáticamente cuando se
jerojasro@461: ejecuta un gancho. Siempre que usted tenga el nombre del módulo y la
jerojasro@461: variable de entorno \envar{PYTHONPATH} ajustada adecuadamente, todo
jerojasro@461: debería funcionar sin problemas.
jerojasro@461: 
jerojasro@461: El siguiente fragmento de ejemplo de un fichero \hgrc\ ilustra la
jerojasro@461: sintaxis y significado de los conceptos que acabamos de describir.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [hooks]
jerojasro@336:   commit.example = python:mymodule.submodule.myhook
jerojasro@336: \end{codesample2}
jerojasro@461: Cuando Mercurial ejecuta el gancho \texttt{commit.example}, importa 
jerojasro@461: \texttt{mymodule.submodule}, busca el objeto invocable llamado
jerojasro@461: \texttt{myhook}, y lo invoca (llama).
jerojasro@461: 
jerojasro@461: \subsection{Escribir un gancho interno}
jerojasro@461: 
jerojasro@461: El gancho interno más sencillo no hace nada, pero ilustra la
jerojasro@461: estructura básica de la API\footnote{\emph{Application Progamming
jerojasro@461: Interface}, Interfaz para Programación de Aplicaciones} para ganchos:
jerojasro@336: \begin{codesample2}
jerojasro@336:   def myhook(ui, repo, **kwargs):
jerojasro@336:       pass
jerojasro@336: \end{codesample2}
jerojasro@462: El primer argumento para un gancho Python siempre es un objeto
jerojasro@462: \pymodclass{mercurial.ui}{ui}.  El segundo es un objeto repositorio;
jerojasro@462: de momento, siempre es una instancia de 
jerojasro@462: \pymodclass{mercurial.localrepo}{localrepository}.  Después de estos
jerojasro@462: dos argumentos están los argumentos de palabra clave. Los argumentos
jerojasro@462: que se pasen dependerán del tipo de gancho que se esté llamando, pero
jerojasro@462: un gancho siempre puede ignorar los argumentos que no le interesen,
jerojasro@462: relegándolos a un diccionario de argumentos por palabras clave, como se
jerojasro@462: hizo arriba con \texttt{**kwargs}.
jerojasro@462: 
jerojasro@462: \section{Ejemplos de ganchos}
jerojasro@462: 
jerojasro@462: \subsection{Escribir mensajes de consignación significativos}
jerojasro@462: 
jerojasro@462: Es difícil de imaginar un mensaje de consignación útil y al mismo
jerojasro@462: tiempo muy corto. El simple gancho \hook{pretxncommit} de la
jerojasro@462: figura~\ref{ex:hook:msglen.go} evitará que usted consigne un conjunto
jerojasro@462: de cambios con un mensaje de menos de 10 bytes de longitud.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.msglen.go}
jerojasro@462:   \caption{Un gancho que prohíbe mensajes de consignación demasiado
jerojasro@462:   cortos}
jerojasro@336:   \label{ex:hook:msglen.go}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@462: \subsection{Comprobar espacios en blanco finales}
jerojasro@462: 
jerojasro@462: Un uso interesante para ganchos relacionados con consignaciones es
jerojasro@462: ayudarle a escribir código más limpio. Un ejemplo simple de
jerojasro@462: %TODO dictum => regla
jerojasro@462: ``código más limpio'' es la regla de que un cambio no debe añadir
jerojasro@462: líneas de texto que contengan ``espacios en blanco finales''. El
jerojasro@462: espacio en blanco final es una serie de caracteres de espacio y
jerojasro@462: tabulación que se encuentran al final de una línea de texto. En la
jerojasro@462: mayoría de los casos, el espacio en blanco final es innecesario, ruido
jerojasro@462: invisible, pero ocasionalmente es problemático, y la gente en general
jerojasro@462: prefiere deshacerse de él.
jerojasro@462: 
jerojasro@462: Usted puede usar cualquiera de los ganchos \hook{precommit} o
jerojasro@462: \hook{pretxncommit} para revisar si tiene el problema de los espacios
jerojasro@462: en blanco finales. Si usa el gancho \hook{precommit}, el gancho no
jerojasro@462: sabrá qué ficheros se están consignando, por lo que se tendrá que
jerojasro@462: revisar cada fichero modificado en el repositorio para ver si tiene
jerojasro@462: espacios en blanco finales. Si usted sólo quiere consignar un cambio
jerojasro@462: al fichero \filename{foo}, y el fichero \filename{bar} contiene
jerojasro@462: espacios en blanco finales, hacer la revisión en el gancho
jerojasro@462: \hook{precommit} evitará que usted haga la consignación de
jerojasro@462: \filename{foo} debido al problem en \filename{bar}.  Este no parece el
jerojasro@462: enfoque adeucado.
jerojasro@462: 
jerojasro@462: Si usted escogiera el gancho \hook{pretxncommit}, la revisión no
jerojasro@462: ocurriría sino hasta justo antes de que la transacción para la
jerojasro@462: consignación se complete. Esto le permitirá comprobar por posibles
jerojasro@462: problemas sólo en los ficheros que serán consignados. Sin embargo, si
jerojasro@462: usted ingresó el mensaje de consignación de manera interactiva y el
jerojasro@462: %TODO roll-back
jerojasro@462: gancho falla, la transacción será deshecha; usted tendrá que
jerojasro@462: reingresar el mensaje de consignación luego de que corrija el problema
jerojasro@462: con los espacios en blanco finales y ejecute \hgcmd{commit} de nuevo.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.ws.simple}
jerojasro@462:   \caption{Un gancho simple que revisa si hay espacios en blanco
jerojasro@462:   finales}
jerojasro@336:   \label{ex:hook:ws.simple}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@462: La figura~\ref{ex:hook:ws.simple} presenta un gancho
jerojasro@462: \hook{pretxncommit} simple que comprueba la existencia de espacios en
jerojasro@462: blanco finales. Este gancho es corto, pero no brinda mucha ayuda.
jerojasro@462: Termina con un código de salida de error si un cambio añade una línea
jerojasro@462: con espacio en blanco final a cualquier fichero, pero no muestra
jerojasro@462: ninguna información que pueda ser útil para identificar el fichero o
jerojasro@462: la línea de texto origen del problema. También tiene la agradable
jerojasro@462: propiedad de no prestar atención a las líneas que no sufrieron
jerojasro@462: modificaciones; sólo las líneas que introducen nuevos espacios en
jerojasro@462: blanco finales causan problemas.
jerojasro@336: 
jerojasro@336: \begin{figure}[ht]
jerojasro@336:   \interaction{hook.ws.better}
jerojasro@336:   \caption{A better trailing whitespace hook}
jerojasro@336:   \label{ex:hook:ws.better}
jerojasro@336: \end{figure}
jerojasro@336: 
jerojasro@462: El ejemplo de la figura~\ref{ex:hook:ws.better} es mucho más complejo,
jerojasro@462: pero también más útil. El gancho procesa un diff unificado para
jerojasro@462: revisar si alguna línea añade espacios en blanco finales, e imprime el
jerojasro@462: nombre del fichero y el número de línea de cada ocurrencia. Aún mejor,
jerojasro@462: si el cambio añade espacios en blanco finales, este gancho guarda el
jerojasro@462: mensaje de consignación e imprime el nombre del fichero en el que el
jerojasro@462: mensaje fue guardado, antes de terminar e indicarle a Mercurial que
jerojasro@462: deshaga la transacción, para que uste pueda usar
jerojasro@462: \hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{nombre\_fichero}} para
jerojasro@462: reutilizar el mensaje de consignación guardado anteriormente, una vez
jerojasro@462: usted haya corregido el problema.
jerojasro@462: 
jerojasro@462: Como anotación final, note que en la figura~\ref{ex:hook:ws.better} el
jerojasro@462: %TODO on-site => in-situ ?
jerojasro@462: uso de la característica de edición \emph{in-situ} de \command{perl}
jerojasro@462: para eliminar los espacios en blanco finales en un fichero. Esto es
jerojasro@462: lo suficientemente conciso y poderoso para que lo presente aquí.
jerojasro@463: % TODO corregí el backslash, y comprobé por mi cuenta un archivo
jerojasro@463: % aparte, y el comando hace lo que debe hacer. Favor copiar del pdf el
jerojasro@463: % comando perl y comprobar con un archivo con espacios en blanco
jerojasro@463: % finales, y si todo está bien (que debería), borrar esta nota
jerojasro@463: \begin{codesample2}
jerojasro@463:     perl -pi -e 's,\textbackslash{}s+\$,,' nombre\_fichero
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \section{Bundled hooks}
jerojasro@336: 
jerojasro@336: Mercurial ships with several bundled hooks.  You can find them in the
jerojasro@336: \dirname{hgext} directory of a Mercurial source tree.  If you are
jerojasro@336: using a Mercurial binary package, the hooks will be located in the
jerojasro@336: \dirname{hgext} directory of wherever your package installer put
jerojasro@336: Mercurial.
jerojasro@336: 
jerojasro@336: \subsection{\hgext{acl}---access control for parts of a repository}
jerojasro@336: 
jerojasro@336: The \hgext{acl} extension lets you control which remote users are
jerojasro@336: allowed to push changesets to a networked server.  You can protect any
jerojasro@336: portion of a repository (including the entire repo), so that a
jerojasro@336: specific remote user can push changes that do not affect the protected
jerojasro@336: portion.
jerojasro@336: 
jerojasro@336: This extension implements access control based on the identity of the
jerojasro@336: user performing a push, \emph{not} on who committed the changesets
jerojasro@336: they're pushing.  It makes sense to use this hook only if you have a
jerojasro@336: locked-down server environment that authenticates remote users, and
jerojasro@336: you want to be sure that only specific users are allowed to push
jerojasro@336: changes to that server.
jerojasro@336: 
jerojasro@336: \subsubsection{Configuring the \hook{acl} hook}
jerojasro@336: 
jerojasro@336: In order to manage incoming changesets, the \hgext{acl} hook must be
jerojasro@336: used as a \hook{pretxnchangegroup} hook.  This lets it see which files
jerojasro@336: are modified by each incoming changeset, and roll back a group of
jerojasro@336: changesets if they modify ``forbidden'' files.  Example:
jerojasro@336: \begin{codesample2}
jerojasro@336:   [hooks]
jerojasro@336:   pretxnchangegroup.acl = python:hgext.acl.hook
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: The \hgext{acl} extension is configured using three sections.  
jerojasro@336: 
jerojasro@336: The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
jerojasro@336: which lists the sources of incoming changesets that the hook should
jerojasro@336: pay attention to.  You don't normally need to configure this section.
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
jerojasro@336:   from a remote repository over http or ssh.  This is the default
jerojasro@336:   value of \rcitem{acl}{sources}, and usually the only setting you'll
jerojasro@336:   need for this configuration item.
jerojasro@336: \item[\rcitem{acl}{pull}] Control incoming changesets that are
jerojasro@336:   arriving via a pull from a local repository.
jerojasro@336: \item[\rcitem{acl}{push}] Control incoming changesets that are
jerojasro@336:   arriving via a push from a local repository.
jerojasro@336: \item[\rcitem{acl}{bundle}] Control incoming changesets that are
jerojasro@336:   arriving from another repository via a bundle.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: The \rcsection{acl.allow} section controls the users that are allowed to
jerojasro@336: add changesets to the repository.  If this section is not present, all
jerojasro@336: users that are not explicitly denied are allowed.  If this section is
jerojasro@336: present, all users that are not explicitly allowed are denied (so an
jerojasro@336: empty section means that all users are denied).
jerojasro@336: 
jerojasro@336: The \rcsection{acl.deny} section determines which users are denied
jerojasro@336: from adding changesets to the repository.  If this section is not
jerojasro@336: present or is empty, no users are denied.
jerojasro@336: 
jerojasro@336: The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
jerojasro@336: sections are identical.  On the left of each entry is a glob pattern
jerojasro@336: that matches files or directories, relative to the root of the
jerojasro@336: repository; on the right, a user name.
jerojasro@336: 
jerojasro@336: In the following example, the user \texttt{docwriter} can only push
jerojasro@336: changes to the \dirname{docs} subtree of the repository, while
jerojasro@336: \texttt{intern} can push changes to any file or directory except
jerojasro@336: \dirname{source/sensitive}.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [acl.allow]
jerojasro@336:   docs/** = docwriter
jerojasro@336: 
jerojasro@336:   [acl.deny]
jerojasro@336:   source/sensitive/** = intern
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \subsubsection{Testing and troubleshooting}
jerojasro@336: 
jerojasro@336: If you want to test the \hgext{acl} hook, run it with Mercurial's
jerojasro@336: debugging output enabled.  Since you'll probably be running it on a
jerojasro@336: server where it's not convenient (or sometimes possible) to pass in
jerojasro@336: the \hggopt{--debug} option, don't forget that you can enable
jerojasro@336: debugging output in your \hgrc:
jerojasro@336: \begin{codesample2}
jerojasro@336:   [ui]
jerojasro@336:   debug = true
jerojasro@336: \end{codesample2}
jerojasro@336: With this enabled, the \hgext{acl} hook will print enough information
jerojasro@336: to let you figure out why it is allowing or forbidding pushes from
jerojasro@336: specific users.
jerojasro@336: 
jerojasro@336: \subsection{\hgext{bugzilla}---integration with Bugzilla}
jerojasro@336: 
jerojasro@336: The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
jerojasro@336: whenever it finds a reference to that bug ID in a commit comment.  You
jerojasro@336: can install this hook on a shared server, so that any time a remote
jerojasro@336: user pushes changes to this server, the hook gets run.  
jerojasro@336: 
jerojasro@336: It adds a comment to the bug that looks like this (you can configure
jerojasro@336: the contents of the comment---see below):
jerojasro@336: \begin{codesample2}
jerojasro@336:   Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
jerojasro@336:   the frobnitz repository, refers to this bug.
jerojasro@336: 
jerojasro@336:   For complete details, see
jerojasro@336:   http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
jerojasro@336: 
jerojasro@336:   Changeset description:
jerojasro@336:         Fix bug 10483 by guarding against some NULL pointers
jerojasro@336: \end{codesample2}
jerojasro@336: The value of this hook is that it automates the process of updating a
jerojasro@336: bug any time a changeset refers to it.  If you configure the hook
jerojasro@336: properly, it makes it easy for people to browse straight from a
jerojasro@336: Bugzilla bug to a changeset that refers to that bug.
jerojasro@336: 
jerojasro@336: You can use the code in this hook as a starting point for some more
jerojasro@336: exotic Bugzilla integration recipes.  Here are a few possibilities:
jerojasro@336: \begin{itemize}
jerojasro@336: \item Require that every changeset pushed to the server have a valid
jerojasro@336:   bug~ID in its commit comment.  In this case, you'd want to configure
jerojasro@336:   the hook as a \hook{pretxncommit} hook.  This would allow the hook
jerojasro@336:   to reject changes that didn't contain bug IDs.
jerojasro@336: \item Allow incoming changesets to automatically modify the
jerojasro@336:   \emph{state} of a bug, as well as simply adding a comment.  For
jerojasro@336:   example, the hook could recognise the string ``fixed bug 31337'' as
jerojasro@336:   indicating that it should update the state of bug 31337 to
jerojasro@336:   ``requires testing''.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: \subsubsection{Configuring the \hook{bugzilla} hook}
jerojasro@336: \label{sec:hook:bugzilla:config}
jerojasro@336: 
jerojasro@336: You should configure this hook in your server's \hgrc\ as an
jerojasro@336: \hook{incoming} hook, for example as follows:
jerojasro@336: \begin{codesample2}
jerojasro@336:   [hooks]
jerojasro@336:   incoming.bugzilla = python:hgext.bugzilla.hook
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: Because of the specialised nature of this hook, and because Bugzilla
jerojasro@336: was not written with this kind of integration in mind, configuring
jerojasro@336: this hook is a somewhat involved process.
jerojasro@336: 
jerojasro@336: Before you begin, you must install the MySQL bindings for Python on
jerojasro@336: the host(s) where you'll be running the hook.  If this is not
jerojasro@336: available as a binary package for your system, you can download it
jerojasro@336: from~\cite{web:mysql-python}.
jerojasro@336: 
jerojasro@336: Configuration information for this hook lives in the
jerojasro@336: \rcsection{bugzilla} section of your \hgrc.
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
jerojasro@336:   the server.  The database schema that Bugzilla uses changes
jerojasro@336:   occasionally, so this hook has to know exactly which schema to use.
jerojasro@336:   At the moment, the only version supported is \texttt{2.16}.
jerojasro@336: \item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
jerojasro@336:   stores your Bugzilla data.  The database must be configured to allow
jerojasro@336:   connections from whatever host you are running the \hook{bugzilla}
jerojasro@336:   hook on.
jerojasro@336: \item[\rcitem{bugzilla}{user}] The username with which to connect to
jerojasro@336:   the MySQL server.  The database must be configured to allow this
jerojasro@336:   user to connect from whatever host you are running the
jerojasro@336:   \hook{bugzilla} hook on.  This user must be able to access and
jerojasro@336:   modify Bugzilla tables.  The default value of this item is
jerojasro@336:   \texttt{bugs}, which is the standard name of the Bugzilla user in a
jerojasro@336:   MySQL database.
jerojasro@336: \item[\rcitem{bugzilla}{password}] The MySQL password for the user you
jerojasro@336:   configured above.  This is stored as plain text, so you should make
jerojasro@336:   sure that unauthorised users cannot read the \hgrc\ file where you
jerojasro@336:   store this information.
jerojasro@336: \item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
jerojasro@336:   MySQL server.  The default value of this item is \texttt{bugs},
jerojasro@336:   which is the standard name of the MySQL database where Bugzilla
jerojasro@336:   stores its data.
jerojasro@336: \item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
jerojasro@336:   notification email to subscribers after this hook has added a
jerojasro@336:   comment to a bug, you will need this hook to run a command whenever
jerojasro@336:   it updates the database.  The command to run depends on where you
jerojasro@336:   have installed Bugzilla, but it will typically look something like
jerojasro@336:   this, if you have Bugzilla installed in
jerojasro@336:   \dirname{/var/www/html/bugzilla}:
jerojasro@336:   \begin{codesample4}
jerojasro@336:     cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
jerojasro@336:   \end{codesample4}
jerojasro@336:   The Bugzilla \texttt{processmail} program expects to be given a
jerojasro@336:   bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
jerojasro@336:   email address.  It also expects to be able to write to some files in
jerojasro@336:   the directory that it runs in.  If Bugzilla and this hook are not
jerojasro@336:   installed on the same machine, you will need to find a way to run
jerojasro@336:   \texttt{processmail} on the server where Bugzilla is installed.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: \subsubsection{Mapping committer names to Bugzilla user names}
jerojasro@336: 
jerojasro@336: By default, the \hgext{bugzilla} hook tries to use the email address
jerojasro@336: of a changeset's committer as the Bugzilla user name with which to
jerojasro@336: update a bug.  If this does not suit your needs, you can map committer
jerojasro@336: email addresses to Bugzilla user names using a \rcsection{usermap}
jerojasro@336: section.
jerojasro@336: 
jerojasro@336: Each item in the \rcsection{usermap} section contains an email address
jerojasro@336: on the left, and a Bugzilla user name on the right.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [usermap]
jerojasro@336:   jane.user@example.com = jane
jerojasro@336: \end{codesample2}
jerojasro@336: You can either keep the \rcsection{usermap} data in a normal \hgrc, or
jerojasro@336: tell the \hgext{bugzilla} hook to read the information from an
jerojasro@336: external \filename{usermap} file.  In the latter case, you can store
jerojasro@336: \filename{usermap} data by itself in (for example) a user-modifiable
jerojasro@336: repository.  This makes it possible to let your users maintain their
jerojasro@336: own \rcitem{bugzilla}{usermap} entries.  The main \hgrc\ file might
jerojasro@336: look like this:
jerojasro@336: \begin{codesample2}
jerojasro@336:   # regular hgrc file refers to external usermap file
jerojasro@336:   [bugzilla]
jerojasro@336:   usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
jerojasro@336: \end{codesample2}
jerojasro@336: While the \filename{usermap} file that it refers to might look like
jerojasro@336: this:
jerojasro@336: \begin{codesample2}
jerojasro@336:   # bugzilla-usermap.conf - inside a hg repository
jerojasro@336:   [usermap]
jerojasro@336:   stephanie@example.com = steph
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \subsubsection{Configuring the text that gets added to a bug}
jerojasro@336: 
jerojasro@336: You can configure the text that this hook adds as a comment; you
jerojasro@336: specify it in the form of a Mercurial template.  Several \hgrc\
jerojasro@336: entries (still in the \rcsection{bugzilla} section) control this
jerojasro@336: behaviour.
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{strip}] The number of leading path elements to strip
jerojasro@336:   from a repository's path name to construct a partial path for a URL.
jerojasro@336:   For example, if the repositories on your server live under
jerojasro@336:   \dirname{/home/hg/repos}, and you have a repository whose path is
jerojasro@336:   \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
jerojasro@336:   \texttt{4} will give a partial path of \dirname{app/tests}.  The
jerojasro@336:   hook will make this partial path available when expanding a
jerojasro@336:   template, as \texttt{webroot}.
jerojasro@336: \item[\texttt{template}] The text of the template to use.  In addition
jerojasro@336:   to the usual changeset-related variables, this template can use
jerojasro@336:   \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
jerojasro@336:   above) and \texttt{webroot} (the path constructed using
jerojasro@336:   \texttt{strip} above).
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: In addition, you can add a \rcitem{web}{baseurl} item to the
jerojasro@336: \rcsection{web} section of your \hgrc.  The \hgext{bugzilla} hook will
jerojasro@336: make this available when expanding a template, as the base string to
jerojasro@336: use when constructing a URL that will let users browse from a Bugzilla
jerojasro@336: comment to view a changeset.  Example:
jerojasro@336: \begin{codesample2}
jerojasro@336:   [web]
jerojasro@336:   baseurl = http://hg.domain.com/
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: Here is an example set of \hgext{bugzilla} hook config information.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [bugzilla]
jerojasro@336:   host = bugzilla.example.com
jerojasro@336:   password = mypassword
jerojasro@336:   version = 2.16
jerojasro@336:   # server-side repos live in /home/hg/repos, so strip 4 leading
jerojasro@336:   # separators
jerojasro@336:   strip = 4
jerojasro@336:   hgweb = http://hg.example.com/
jerojasro@336:   usermap = /home/hg/repos/notify/bugzilla.conf
jerojasro@336:   template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
jerojasro@336:     repo, refers to this bug.\\nFor complete details, see 
jerojasro@336:     \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
jerojasro@336:     description:\\n\\t\{desc|tabindent\}
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \subsubsection{Testing and troubleshooting}
jerojasro@336: 
jerojasro@336: The most common problems with configuring the \hgext{bugzilla} hook
jerojasro@336: relate to running Bugzilla's \filename{processmail} script and mapping
jerojasro@336: committer names to user names.
jerojasro@336: 
jerojasro@336: Recall from section~\ref{sec:hook:bugzilla:config} above that the user
jerojasro@336: that runs the Mercurial process on the server is also the one that
jerojasro@336: will run the \filename{processmail} script.  The
jerojasro@336: \filename{processmail} script sometimes causes Bugzilla to write to
jerojasro@336: files in its configuration directory, and Bugzilla's configuration
jerojasro@336: files are usually owned by the user that your web server runs under.
jerojasro@336: 
jerojasro@336: You can cause \filename{processmail} to be run with the suitable
jerojasro@336: user's identity using the \command{sudo} command.  Here is an example
jerojasro@336: entry for a \filename{sudoers} file.
jerojasro@336: \begin{codesample2}
jerojasro@336:   hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
jerojasro@336: \end{codesample2}
jerojasro@336: This allows the \texttt{hg\_user} user to run a
jerojasro@336: \filename{processmail-wrapper} program under the identity of
jerojasro@336: \texttt{httpd\_user}.
jerojasro@336: 
jerojasro@336: This indirection through a wrapper script is necessary, because
jerojasro@336: \filename{processmail} expects to be run with its current directory
jerojasro@336: set to wherever you installed Bugzilla; you can't specify that kind of
jerojasro@336: constraint in a \filename{sudoers} file.  The contents of the wrapper
jerojasro@336: script are simple:
jerojasro@336: \begin{codesample2}
jerojasro@336:   #!/bin/sh
jerojasro@336:   cd `dirname $0` && ./processmail "$1" nobody@example.com
jerojasro@336: \end{codesample2}
jerojasro@336: It doesn't seem to matter what email address you pass to
jerojasro@336: \filename{processmail}.
jerojasro@336: 
jerojasro@336: If your \rcsection{usermap} is not set up correctly, users will see an
jerojasro@336: error message from the \hgext{bugzilla} hook when they push changes
jerojasro@336: to the server.  The error message will look like this:
jerojasro@336: \begin{codesample2}
jerojasro@336:   cannot find bugzilla user id for john.q.public@example.com
jerojasro@336: \end{codesample2}
jerojasro@336: What this means is that the committer's address,
jerojasro@336: \texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
jerojasro@336: nor does it have an entry in your \rcsection{usermap} that maps it to
jerojasro@336: a valid Bugzilla user name.
jerojasro@336: 
jerojasro@336: \subsection{\hgext{notify}---send email notifications}
jerojasro@336: 
jerojasro@336: Although Mercurial's built-in web server provides RSS feeds of changes
jerojasro@336: in every repository, many people prefer to receive change
jerojasro@336: notifications via email.  The \hgext{notify} hook lets you send out
jerojasro@336: notifications to a set of email addresses whenever changesets arrive
jerojasro@336: that those subscribers are interested in.
jerojasro@336: 
jerojasro@336: As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
jerojasro@336: template-driven, so you can customise the contents of the notification
jerojasro@336: messages that it sends.
jerojasro@336: 
jerojasro@336: By default, the \hgext{notify} hook includes a diff of every changeset
jerojasro@336: that it sends out; you can limit the size of the diff, or turn this
jerojasro@336: feature off entirely.  It is useful for letting subscribers review
jerojasro@336: changes immediately, rather than clicking to follow a URL.
jerojasro@336: 
jerojasro@336: \subsubsection{Configuring the \hgext{notify} hook}
jerojasro@336: 
jerojasro@336: You can set up the \hgext{notify} hook to send one email message per
jerojasro@336: incoming changeset, or one per incoming group of changesets (all those
jerojasro@336: that arrived in a single pull or push).
jerojasro@336: \begin{codesample2}
jerojasro@336:   [hooks]
jerojasro@336:   # send one email per group of changes
jerojasro@336:   changegroup.notify = python:hgext.notify.hook
jerojasro@336:   # send one email per change
jerojasro@336:   incoming.notify = python:hgext.notify.hook
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: Configuration information for this hook lives in the
jerojasro@336: \rcsection{notify} section of a \hgrc\ file.
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\rcitem{notify}{test}] By default, this hook does not send out
jerojasro@336:   email at all; instead, it prints the message that it \emph{would}
jerojasro@336:   send.  Set this item to \texttt{false} to allow email to be sent.
jerojasro@336:   The reason that sending of email is turned off by default is that it
jerojasro@336:   takes several tries to configure this extension exactly as you would
jerojasro@336:   like, and it would be bad form to spam subscribers with a number of
jerojasro@336:   ``broken'' notifications while you debug your configuration.
jerojasro@336: \item[\rcitem{notify}{config}] The path to a configuration file that
jerojasro@336:   contains subscription information.  This is kept separate from the
jerojasro@336:   main \hgrc\ so that you can maintain it in a repository of its own.
jerojasro@336:   People can then clone that repository, update their subscriptions,
jerojasro@336:   and push the changes back to your server.
jerojasro@336: \item[\rcitem{notify}{strip}] The number of leading path separator
jerojasro@336:   characters to strip from a repository's path, when deciding whether
jerojasro@336:   a repository has subscribers.  For example, if the repositories on
jerojasro@336:   your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
jerojasro@336:   considering a repository named \dirname{/home/hg/repos/shared/test},
jerojasro@336:   setting \rcitem{notify}{strip} to \texttt{4} will cause
jerojasro@336:   \hgext{notify} to trim the path it considers down to
jerojasro@336:   \dirname{shared/test}, and it will match subscribers against that.
jerojasro@336: \item[\rcitem{notify}{template}] The template text to use when sending
jerojasro@336:   messages.  This specifies both the contents of the message header
jerojasro@336:   and its body.
jerojasro@336: \item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
jerojasro@336:   data to append to the end of a message.  If a diff is longer than
jerojasro@336:   this, it is truncated.  By default, this is set to 300.  Set this to
jerojasro@336:   \texttt{0} to omit diffs from notification emails.
jerojasro@336: \item[\rcitem{notify}{sources}] A list of sources of changesets to
jerojasro@336:   consider.  This lets you limit \hgext{notify} to only sending out
jerojasro@336:   email about changes that remote users pushed into this repository
jerojasro@336:   via a server, for example.  See section~\ref{sec:hook:sources} for
jerojasro@336:   the sources you can specify here.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
jerojasro@336: section, you can use it in a template; it will be available as
jerojasro@336: \texttt{webroot}.
jerojasro@336: 
jerojasro@336: Here is an example set of \hgext{notify} configuration information.
jerojasro@336: \begin{codesample2}
jerojasro@336:   [notify]
jerojasro@336:   # really send email
jerojasro@336:   test = false
jerojasro@336:   # subscriber data lives in the notify repo
jerojasro@336:   config = /home/hg/repos/notify/notify.conf
jerojasro@336:   # repos live in /home/hg/repos on server, so strip 4 "/" chars
jerojasro@336:   strip = 4
jerojasro@336:   template = X-Hg-Repo: \{webroot\}
jerojasro@336:     Subject: \{webroot\}: \{desc|firstline|strip\}
jerojasro@336:     From: \{author\}
jerojasro@336: 
jerojasro@336:     changeset \{node|short\} in \{root\}
jerojasro@336:     details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
jerojasro@336:     description:
jerojasro@336:       \{desc|tabindent|strip\}
jerojasro@336: 
jerojasro@336:   [web]
jerojasro@336:   baseurl = http://hg.example.com/
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: This will produce a message that looks like the following:
jerojasro@336: \begin{codesample2}
jerojasro@336:   X-Hg-Repo: tests/slave
jerojasro@336:   Subject: tests/slave: Handle error case when slave has no buffers
jerojasro@336:   Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
jerojasro@336: 
jerojasro@336:   changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
jerojasro@336:   details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
jerojasro@336:   description:
jerojasro@336:           Handle error case when slave has no buffers
jerojasro@336:   diffs (54 lines):
jerojasro@336: 
jerojasro@336:   diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
jerojasro@336:   --- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
jerojasro@336:   +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
jerojasro@336:   @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
jerojasro@336:   [...snip...]
jerojasro@336: \end{codesample2}
jerojasro@336: 
jerojasro@336: \subsubsection{Testing and troubleshooting}
jerojasro@336: 
jerojasro@336: Do not forget that by default, the \hgext{notify} extension \emph{will
jerojasro@336:   not send any mail} until you explicitly configure it to do so, by
jerojasro@336: setting \rcitem{notify}{test} to \texttt{false}.  Until you do that,
jerojasro@336: it simply prints the message it \emph{would} send.
jerojasro@336: 
jerojasro@336: \section{Information for writers of hooks}
jerojasro@336: \label{sec:hook:ref}
jerojasro@336: 
jerojasro@336: \subsection{In-process hook execution}
jerojasro@336: 
jerojasro@336: An in-process hook is called with arguments of the following form:
jerojasro@336: \begin{codesample2}
jerojasro@336:   def myhook(ui, repo, **kwargs):
jerojasro@336:       pass
jerojasro@336: \end{codesample2}
jerojasro@336: The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
jerojasro@336: The \texttt{repo} parameter is a
jerojasro@336: \pymodclass{mercurial.localrepo}{localrepository} object.  The
jerojasro@336: names and values of the \texttt{**kwargs} parameters depend on the
jerojasro@336: hook being invoked, with the following common features:
jerojasro@336: \begin{itemize}
jerojasro@336: \item If a parameter is named \texttt{node} or
jerojasro@336:   \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
jerojasro@336:   The empty string is used to represent ``null changeset ID'' instead
jerojasro@336:   of a string of zeroes.
jerojasro@336: \item If a parameter is named \texttt{url}, it will contain the URL of
jerojasro@336:   a remote repository, if that can be determined.
jerojasro@336: \item Boolean-valued parameters are represented as Python
jerojasro@336:   \texttt{bool} objects.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: An in-process hook is called without a change to the process's working
jerojasro@336: directory (unlike external hooks, which are run in the root of the
jerojasro@336: repository).  It must not change the process's working directory, or
jerojasro@336: it will cause any calls it makes into the Mercurial API to fail.
jerojasro@336: 
jerojasro@336: If a hook returns a boolean ``false'' value, it is considered to have
jerojasro@336: succeeded.  If it returns a boolean ``true'' value or raises an
jerojasro@336: exception, it is considered to have failed.  A useful way to think of
jerojasro@336: the calling convention is ``tell me if you fail''.
jerojasro@336: 
jerojasro@336: Note that changeset IDs are passed into Python hooks as hexadecimal
jerojasro@336: strings, not the binary hashes that Mercurial's APIs normally use.  To
jerojasro@336: convert a hash from hex to binary, use the
jerojasro@336: \pymodfunc{mercurial.node}{bin} function.
jerojasro@336: 
jerojasro@336: \subsection{External hook execution}
jerojasro@336: 
jerojasro@336: An external hook is passed to the shell of the user running Mercurial.
jerojasro@336: Features of that shell, such as variable substitution and command
jerojasro@336: redirection, are available.  The hook is run in the root directory of
jerojasro@336: the repository (unlike in-process hooks, which are run in the same
jerojasro@336: directory that Mercurial was run in).
jerojasro@336: 
jerojasro@336: Hook parameters are passed to the hook as environment variables.  Each
jerojasro@336: environment variable's name is converted in upper case and prefixed
jerojasro@336: with the string ``\texttt{HG\_}''.  For example, if the name of a
jerojasro@336: parameter is ``\texttt{node}'', the name of the environment variable
jerojasro@336: representing that parameter will be ``\texttt{HG\_NODE}''.
jerojasro@336: 
jerojasro@336: A boolean parameter is represented as the string ``\texttt{1}'' for
jerojasro@336: ``true'', ``\texttt{0}'' for ``false''.  If an environment variable is
jerojasro@336: named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
jerojasro@336: contains a changeset ID represented as a hexadecimal string.  The
jerojasro@336: empty string is used to represent ``null changeset ID'' instead of a
jerojasro@336: string of zeroes.  If an environment variable is named
jerojasro@336: \envar{HG\_URL}, it will contain the URL of a remote repository, if
jerojasro@336: that can be determined.
jerojasro@336: 
jerojasro@336: If a hook exits with a status of zero, it is considered to have
jerojasro@336: succeeded.  If it exits with a non-zero status, it is considered to
jerojasro@336: have failed.
jerojasro@336: 
jerojasro@336: \subsection{Finding out where changesets come from}
jerojasro@336: 
jerojasro@336: A hook that involves the transfer of changesets between a local
jerojasro@336: repository and another may be able to find out information about the
jerojasro@336: ``far side''.  Mercurial knows \emph{how} changes are being
jerojasro@336: transferred, and in many cases \emph{where} they are being transferred
jerojasro@336: to or from.
jerojasro@336: 
jerojasro@336: \subsubsection{Sources of changesets}
jerojasro@336: \label{sec:hook:sources}
jerojasro@336: 
jerojasro@336: Mercurial will tell a hook what means are, or were, used to transfer
jerojasro@336: changesets between repositories.  This is provided by Mercurial in a
jerojasro@336: Python parameter named \texttt{source}, or an environment variable named
jerojasro@336: \envar{HG\_SOURCE}.
jerojasro@336: 
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{serve}] Changesets are transferred to or from a remote
jerojasro@336:   repository over http or ssh.
jerojasro@336: \item[\texttt{pull}] Changesets are being transferred via a pull from
jerojasro@336:   one repository into another.
jerojasro@336: \item[\texttt{push}] Changesets are being transferred via a push from
jerojasro@336:   one repository into another.
jerojasro@336: \item[\texttt{bundle}] Changesets are being transferred to or from a
jerojasro@336:   bundle.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: \subsubsection{Where changes are going---remote repository URLs}
jerojasro@336: \label{sec:hook:url}
jerojasro@336: 
jerojasro@336: When possible, Mercurial will tell a hook the location of the ``far
jerojasro@336: side'' of an activity that transfers changeset data between
jerojasro@336: repositories.  This is provided by Mercurial in a Python parameter
jerojasro@336: named \texttt{url}, or an environment variable named \envar{HG\_URL}.
jerojasro@336: 
jerojasro@336: This information is not always known.  If a hook is invoked in a
jerojasro@336: repository that is being served via http or ssh, Mercurial cannot tell
jerojasro@336: where the remote repository is, but it may know where the client is
jerojasro@336: connecting from.  In such cases, the URL will take one of the
jerojasro@336: following forms:
jerojasro@336: \begin{itemize}
jerojasro@336: \item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
jerojasro@336:   the given IP address.
jerojasro@336: \item \texttt{remote:http:\emph{ip-address}}---remote http client, at
jerojasro@336:   the given IP address.  If the client is using SSL, this will be of
jerojasro@336:   the form \texttt{remote:https:\emph{ip-address}}.
jerojasro@336: \item Empty---no information could be discovered about the remote
jerojasro@336:   client.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: \section{Hook reference}
jerojasro@336: 
jerojasro@336: \subsection{\hook{changegroup}---after remote changesets added}
jerojasro@336: \label{sec:hook:changegroup}
jerojasro@336: 
jerojasro@336: This hook is run after a group of pre-existing changesets has been
jerojasro@336: added to the repository, for example via a \hgcmd{pull} or
jerojasro@336: \hgcmd{unbundle}.  This hook is run once per operation that added one
jerojasro@336: or more changesets.  This is in contrast to the \hook{incoming} hook,
jerojasro@336: which is run once per changeset, regardless of whether the changesets
jerojasro@336: arrive in a group.
jerojasro@336: 
jerojasro@336: Some possible uses for this hook include kicking off an automated
jerojasro@336: build or test of the added changesets, updating a bug database, or
jerojasro@336: notifying subscribers that a repository contains new changes.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The changeset ID of the first
jerojasro@336:   changeset in the group that was added.  All changesets between this
jerojasro@336:   and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
jerojasro@336:   a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
jerojasro@336: \item[\texttt{source}] A string.  The source of these changes.  See
jerojasro@336:   section~\ref{sec:hook:sources} for details.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
jerojasro@336: \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
jerojasro@336: \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
jerojasro@336: 
jerojasro@336: \subsection{\hook{commit}---after a new changeset is created}
jerojasro@336: \label{sec:hook:commit}
jerojasro@336: 
jerojasro@336: This hook is run after a new changeset has been created.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The changeset ID of the newly
jerojasro@336:   committed changeset.
jerojasro@336: \item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
jerojasro@336:   parent of the newly committed changeset.
jerojasro@336: \item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
jerojasro@336:   parent of the newly committed changeset.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
jerojasro@336: \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
jerojasro@336: 
jerojasro@336: \subsection{\hook{incoming}---after one remote changeset is added}
jerojasro@336: \label{sec:hook:incoming}
jerojasro@336: 
jerojasro@336: This hook is run after a pre-existing changeset has been added to the
jerojasro@336: repository, for example via a \hgcmd{push}.  If a group of changesets
jerojasro@336: was added in a single operation, this hook is called once for each
jerojasro@336: added changeset.
jerojasro@336: 
jerojasro@336: You can use this hook for the same purposes as the \hook{changegroup}
jerojasro@336: hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
jerojasro@336: sometimes to run a hook once per group of changesets, while other
jerojasro@336: times it's handier once per changeset.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The ID of the newly added
jerojasro@336:   changeset.
jerojasro@336: \item[\texttt{source}] A string.  The source of these changes.  See
jerojasro@336:   section~\ref{sec:hook:sources} for details.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
jerojasro@336: 
jerojasro@336: \subsection{\hook{outgoing}---after changesets are propagated}
jerojasro@336: \label{sec:hook:outgoing}
jerojasro@336: 
jerojasro@336: This hook is run after a group of changesets has been propagated out
jerojasro@336: of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
jerojasro@336: command.
jerojasro@336: 
jerojasro@336: One possible use for this hook is to notify administrators that
jerojasro@336: changes have been pulled.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The changeset ID of the first
jerojasro@336:   changeset of the group that was sent.
jerojasro@336: \item[\texttt{source}] A string.  The source of the of the operation
jerojasro@336:   (see section~\ref{sec:hook:sources}).  If a remote client pulled
jerojasro@336:   changes from this repository, \texttt{source} will be
jerojasro@336:   \texttt{serve}.  If the client that obtained changes from this
jerojasro@336:   repository was local, \texttt{source} will be \texttt{bundle},
jerojasro@336:   \texttt{pull}, or \texttt{push}, depending on the operation the
jerojasro@336:   client performed.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
jerojasro@336: 
jerojasro@336: \subsection{\hook{prechangegroup}---before starting to add remote changesets}
jerojasro@336: \label{sec:hook:prechangegroup}
jerojasro@336: 
jerojasro@336: This controlling hook is run before Mercurial begins to add a group of
jerojasro@336: changesets from another repository.
jerojasro@336: 
jerojasro@336: This hook does not have any information about the changesets to be
jerojasro@336: added, because it is run before transmission of those changesets is
jerojasro@336: allowed to begin.  If this hook fails, the changesets will not be
jerojasro@336: transmitted.
jerojasro@336: 
jerojasro@336: One use for this hook is to prevent external changes from being added
jerojasro@336: to a repository.  For example, you could use this to ``freeze'' a
jerojasro@336: server-hosted branch temporarily or permanently so that users cannot
jerojasro@336: push to it, while still allowing a local administrator to modify the
jerojasro@336: repository.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{source}] A string.  The source of these changes.  See
jerojasro@336:   section~\ref{sec:hook:sources} for details.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
jerojasro@336: \hook{incoming} (section~\ref{sec:hook:incoming}), ,
jerojasro@336: \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
jerojasro@336: 
jerojasro@336: \subsection{\hook{precommit}---before starting to commit a changeset}
jerojasro@336: \label{sec:hook:precommit}
jerojasro@336: 
jerojasro@336: This hook is run before Mercurial begins to commit a new changeset.
jerojasro@336: It is run before Mercurial has any of the metadata for the commit,
jerojasro@336: such as the files to be committed, the commit message, or the commit
jerojasro@336: date.
jerojasro@336: 
jerojasro@336: One use for this hook is to disable the ability to commit new
jerojasro@336: changesets, while still allowing incoming changesets.  Another is to
jerojasro@336: run a build or test, and only allow the commit to begin if the build
jerojasro@336: or test succeeds.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
jerojasro@336:   parent of the working directory.
jerojasro@336: \item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
jerojasro@336:   parent of the working directory.
jerojasro@336: \end{itemize}
jerojasro@336: If the commit proceeds, the parents of the working directory will
jerojasro@336: become the parents of the new changeset.
jerojasro@336: 
jerojasro@336: See also: \hook{commit} (section~\ref{sec:hook:commit}),
jerojasro@336: \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
jerojasro@336: 
jerojasro@336: \subsection{\hook{preoutgoing}---before starting to propagate changesets}
jerojasro@336: \label{sec:hook:preoutgoing}
jerojasro@336: 
jerojasro@336: This hook is invoked before Mercurial knows the identities of the
jerojasro@336: changesets to be transmitted.
jerojasro@336: 
jerojasro@336: One use for this hook is to prevent changes from being transmitted to
jerojasro@336: another repository.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{source}] A string.  The source of the operation that is
jerojasro@336:   attempting to obtain changes from this repository (see
jerojasro@336:   section~\ref{sec:hook:sources}).  See the documentation for the
jerojasro@336:   \texttt{source} parameter to the \hook{outgoing} hook, in
jerojasro@336:   section~\ref{sec:hook:outgoing}, for possible values of this
jerojasro@336:   parameter.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
jerojasro@336: 
jerojasro@336: \subsection{\hook{pretag}---before tagging a changeset}
jerojasro@336: \label{sec:hook:pretag}
jerojasro@336: 
jerojasro@336: This controlling hook is run before a tag is created.  If the hook
jerojasro@336: succeeds, creation of the tag proceeds.  If the hook fails, the tag is
jerojasro@336: not created.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{local}] A boolean.  Whether the tag is local to this
jerojasro@336:   repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
jerojasro@336:   managed by Mercurial (stored in \sfilename{.hgtags}).
jerojasro@336: \item[\texttt{node}] A changeset ID.  The ID of the changeset to be tagged.
jerojasro@336: \item[\texttt{tag}] A string.  The name of the tag to be created.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: If the tag to be created is revision-controlled, the \hook{precommit}
jerojasro@336: and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
jerojasro@336: and~\ref{sec:hook:pretxncommit}) will also be run.
jerojasro@336: 
jerojasro@336: See also: \hook{tag} (section~\ref{sec:hook:tag})
jerojasro@336: 
jerojasro@336: \subsection{\hook{pretxnchangegroup}---before completing addition of
jerojasro@336:   remote changesets}
jerojasro@336: \label{sec:hook:pretxnchangegroup}
jerojasro@336: 
jerojasro@336: This controlling hook is run before a transaction---that manages the
jerojasro@336: addition of a group of new changesets from outside the
jerojasro@336: repository---completes.  If the hook succeeds, the transaction
jerojasro@336: completes, and all of the changesets become permanent within this
jerojasro@336: repository.  If the hook fails, the transaction is rolled back, and
jerojasro@336: the data for the changesets is erased.
jerojasro@336: 
jerojasro@336: This hook can access the metadata associated with the almost-added
jerojasro@336: changesets, but it should not do anything permanent with this data.
jerojasro@336: It must also not modify the working directory.
jerojasro@336: 
jerojasro@336: While this hook is running, if other Mercurial processes access this
jerojasro@336: repository, they will be able to see the almost-added changesets as if
jerojasro@336: they are permanent.  This may lead to race conditions if you do not
jerojasro@336: take steps to avoid them.
jerojasro@336: 
jerojasro@336: This hook can be used to automatically vet a group of changesets.  If
jerojasro@336: the hook fails, all of the changesets are ``rejected'' when the
jerojasro@336: transaction rolls back.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The changeset ID of the first
jerojasro@336:   changeset in the group that was added.  All changesets between this
jerojasro@336:   and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
jerojasro@336:   a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
jerojasro@336: \item[\texttt{source}] A string.  The source of these changes.  See
jerojasro@336:   section~\ref{sec:hook:sources} for details.
jerojasro@336: \item[\texttt{url}] A URL.  The location of the remote repository, if
jerojasro@336:   known.  See section~\ref{sec:hook:url} for more information.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
jerojasro@336: \hook{incoming} (section~\ref{sec:hook:incoming}),
jerojasro@336: \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
jerojasro@336: 
jerojasro@336: \subsection{\hook{pretxncommit}---before completing commit of new changeset}
jerojasro@336: \label{sec:hook:pretxncommit}
jerojasro@336: 
jerojasro@336: This controlling hook is run before a transaction---that manages a new
jerojasro@336: commit---completes.  If the hook succeeds, the transaction completes
jerojasro@336: and the changeset becomes permanent within this repository.  If the
jerojasro@336: hook fails, the transaction is rolled back, and the commit data is
jerojasro@336: erased.
jerojasro@336: 
jerojasro@336: This hook can access the metadata associated with the almost-new
jerojasro@336: changeset, but it should not do anything permanent with this data.  It
jerojasro@336: must also not modify the working directory.
jerojasro@336: 
jerojasro@336: While this hook is running, if other Mercurial processes access this
jerojasro@336: repository, they will be able to see the almost-new changeset as if it
jerojasro@336: is permanent.  This may lead to race conditions if you do not take
jerojasro@336: steps to avoid them.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{node}] A changeset ID.  The changeset ID of the newly
jerojasro@336:   committed changeset.
jerojasro@336: \item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
jerojasro@336:   parent of the newly committed changeset.
jerojasro@336: \item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
jerojasro@336:   parent of the newly committed changeset.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{precommit} (section~\ref{sec:hook:precommit})
jerojasro@336: 
jerojasro@336: \subsection{\hook{preupdate}---before updating or merging working directory}
jerojasro@336: \label{sec:hook:preupdate}
jerojasro@336: 
jerojasro@336: This controlling hook is run before an update or merge of the working
jerojasro@336: directory begins.  It is run only if Mercurial's normal pre-update
jerojasro@336: checks determine that the update or merge can proceed.  If the hook
jerojasro@336: succeeds, the update or merge may proceed; if it fails, the update or
jerojasro@336: merge does not start.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
jerojasro@336:   working directory is to be updated to.  If the working directory is
jerojasro@336:   being merged, it will not change this parent.
jerojasro@336: \item[\texttt{parent2}] A changeset ID.  Only set if the working
jerojasro@336:   directory is being merged.  The ID of the revision that the working
jerojasro@336:   directory is being merged with.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{update} (section~\ref{sec:hook:update})
jerojasro@336: 
jerojasro@336: \subsection{\hook{tag}---after tagging a changeset}
jerojasro@336: \label{sec:hook:tag}
jerojasro@336: 
jerojasro@336: This hook is run after a tag has been created.
jerojasro@336: 
jerojasro@336: Parameters to this hook:
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{local}] A boolean.  Whether the new tag is local to this
jerojasro@336:   repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
jerojasro@336:   managed by Mercurial (stored in \sfilename{.hgtags}).
jerojasro@336: \item[\texttt{node}] A changeset ID.  The ID of the changeset that was
jerojasro@336:   tagged.
jerojasro@336: \item[\texttt{tag}] A string.  The name of the tag that was created.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: If the created tag is revision-controlled, the \hook{commit} hook
jerojasro@336: (section~\ref{sec:hook:commit}) is run before this hook.
jerojasro@336: 
jerojasro@336: See also: \hook{pretag} (section~\ref{sec:hook:pretag})
jerojasro@336: 
jerojasro@336: \subsection{\hook{update}---after updating or merging working directory}
jerojasro@336: \label{sec:hook:update}
jerojasro@336: 
jerojasro@336: This hook is run after an update or merge of the working directory
jerojasro@336: completes.  Since a merge can fail (if the external \command{hgmerge}
jerojasro@336: command fails to resolve conflicts in a file), this hook communicates
jerojasro@336: whether the update or merge completed cleanly.
jerojasro@336: 
jerojasro@336: \begin{itemize}
jerojasro@336: \item[\texttt{error}] A boolean.  Indicates whether the update or
jerojasro@336:   merge completed successfully.
jerojasro@336: \item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
jerojasro@336:   working directory was updated to.  If the working directory was
jerojasro@336:   merged, it will not have changed this parent.
jerojasro@336: \item[\texttt{parent2}] A changeset ID.  Only set if the working
jerojasro@336:   directory was merged.  The ID of the revision that the working
jerojasro@336:   directory was merged with.
jerojasro@336: \end{itemize}
jerojasro@336: 
jerojasro@336: See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
jerojasro@336: 
jerojasro@336: %%% Local Variables: 
jerojasro@336: %%% mode: latex
jerojasro@336: %%% TeX-master: "00book"
jerojasro@336: %%% End: 




