hgbook: es/hook.tex annotate

hgbook

annotate es/hook.tex @ 461:67d34d8b6ba0

translated up to the "writing an in-process hook" section

author	Javier Rojas <jerojasro@devnull.li>
date	Tue Dec 23 12:57:21 2008 -0500 (2008-12-23)
parents	5a0401ba9faa
children	5389bef3a95b

rev	line source
jerojasro@437	1 \chapter{Manejo de eventos en repositorios mediante ganchos}
jerojasro@336	2 \label{chap:hook}
jerojasro@336	3
jerojasro@435	4 Mercurial ofrece un poderoso mecanismo para permitirle a usted
jerojasro@435	5 automatizar la ejecución de acciones en respuesta a eventos que
jerojasro@435	6 ocurran en un repositorio. En algunos casos, usted puede controlar
jerojasro@435	7 incluso la respuesta de Mercurial a dichos eventos.
jerojasro@435	8
jerojasro@435	9 Mercurial usa el término \emph{gancho} para identificar estas
jerojasro@435	10 acciones. Los ganchos son conocidos como ``disparadores'' en algunos
jerojasro@435	11 sistemas de control de revisiones, pero los dos nombres se refieren al
jerojasro@435	12 mismo concepto.
jerojasro@435	13
jerojasro@435	14 \section{Vistazo general de ganchos en Mercurial}
jerojasro@435	15
jerojasro@435	16 A continuación se encuentra una breve lista de los ganchos que
jerojasro@435	17 Mercurial soporta. Volveremos a cada uno de estos ganchos con más
jerojasro@435	18 detalle después, en la sección~\ref{sec:hook:ref}.
jerojasro@435	19
jerojasro@435	20 \begin{itemize}
jerojasro@435	21 \item[\small\hook{changegroup}] Es ejecutado luego de que un grupo de
jerojasro@435	22 conjuntos de cambios ha sido traído al repositorio desde algún
jerojasro@435	23 otro sitio.
jerojasro@435	24 \item[\small\hook{commit}] Es ejecutado después de la creación de
jerojasro@435	25 un conjunto de cambios en el repositorio local.
jerojasro@435	26 \item[\small\hook{incoming}] Es ejecutado una vez por cada conjunto de
jerojasro@435	27 cambios traído al repositorio desde otra ubicación. Note la
jerojasro@435	28 diferencia respecto al gancho \hook{changegroup}, que es ejecutado
jerojasro@435	29 una vez por cada \emph{grupo} de conjuntos de cambios que se
jerojasro@435	30 traiga.
jerojasro@435	31 \item[\small\hook{outgoing}] Es ejecutado luego de que un grupo de
jerojasro@435	32 conjuntos de cambios ha sido transmitido desde el repositorio.
jerojasro@435	33 \item[\small\hook{prechangegroup}] Es ejecutado antes de iniciar la
jerojasro@435	34 recepción de un grupo de conjuntos de cambios en el repositorio.
jerojasro@435	35 \item[\small\hook{precommit}] De control. Es ejecutado antes de
jerojasro@435	36 iniciar una consignación.
jerojasro@435	37 \item[\small\hook{preoutgoing}] De control. Es ejecutado antes de
jerojasro@435	38 iniciar la transmisión de un grupo de conjuntos de cambios desde
jerojasro@435	39 el repositorio.
jerojasro@435	40 \item[\small\hook{pretag}] De control. Es ejecutado antes de crear una
jerojasro@435	41 etiqueta.
jerojasro@435	42 \item[\small\hook{pretxnchangegroup}] De control. Es ejecutado después
jerojasro@435	43 de haber recibido un grupo de conjuntos de cambios en el
jerojasro@435	44 repositorio local, pero antes de que la transacción se complete y
jerojasro@435	45 los cambios sean permanentes dentro del repositorio.
jerojasro@435	46 \item[\small\hook{pretxncommit}] De control. Es ejecutado luego de la
jerojasro@435	47 creación de un conjunto de cambios en el repositorio local, pero
jerojasro@435	48 antes de que la transacción que hace permanente el cambio sea
jerojasro@435	49 completada.
jerojasro@435	50 \item[\small\hook{preupdate}] De control. Es ejecutado antes de
jerojasro@435	51 iniciar una actualización o fusión en el directorio de trabajo.
jerojasro@435	52 \item[\small\hook{tag}] Es ejecutado después de la creación de una
jerojasro@435	53 etiqueta.
jerojasro@435	54 \item[\small\hook{update}] Es ejecutado después de que termina una
jerojasro@435	55 actualización o una fusión.
jerojasro@435	56 \end{itemize}
jerojasro@435	57 Cada uno de los ganchos cuya descripción empieza con la frase
jerojasro@435	58 ``de control'' tiene la facultad de determinar si una actividad puede
jerojasro@435	59 continuar. Si el gancho se ejecuta con éxito, la actividad puede
jerojasro@435	60 continuar; si falla, o bien la actividad no es permitida, o se
jerojasro@435	61 deshacen los cambios que se puedan haber llevado a cabo, dependiendo
jerojasro@435	62 del gancho involucrado.
jerojasro@435	63
jerojasro@435	64 \section{Ganchos y seguridad}
jerojasro@435	65
jerojasro@435	66 \subsection{Los ganchos se ejecutan con sus privilegios de usuario}
jerojasro@435	67
jerojasro@435	68 Cuando usted ejecuta un comando de Mercurial en un repositorio, y el
jerojasro@435	69 comando causa la ejecución de un gancho, dicho gancho se ejecuta en
jerojasro@435	70 \emph{su} sistema, en \emph{su} cuenta de usuario, con \emph{sus}
jerojasro@435	71 privilegios. Ya que los ganchos son elementos arbitrarios de código
jerojasro@435	72 ejecutable, usted debería tratarlos con un nivel adecuado de
jerojasro@435	73 desconfianza. No instale un gancho a menos en que confíe en quien lo
jerojasro@435	74 creó y en lo que el gancho hace.
jerojasro@435	75
jerojasro@435	76 En algunos casos, usted puede estar expuesto a ganchos que usted no
jerojasro@435	77 %TODO acá introduzco algo de texto por mi cuenta, por claridad
jerojasro@435	78 instaló. Si usted usa Mercurial en un sistema extraño, tenga en cuenta
jerojasro@435	79 que Mercurial ejecutará los ganchos definidos en el fichero \hgrc.
jerojasro@435	80
jerojasro@435	81 Si está trabajando con un repositorio propiedad de otro usuario,
jerojasro@435	82 Mercurial podrá ejecutar los ganchos definidos en el repositorio de
jerojasro@435	83 dicho usuario, pero los ejecutará como ``usted''. Por ejemplo, si
jerojasro@435	84 usted jala (\hgcmd{pull}) desde ese repositorio, y el
jerojasro@435	85 \sfilename{.hg/hgrc} define un gancho saliente (\hook{outgoing}),
jerojasro@435	86 dicho gancho se ejecuta bajo su cuenta de usuario, aun cuando usted no
jerojasro@435	87 es el propietario del repositorio.
jerojasro@336	88
jerojasro@336	89 \begin{note}
jerojasro@435	90 Esto sólo aplica si usted está jalando desde un repositorio en un
jerojasro@435	91 sistema de ficheros local o de red. Si está jalando a través de http
jerojasro@435	92 o ssh, cualquier gancho saliente (\hook{outgoing}) se ejecutará bajo
jerojasro@435	93 la cuenta que está ejecutando el proceso servidor, en el servidor.
jerojasro@336	94 \end{note}
jerojasro@336	95
jerojasro@435	96 XXX Para ver qué ganchos han sido definidos en un repositorio, use el
jerojasro@435	97 comando \hgcmdargs{config}{hooks}. Si usted está trabajando en un
jerojasro@435	98 repositorio, pero comunicándose con otro que no le pertenece
jerojasro@435	99 (por ejemplo, usando \hgcmd{pull} o \hgcmd{incoming}), recuerde que
jerojasro@435	100 los ganchos que debe considerar son los del otro repositorio, no los
jerojasro@435	101 del suyo.
jerojasro@435	102
jerojasro@435	103 \subsection{Los ganchos no se propagan}
jerojasro@435	104
jerojasro@435	105 En Mercurial, no se hace control de revisiones de los ganchos, y no se
jerojasro@435	106 propagan cuando usted clona, o jala de, un repositorio. El motivo para
jerojasro@435	107 esto es simple: un gancho es código ejecutable arbitrario. Se ejecuta
jerojasro@435	108 bajo su identidad, con su nivel de privilegios, en su máquina.
jerojasro@435	109
jerojasro@435	110 Sería extremadamente descuidado de parte de cualquier sistema
jerojasro@435	111 distribuido de control de revisiones el implementar control de
jerojasro@435	112 revisiones para ganchos, ya que esto ofrecería maneras fácilmente
jerojasro@435	113 %TODO subvertir
jerojasro@435	114 aprovechables de subvertir las cuentas de los usuarios del sistema de
jerojasro@435	115 control de revisiones.
jerojasro@435	116
jerojasro@435	117 Ya que Mercurial no propaga los ganchos, si usted está colaborando con
jerojasro@435	118 otras personas en un proyecto común, no debería asumir que ellos están
jerojasro@435	119 usando los mismos ganchos para Mercurial que usted usa, o que los de
jerojasro@435	120 ellos están configurado correctamente. Usted debería documentar los
jerojasro@435	121 ganchos que usted espera que la gente use.
jerojasro@336	122
jerojasro@437	123 En una intranet corporativa, esto es algo más fácil de manejar, ya que
jerojasro@437	124 usted puede, por ejemplo, proveer una instalación ``estándar'' de
jerojasro@437	125 Mercurial en un sistema de ficheros NFS, y usar un fichero \hgrc\
jerojasro@437	126 global para definir los ganchos que verán todos los usuarios. Sin
jerojasro@437	127 embargo, este enfoque tiene sus límites; vea más abajo.
jerojasro@336	128
jerojasro@441	129 \subsection{Es posible hacer caso omiso de los ganchos}
jerojasro@441	130
jerojasro@441	131 Mercurial le permite hacer caso omiso de la deficinión de un gancho,
jerojasro@441	132 a través de la redefinición del mismo. Usted puede deshabilitar el
jerojasro@441	133 gancho fijando su valor como una cadena vacía, o cambiar su
jerojasro@441	134 comportamiento como desee.
jerojasro@441	135
jerojasro@441	136 Si usted instala un fichero \hgrc\ a nivel de sistema o sitio completo
jerojasro@441	137 que define algunos ganchos, debe entender que sus usuarios pueden
jerojasro@441	138 deshabilitar o hacer caso omiso de los mismos.
jerojasro@441	139
jerojasro@441	140 \subsection{Asegurarse de que ganchos críticos sean ejecutados}
jerojasro@441	141
jerojasro@441	142 Algunas veces usted puede querer hacer respetar una política, y no
jerojasro@441	143 permitir que los demás sean capaces de evitarla. Por ejemplo, usted
jerojasro@441	144 puede tener como requerimiento que cada conjunto de cambios debe pasar
jerojasro@441	145 un riguroso conjunto de pruebas. Definir este requerimientos a través
jerojasro@441	146 de un gancho en un fichero \hgrc\ global no servirá con usuarios
jerojasro@441	147 remotos en computadoras portátiles, y por supuesto que los usuarios
jerojasro@441	148 locales pueden evitar esto a voluntad haciendo caso omiso del gancho.
jerojasro@441	149
jerojasro@441	150 En vez de eso, usted puede definir las políticas para usar Mercurial
jerojasro@441	151 de tal forma que se espere que los usuarios propaguen los cambios a
jerojasro@441	152 través de un servidor ``canónico'' bien conocido que usted ha
jerojasro@441	153 asegurado y configurado apropiadamente.
jerojasro@441	154
jerojasro@441	155 Una manera de hacer esto es a través de una combinación de ingeniería
jerojasro@441	156 socual y tecnología. Cree una cuenta de acceso restringido; los
jerojasro@441	157 usuarios pueden empujar cambios a través de la red a los repositorios
jerojasro@441	158 administrados por esta cuenta, pero no podrán ingresar a dicha cuenta
jerojasro@441	159 para ejecutar órdenes en el intérprete de comandos. En este escenario,
jerojasro@441	160 un usuario puede enviar un conjunto de cambios que contenga la
jerojasro@441	161 porquería que él desee.
jerojasro@441	162
jerojasro@441	163 Cuando alguien empuja un conjunto de cambios al servidor del que todos
jerojasro@441	164 jalan, el servidor probará el conjunto de cambios antes de aceptarlo
jerojasro@441	165 como permanente, y lo rechazará si no logra pasar el conjunto de
jerojasro@441	166 pruebas. Si la gente sólo jala cambios desde este servidor de filtro,
jerojasro@441	167 servirá para asegurarse de que todos los cambios que la gente jala han
jerojasro@441	168 sido examinados automáticamente
jerojasro@441	169
jerojasro@441	170 \section{Precauciones con ganchos \texttt{pretxn} en un repositorio de
jerojasro@441	171 acceso compartido}
jerojasro@441	172
jerojasro@441	173 Si usted desea usar ganchos para llevar a cabo automáticamente algún
jerojasro@441	174 trabajo en un repositorio al que varias personas tienen acceso
jerojasro@441	175 compartido, debe tener cuidado con la forma de hacerlo.
jerojasro@441	176
jerojasro@441	177 Mercurial sólo bloquea un repositorio cuando está escribiendo al
jerojasro@441	178 mismo, y sólo las partes de Mercurial que escriben al repositorio le
jerojasro@441	179 prestan atención a los bloqueos. Los bloqueos de escritura son
jerojasro@441	180 necesarios para evitar que múltiples escritores simultáneos
jerojasro@441	181 interfieran entre sí, corrompiendo el repositorio.
jerojasro@441	182
jerojasro@441	183 Ya que Mercurial tiene cuidado con el orden en que lee y escribe
jerojasro@441	184 datos, no necesita adquirir un bloqueo cuando desea leer datos del
jerojasro@441	185 repositorio. Las partes de Mercurial que leen del repositorio nunca le
jerojasro@441	186 prestan atención a los bloqueos. Este esquema de lectura libre de
jerojasro@441	187 bloqueos incremententa en gran medida el desempeño y la concurrencia.
jerojasro@441	188
jerojasro@441	189 Sin embargo, para tener un gran desempeño es necesario hacer
jerojasro@441	190 sacrificios, uno de los cuales tiene el potencial de causarle
jerojasro@441	191 problemas a menos de que usted esté consciente de él. Describirlo
jerojasro@441	192 requiere algo de detalle respecto a cómo Mercurial añade conjuntos de
jerojasro@441	193 cambios al repositorio y cómo lee esos cambios de vuelta.
jerojasro@441	194
jerojasro@441	195 Cuando Mercurial \emph{escribe} metadatos, los escribe directamente en
jerojasro@441	196 el fichero de destino. Primero escribe los datos del fichero, luego
jerojasro@441	197 los datos del manifiesto (que contienen punteros a los nuevos datos
jerojasro@441	198 del fichero), luego datos de la bitácora de cambios (que contienen
jerojasro@441	199 punteros a los nuevos datos del manifiesto). Antes de la primera
jerojasro@441	200 escritura a cada fichero, se guarda un registro de dónde estaba el
jerojasro@441	201 final de fichero en su registro de transacciones. Si la transacción
jerojasro@441	202 debe ser deshecha, Mercurial simplemente trunca cada fichero de vuelta
jerojasro@441	203 al tamaño que tenía antes de que empezara la transacción.
jerojasro@441	204
jerojasro@441	205 Cuando Mercurial \emph{lee} metadatos, lee la bitácora de cambios
jerojasro@441	206 primero, y luego todo lo demás. Como un lector sólo accederá a las
jerojasro@441	207 partes del manifiesto o de los metadatos de fichero que él puede ver
jerojasro@441	208 en la bitácora de cambios, nunca puede ver datos parcialmente
jerojasro@441	209 escritos.
jerojasro@441	210
jerojasro@441	211 Algunos ganchos de control (\hook{pretxncommit} y
jerojasro@441	212 \hook{pretxnchangegroup}) se ejecutan cuando una transacción está casi
jerojasro@441	213 completa. Todos los metadatos han sido escritos, pero Mercurial aún
jerojasro@441	214 puede deshacer la transacción y hacer que los datos recién escritos
jerojasro@441	215 desaparezcan.
jerojasro@441	216
jerojasro@441	217 Si alguno de estos ganchos permanece en ejecución por mucho tiempo,
jerojasro@441	218 abre una ventana de tiempo en la que un lector puede ver los metadatos
jerojasro@441	219 de conjuntos de cambios que aún no son permanentes y que no debería
jerojasro@441	220 considerarse que estén ``realmante ahí''. Entre más tiempo tome la
jerojasro@441	221 ejecución del gancho, más tiempo estará abierta esta ventana.
jerojasro@441	222
jerojasro@441	223 \subsection{Ilustración del problema}
jerojasro@441	224
jerojasro@441	225 En principio, un buen uso del gancho \hook{pretxnchangegroup} sería
jerojasro@441	226 ensamblar y probar automáticamente todos los cambios entrantes antes
jerojasro@441	227 de que sean aceptados en un repositorio central. Esto le permitiría a
jerojasro@441	228 usted garantizar que nadie pueda empujar cambios que ``rompan el
jerojasro@441	229 ensamblaje''. Pero si un cliente puede jalar cambios mientras están
jerojasro@441	230 siendo probados, la utilidad de esta prueba es nula; alguien confiado
jerojasro@441	231 puede jalar cambios sin probar, lo que potencialmente podría romper su
jerojasro@441	232 proceso de ensamblaje.
jerojasro@441	233
jerojasro@441	234 La respuesta técnica más segura frente a este retos es montar dicho
jerojasro@441	235 repositorio ``guardián'' como \emph{unidireccional}. Permita que
jerojasro@441	236 reciba cambios desde el exterior, pero no permita que nadie jale
jerojasro@441	237 cambios de él (use el gancho \hook{preoutgoing} para bloquear esto).
jerojasro@441	238 Configure un gancho \hook{changegroup} para que si el ensamblaje o
jerojasro@441	239 prueba tiene éxito, el gancho empuje los nuevos cambios a otro
jerojasro@441	240 repositorio del que la gente \emph{pueda} jalar.
jerojasro@441	241
jerojasro@441	242 En la práctica, montar un cuello de botella centralizado como éste a
jerojasro@441	243 menudo no es una buena idea, y la visibilidad de las transacciones no
jerojasro@441	244 tiene nada que ver con el problema. A medida que el tamaño de un
jerojasro@441	245 proyecto---y el tiempo que toma ensamblarlo y probarlo---crece, usted
jerojasro@441	246 se acerca rápidamente a un límite con este enfoque ``pruebe antes de
jerojasro@441	247 comprar'', en el que tiene más conjuntos de cambios a probar que
jerojasro@441	248 tiempo para ocuparse de ellos. El resultado inevitable es frustración
jerojasro@441	249 para todos los que estén involucrados.
jerojasro@441	250
jerojasro@441	251 Una aproximación que permite manejar mejor el crecimiento es hacer que
jerojasro@441	252 la gente ensamble y pruebe antes de empujar, y ejecutar el ensamble y
jerojasro@441	253 pruebas automáticas centralmente \emph{después} de empujar, para
jerojasro@441	254 asegurarse de que todo esté bien. La ventaja de este enfoque es que no
jerojasro@441	255 impone un límite a la rata en la que un repositorio puede aceptar
jerojasro@441	256 cambios.
jerojasro@441	257
jerojasro@441	258 \section{Tutorial corto de uso de ganchos}
jerojasro@336	259 \label{sec:hook:simple}
jerojasro@336	260
jerojasro@442	261 Escribir un gancho para Mercurial es fácil. Empecemos con un gancho
jerojasro@442	262 que se ejecute cuando usted termine un \hgcmd{commit}, y simplemente
jerojasro@442	263 muestre el hash del conjunto de cambios que usted acaba de crear. El
jerojasro@442	264 gancho se llamará \hook{commit}.
jerojasro@336	265
jerojasro@336	266 \begin{figure}[ht]
jerojasro@336	267 \interaction{hook.simple.init}
jerojasro@442	268 \caption{Un gancho simple que se ejecuta al hacer la consignación de
jerojasro@442	269 un conjunto de cambios}
jerojasro@336	270 \label{ex:hook:init}
jerojasro@336	271 \end{figure}
jerojasro@336	272
jerojasro@442	273 Todos los ganchos siguen el patrón del ejemplo~\ref{ex:hook:init}.
jerojasro@442	274 Usted puede añadir una entrada a la sección \rcsection{hooks} de su
jerojasro@442	275 fichero \hgrc. A la izquierda está el nombre del evento respecto al
jerojasro@442	276 cual dispararse; a la derecha está la acción a llevar a cabo. Como
jerojasro@442	277 puede ver, es posible ejecutar cualquier orden de la línea de comandos
jerojasro@442	278 en un gancho. Mercurial le pasa información extra al gancho usando
jerojasro@442	279 variables de entorno (busque \envar{HG\_NODE} en el ejemplo).
jerojasro@442	280
jerojasro@442	281 \subsection{Llevar a cabo varias acciones por evento}
jerojasro@442	282
jerojasro@442	283 A menudo, usted querrá definir más de un gancho para un tipo de evento
jerojasro@442	284 particular, como se muestra en el ejemplo~\ref{ex:hook:ext}.
jerojasro@442	285 Mercurial le permite hacer esto añadiendo una \emph{extensión} al
jerojasro@442	286 final del nombre de un gancho. Usted extiende el nombre del gancho
jerojasro@442	287 %TODO Yuk, no me gusta ese "parada completa"
jerojasro@442	288 poniendo el nombre del gancho, seguido por una parada completa (el
jerojasro@442	289 caracter ``\texttt{.}''), seguido de algo más de texto de su elección.
jerojasro@442	290 Por ejemplo, Mercurial ejecutará tanto \texttt{commit.foo} como
jerojasro@442	291 \texttt{commit.bar} cuando ocurra el evento \texttt{commit}.
jerojasro@336	292
jerojasro@336	293 \begin{figure}[ht]
jerojasro@336	294 \interaction{hook.simple.ext}
jerojasro@442	295 \caption{Definición de un segundo gancho \hook{commit}}
jerojasro@336	296 \label{ex:hook:ext}
jerojasro@336	297 \end{figure}
jerojasro@336	298
jerojasro@442	299 Para dar un orden bien definido de ejecución cuando hay múltiples
jerojasro@442	300 ganchos definidos para un evento, Mercurial ordena los ganchos de
jerojasro@442	301 acuerdo a su extensión, y los ejecuta en dicho orden. En el ejemplo de
jerojasro@442	302 arribam \texttt{commit.bar} se ejecutará antes que
jerojasro@442	303 \texttt{commit.foo}, y \texttt{commit} se ejecutará antes de ambos.
jerojasro@442	304
jerojasro@442	305 Es una buena idea usar una extensión descriptiva cuando usted define
jerojasro@442	306 un gancho. Esto le ayudará a recordar para qué se usa el gancho. Si el
jerojasro@442	307 gancho falla, usted recibirá un mensaje de error que contiene el
jerojasro@442	308 nombre y la extensión del gancho, así que usar una extensión
jerojasro@442	309 descriptiva le dará una pista inmediata de porqué el gancho falló (vea
jerojasro@442	310 un ejemplo en la sección~\ref{sec:hook:perm}).
jerojasro@442	311
jerojasro@442	312 \subsection{Controlar cuándo puede llevarse a cabo una actividad}
jerojasro@336	313 \label{sec:hook:perm}
jerojasro@336	314
jerojasro@442	315 En los ejemplos anteriores, usamos el gancho \hook{commit}, que es
jerojasro@442	316 ejecutado después de que se ha completado una consignación. Este es
jerojasro@442	317 uno de los varios ganchos que Mercurial ejecuta luego de que una
jerojasro@442	318 actividad termina. Tales ganchos no tienen forma de influenciar la
jerojasro@442	319 actividad como tal.
jerojasro@442	320
jerojasro@442	321 Mercurial define un número de eventos que ocurren antes de que una
jerojasro@442	322 actividad empiece; o luego de que empiece, pero antes de que termine.
jerojasro@442	323 Los ganchos que se disparan con estos eventos tienen la capacidad
jerojasro@442	324 adicional de elegir si la actividad puede continuar, o si su ejecución
jerojasro@442	325 es abortada.
jerojasro@442	326
jerojasro@442	327 El gancho \hook{pretxncommit} se ejecuta justo antes de que una
jerojasro@442	328 consignación se ejecute. En otras palabras, los metadatos que
jerojasro@442	329 representan el conjunto de cambios han sido escritos al disco, pero no
jerojasro@442	330 se ha terminado la transacción. El gancho \hook{pretxncommit} tiene la
jerojasro@442	331 capacidad de decidir si una transacción se completa, o debe
jerojasro@442	332 deshacerse.
jerojasro@442	333
jerojasro@442	334 Si el gancho \hook{pretxncommit} termina con un código de salida de
jerojasro@442	335 cero, se permite que la transacción se complete; la consignación
jerojasro@442	336 termina; y el gancho \hook{commit} es ejecutado. Si el gancho
jerojasro@442	337 \hook{pretxncommit} termina con un código de salida diferente de cero,
jerojasro@442	338 la transacción es revertida; los metadatos representando el conjunto
jerojasro@442	339 de cambios son borrados; y el gancho \hook{commit} no es ejecutado.
jerojasro@336	340
jerojasro@336	341 \begin{figure}[ht]
jerojasro@336	342 \interaction{hook.simple.pretxncommit}
jerojasro@442	343 \caption{Uso del gancho \hook{pretxncommit} hook to control commits}
jerojasro@336	344 \label{ex:hook:pretxncommit}
jerojasro@336	345 \end{figure}
jerojasro@336	346
jerojasro@452	347 El gancho en el ejemplo~\ref{ex:hook:pretxncommit} revisa si el
jerojasro@452	348 mensaje de consignación contiene el ID de algún fallo. Si lo contiene,
jerojasro@452	349 la consignación puede continuar. Si no, la consignación es cancelada.
jerojasro@452	350
jerojasro@452	351 \section{Escribir sus propios ganchos}
jerojasro@452	352
jerojasro@452	353 Cuando usted escriba un gancho, puede encontrar útil el ejecutar
jerojasro@452	354 Mercurial o bien pasándole la opción \hggopt{-v}, o con el valor de
jerojasro@452	355 configuración \rcitem{ui}{verbose} fijado en ``true'' (verdadero).
jerojasro@452	356 Cuando lo haga, Mercurial imprimirá un mensaje antes de llamar cada
jerojasro@452	357 gancho.
jerojasro@452	358
jerojasro@452	359 \subsection{Escoger cómo debe ejecutarse su gancho}
jerojasro@336	360 \label{sec:hook:lang}
jerojasro@336	361
jerojasro@452	362 Usted puede escribir un gancho que funcione como un programa normal
jerojasro@452	363 ---típicamente un guión de línea de comandos---o como una función de
jerojasro@452	364 Python que se ejecuta dentro del proceso Mercurial.
jerojasro@452	365
jerojasro@452	366 Escribir un gancho como un programa externo tiene la ventaja de que no
jerojasro@452	367 requiere ningún conocimiento del funcionamiento interno de Mercurial.
jerojasro@452	368 Usted puede ejecutar comandos Mercurial normales para obtener la
jerojasro@452	369 informción extra que pueda necesitar. La contraparte de esto es que
jerojasro@452	370 los ganchos externos son más lentos que los ganchos internos
jerojasro@452	371 ejecutados dentro del proceso.
jerojasro@452	372
jerojasro@452	373 Un gancho Python interno tiene acceso completo a la API de Mercurial,
jerojasro@452	374 y no se ``externaliza'' a otro proceso, así que es inherentemente más
jerojasro@452	375 rápido que un gancho externo. Adicionalmente es más fácil obtener la
jerojasro@452	376 mayoría de la información que un gancho requiere a través de llamadas
jerojasro@452	377 directas a la API de Mercurial que hacerlo ejecutando comandos
jerojasro@452	378 Mercurial.
jerojasro@452	379
jerojasro@452	380 Si se siente a gusto con Python, o requiere un alto desempeño,
jerojasro@452	381 escribir sus ganchos en Python puede ser una buena elección. Sin
jerojasro@452	382 embargo, cuando usted tiene un gancho bastante directo por escribir y
jerojasro@452	383 no le importa el desempeño (el caso de la mayoría de los ganchos), es
jerojasro@452	384 perfectamente admisible un guión de línea de comandos.
jerojasro@336	385
jerojasro@461	386 \subsection{Parámetros para ganchos}
jerojasro@336	387 \label{sec:hook:param}
jerojasro@336	388
jerojasro@461	389 Mercurial llama cada gancho con un conjunto de paŕametros bien
jerojasro@461	390 definidos. En Python, un parámetro se pasa como argumento de palabra
jerojasro@461	391 clave a su función de gancho. Para un programa externo, los parámetros
jerojasro@461	392 son pasados como variables de entornos.
jerojasro@461	393
jerojasro@461	394 Sin importar si su gancho está escrito en Python o como guión de línea
jerojasro@461	395 de comandos, los nombres y valores de los parámetros específicos de
jerojasro@461	396 los ganchos serán los mismos. Un parámetro booleano será representado
jerojasro@461	397 como un valor booleano en Python, pero como el número 1 (para
jerojasro@461	398 ``verdadero'') o 0 (para falso) en una variable de entorno para un
jerojasro@461	399 gancho externo. Si un parámetro se llama \texttt{foo}, el argumento de
jerojasro@461	400 palabra clave para un gancho en Python también se llamará
jerojasro@461	401 \texttt{foo}, mientras que la variable de entorno para un gancho
jerojasro@461	402 externo se llamará \texttt{HG\_FOO}.
jerojasro@461	403
jerojasro@461	404 \subsection{Valores de retorno de ganchos y control de actividades}
jerojasro@461	405
jerojasro@461	406 Un gancho que se ejecuta exitosamente debe terminar con un código de
jerojasro@461	407 salida de cero, si es externo, o retornar el valor booleano
jerojasro@461	408 ``falso'', si es interno. Un fallo se indica con un código de salida
jerojasro@461	409 diferente de cero desde un gancho externo, o un valor de retorno
jerojasro@461	410 booleano ``verdadero''. Si un gancho interno genera una excepción, se
jerojasro@461	411 considera que el gancho ha fallado.
jerojasro@461	412
jerojasro@461	413 Para los ganchos que controlan si una actividad puede continuar o no,
jerojasro@461	414 cero/falso quiere decir ``permitir'', mientras que
jerojasro@461	415 % TODO me suena mejor "no permitir" que "denegar"
jerojasro@461	416 no-cero/verdadero/excepción quiere decir ``no permitir''.
jerojasro@461	417
jerojasro@461	418 \subsection{Escribir un gancho externo}
jerojasro@461	419
jerojasro@461	420 Cuando usted define un gancho externo en su fichero \hgrc\ y el mismo
jerojasro@461	421 es ejecutado, dicha definición pasa a su intérprete de comandos, que
jerojasro@461	422 hace la interpretación correspondiente. Esto significa que usted puede
jerojasro@461	423 usar elementos normales del intérprete en el cuerpo del gancho.
jerojasro@461	424
jerojasro@461	425 Un gancho ejecutable siempre es ejecutado con su directorio actual
jerojasro@461	426 fijado al directorio raíz del repositorio.
jerojasro@461	427
jerojasro@461	428 Cada parámetro para el gancho es pasado como una variable de entorno;
jerojasro@461	429 el nombre está en mayúsculas, y tiene como prefijo la cadena
jerojasro@461	430 ``\texttt{HG\_}''.
jerojasro@461	431
jerojasro@461	432 Con la excepción de los parámetros para los ganchos, Mercurial no
jerojasro@461	433 define o modifica ninguna variable de entorno al ejecutar un gancho.
jerojasro@461	434 Es útil recordar esto al escribir un gancho global que podría ser
jerojasro@461	435 ejecutado por varios usuarios con distintas variables de entorno
jerojasro@461	436 fijadas. En situaciones con múltiples usuarios, usted no debería
jerojasro@461	437 asumir la existencia de ninguna variable de entorno, ni que sus
jerojasro@461	438 valores sean los mismos que tenían cuando usted probó el gancho en su
jerojasro@461	439 ambiente de trabajo.
jerojasro@461	440
jerojasro@461	441 \subsection{Indicar a Mercurial que use un gancho interno}
jerojasro@461	442
jerojasro@461	443 La sintaxis para definir un gancho interno en el fichero \hgrc\ es
jerojasro@461	444 ligeramente diferente de la usada para un gancho externo. El valor del
jerojasro@461	445 gancho debe comenzar con el texto ``\texttt{python:}'', y continuar
jerojasro@461	446 con el nombre completamente cualificado de un objeto invocable que se
jerojasro@461	447 usará como el valor del gancho.
jerojasro@461	448
jerojasro@461	449 El módulo en que vive un gancho es importado automáticamente cuando se
jerojasro@461	450 ejecuta un gancho. Siempre que usted tenga el nombre del módulo y la
jerojasro@461	451 variable de entorno \envar{PYTHONPATH} ajustada adecuadamente, todo
jerojasro@461	452 debería funcionar sin problemas.
jerojasro@461	453
jerojasro@461	454 El siguiente fragmento de ejemplo de un fichero \hgrc\ ilustra la
jerojasro@461	455 sintaxis y significado de los conceptos que acabamos de describir.
jerojasro@336	456 \begin{codesample2}
jerojasro@336	457 [hooks]
jerojasro@336	458 commit.example = python:mymodule.submodule.myhook
jerojasro@336	459 \end{codesample2}
jerojasro@461	460 Cuando Mercurial ejecuta el gancho \texttt{commit.example}, importa
jerojasro@461	461 \texttt{mymodule.submodule}, busca el objeto invocable llamado
jerojasro@461	462 \texttt{myhook}, y lo invoca (llama).
jerojasro@461	463
jerojasro@461	464 \subsection{Escribir un gancho interno}
jerojasro@461	465
jerojasro@461	466 El gancho interno más sencillo no hace nada, pero ilustra la
jerojasro@461	467 estructura básica de la API\footnote{\emph{Application Progamming
jerojasro@461	468 Interface}, Interfaz para Programación de Aplicaciones} para ganchos:
jerojasro@336	469 \begin{codesample2}
jerojasro@336	470 def myhook(ui, repo, **kwargs):
jerojasro@336	471 pass
jerojasro@336	472 \end{codesample2}
jerojasro@336	473 The first argument to a Python hook is always a
jerojasro@336	474 \pymodclass{mercurial.ui}{ui} object. The second is a repository object;
jerojasro@336	475 at the moment, it is always an instance of
jerojasro@336	476 \pymodclass{mercurial.localrepo}{localrepository}. Following these two
jerojasro@336	477 arguments are other keyword arguments. Which ones are passed in
jerojasro@336	478 depends on the hook being called, but a hook can ignore arguments it
jerojasro@336	479 doesn't care about by dropping them into a keyword argument dict, as
jerojasro@336	480 with \texttt{**kwargs} above.
jerojasro@336	481
jerojasro@336	482 \section{Some hook examples}
jerojasro@336	483
jerojasro@336	484 \subsection{Writing meaningful commit messages}
jerojasro@336	485
jerojasro@336	486 It's hard to imagine a useful commit message being very short. The
jerojasro@336	487 simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go}
jerojasro@336	488 will prevent you from committing a changeset with a message that is
jerojasro@336	489 less than ten bytes long.
jerojasro@336	490
jerojasro@336	491 \begin{figure}[ht]
jerojasro@336	492 \interaction{hook.msglen.go}
jerojasro@336	493 \caption{A hook that forbids overly short commit messages}
jerojasro@336	494 \label{ex:hook:msglen.go}
jerojasro@336	495 \end{figure}
jerojasro@336	496
jerojasro@336	497 \subsection{Checking for trailing whitespace}
jerojasro@336	498
jerojasro@336	499 An interesting use of a commit-related hook is to help you to write
jerojasro@336	500 cleaner code. A simple example of ``cleaner code'' is the dictum that
jerojasro@336	501 a change should not add any new lines of text that contain ``trailing
jerojasro@336	502 whitespace''. Trailing whitespace is a series of space and tab
jerojasro@336	503 characters at the end of a line of text. In most cases, trailing
jerojasro@336	504 whitespace is unnecessary, invisible noise, but it is occasionally
jerojasro@336	505 problematic, and people often prefer to get rid of it.
jerojasro@336	506
jerojasro@336	507 You can use either the \hook{precommit} or \hook{pretxncommit} hook to
jerojasro@336	508 tell whether you have a trailing whitespace problem. If you use the
jerojasro@336	509 \hook{precommit} hook, the hook will not know which files you are
jerojasro@336	510 committing, so it will have to check every modified file in the
jerojasro@336	511 repository for trailing white space. If you want to commit a change
jerojasro@336	512 to just the file \filename{foo}, but the file \filename{bar} contains
jerojasro@336	513 trailing whitespace, doing a check in the \hook{precommit} hook will
jerojasro@336	514 prevent you from committing \filename{foo} due to the problem with
jerojasro@336	515 \filename{bar}. This doesn't seem right.
jerojasro@336	516
jerojasro@336	517 Should you choose the \hook{pretxncommit} hook, the check won't occur
jerojasro@336	518 until just before the transaction for the commit completes. This will
jerojasro@336	519 allow you to check for problems only the exact files that are being
jerojasro@336	520 committed. However, if you entered the commit message interactively
jerojasro@336	521 and the hook fails, the transaction will roll back; you'll have to
jerojasro@336	522 re-enter the commit message after you fix the trailing whitespace and
jerojasro@336	523 run \hgcmd{commit} again.
jerojasro@336	524
jerojasro@336	525 \begin{figure}[ht]
jerojasro@336	526 \interaction{hook.ws.simple}
jerojasro@336	527 \caption{A simple hook that checks for trailing whitespace}
jerojasro@336	528 \label{ex:hook:ws.simple}
jerojasro@336	529 \end{figure}
jerojasro@336	530
jerojasro@336	531 Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
jerojasro@336	532 hook that checks for trailing whitespace. This hook is short, but not
jerojasro@336	533 very helpful. It exits with an error status if a change adds a line
jerojasro@336	534 with trailing whitespace to any file, but does not print any
jerojasro@336	535 information that might help us to identify the offending file or
jerojasro@336	536 line. It also has the nice property of not paying attention to
jerojasro@336	537 unmodified lines; only lines that introduce new trailing whitespace
jerojasro@336	538 cause problems.
jerojasro@336	539
jerojasro@336	540 \begin{figure}[ht]
jerojasro@336	541 \interaction{hook.ws.better}
jerojasro@336	542 \caption{A better trailing whitespace hook}
jerojasro@336	543 \label{ex:hook:ws.better}
jerojasro@336	544 \end{figure}
jerojasro@336	545
jerojasro@336	546 The example of figure~\ref{ex:hook:ws.better} is much more complex,
jerojasro@336	547 but also more useful. It parses a unified diff to see if any lines
jerojasro@336	548 add trailing whitespace, and prints the name of the file and the line
jerojasro@336	549 number of each such occurrence. Even better, if the change adds
jerojasro@336	550 trailing whitespace, this hook saves the commit comment and prints the
jerojasro@336	551 name of the save file before exiting and telling Mercurial to roll the
jerojasro@336	552 transaction back, so you can use
jerojasro@336	553 \hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
jerojasro@336	554 saved commit message once you've corrected the problem.
jerojasro@336	555
jerojasro@336	556 As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
jerojasro@336	557 \command{perl}'s in-place editing feature to get rid of trailing
jerojasro@336	558 whitespace from a file. This is concise and useful enough that I will
jerojasro@336	559 reproduce it here.
jerojasro@336	560 \begin{codesample2}
jerojasro@336	561 perl -pi -e 's,\\s+\$,,' filename
jerojasro@336	562 \end{codesample2}
jerojasro@336	563
jerojasro@336	564 \section{Bundled hooks}
jerojasro@336	565
jerojasro@336	566 Mercurial ships with several bundled hooks. You can find them in the
jerojasro@336	567 \dirname{hgext} directory of a Mercurial source tree. If you are
jerojasro@336	568 using a Mercurial binary package, the hooks will be located in the
jerojasro@336	569 \dirname{hgext} directory of wherever your package installer put
jerojasro@336	570 Mercurial.
jerojasro@336	571
jerojasro@336	572 \subsection{\hgext{acl}---access control for parts of a repository}
jerojasro@336	573
jerojasro@336	574 The \hgext{acl} extension lets you control which remote users are
jerojasro@336	575 allowed to push changesets to a networked server. You can protect any
jerojasro@336	576 portion of a repository (including the entire repo), so that a
jerojasro@336	577 specific remote user can push changes that do not affect the protected
jerojasro@336	578 portion.
jerojasro@336	579
jerojasro@336	580 This extension implements access control based on the identity of the
jerojasro@336	581 user performing a push, \emph{not} on who committed the changesets
jerojasro@336	582 they're pushing. It makes sense to use this hook only if you have a
jerojasro@336	583 locked-down server environment that authenticates remote users, and
jerojasro@336	584 you want to be sure that only specific users are allowed to push
jerojasro@336	585 changes to that server.
jerojasro@336	586
jerojasro@336	587 \subsubsection{Configuring the \hook{acl} hook}
jerojasro@336	588
jerojasro@336	589 In order to manage incoming changesets, the \hgext{acl} hook must be
jerojasro@336	590 used as a \hook{pretxnchangegroup} hook. This lets it see which files
jerojasro@336	591 are modified by each incoming changeset, and roll back a group of
jerojasro@336	592 changesets if they modify ``forbidden'' files. Example:
jerojasro@336	593 \begin{codesample2}
jerojasro@336	594 [hooks]
jerojasro@336	595 pretxnchangegroup.acl = python:hgext.acl.hook
jerojasro@336	596 \end{codesample2}
jerojasro@336	597
jerojasro@336	598 The \hgext{acl} extension is configured using three sections.
jerojasro@336	599
jerojasro@336	600 The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
jerojasro@336	601 which lists the sources of incoming changesets that the hook should
jerojasro@336	602 pay attention to. You don't normally need to configure this section.
jerojasro@336	603 \begin{itemize}
jerojasro@336	604 \item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
jerojasro@336	605 from a remote repository over http or ssh. This is the default
jerojasro@336	606 value of \rcitem{acl}{sources}, and usually the only setting you'll
jerojasro@336	607 need for this configuration item.
jerojasro@336	608 \item[\rcitem{acl}{pull}] Control incoming changesets that are
jerojasro@336	609 arriving via a pull from a local repository.
jerojasro@336	610 \item[\rcitem{acl}{push}] Control incoming changesets that are
jerojasro@336	611 arriving via a push from a local repository.
jerojasro@336	612 \item[\rcitem{acl}{bundle}] Control incoming changesets that are
jerojasro@336	613 arriving from another repository via a bundle.
jerojasro@336	614 \end{itemize}
jerojasro@336	615
jerojasro@336	616 The \rcsection{acl.allow} section controls the users that are allowed to
jerojasro@336	617 add changesets to the repository. If this section is not present, all
jerojasro@336	618 users that are not explicitly denied are allowed. If this section is
jerojasro@336	619 present, all users that are not explicitly allowed are denied (so an
jerojasro@336	620 empty section means that all users are denied).
jerojasro@336	621
jerojasro@336	622 The \rcsection{acl.deny} section determines which users are denied
jerojasro@336	623 from adding changesets to the repository. If this section is not
jerojasro@336	624 present or is empty, no users are denied.
jerojasro@336	625
jerojasro@336	626 The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
jerojasro@336	627 sections are identical. On the left of each entry is a glob pattern
jerojasro@336	628 that matches files or directories, relative to the root of the
jerojasro@336	629 repository; on the right, a user name.
jerojasro@336	630
jerojasro@336	631 In the following example, the user \texttt{docwriter} can only push
jerojasro@336	632 changes to the \dirname{docs} subtree of the repository, while
jerojasro@336	633 \texttt{intern} can push changes to any file or directory except
jerojasro@336	634 \dirname{source/sensitive}.
jerojasro@336	635 \begin{codesample2}
jerojasro@336	636 [acl.allow]
jerojasro@336	637 docs/** = docwriter
jerojasro@336	638
jerojasro@336	639 [acl.deny]
jerojasro@336	640 source/sensitive/** = intern
jerojasro@336	641 \end{codesample2}
jerojasro@336	642
jerojasro@336	643 \subsubsection{Testing and troubleshooting}
jerojasro@336	644
jerojasro@336	645 If you want to test the \hgext{acl} hook, run it with Mercurial's
jerojasro@336	646 debugging output enabled. Since you'll probably be running it on a
jerojasro@336	647 server where it's not convenient (or sometimes possible) to pass in
jerojasro@336	648 the \hggopt{--debug} option, don't forget that you can enable
jerojasro@336	649 debugging output in your \hgrc:
jerojasro@336	650 \begin{codesample2}
jerojasro@336	651 [ui]
jerojasro@336	652 debug = true
jerojasro@336	653 \end{codesample2}
jerojasro@336	654 With this enabled, the \hgext{acl} hook will print enough information
jerojasro@336	655 to let you figure out why it is allowing or forbidding pushes from
jerojasro@336	656 specific users.
jerojasro@336	657
jerojasro@336	658 \subsection{\hgext{bugzilla}---integration with Bugzilla}
jerojasro@336	659
jerojasro@336	660 The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
jerojasro@336	661 whenever it finds a reference to that bug ID in a commit comment. You
jerojasro@336	662 can install this hook on a shared server, so that any time a remote
jerojasro@336	663 user pushes changes to this server, the hook gets run.
jerojasro@336	664
jerojasro@336	665 It adds a comment to the bug that looks like this (you can configure
jerojasro@336	666 the contents of the comment---see below):
jerojasro@336	667 \begin{codesample2}
jerojasro@336	668 Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
jerojasro@336	669 the frobnitz repository, refers to this bug.
jerojasro@336	670
jerojasro@336	671 For complete details, see
jerojasro@336	672 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
jerojasro@336	673
jerojasro@336	674 Changeset description:
jerojasro@336	675 Fix bug 10483 by guarding against some NULL pointers
jerojasro@336	676 \end{codesample2}
jerojasro@336	677 The value of this hook is that it automates the process of updating a
jerojasro@336	678 bug any time a changeset refers to it. If you configure the hook
jerojasro@336	679 properly, it makes it easy for people to browse straight from a
jerojasro@336	680 Bugzilla bug to a changeset that refers to that bug.
jerojasro@336	681
jerojasro@336	682 You can use the code in this hook as a starting point for some more
jerojasro@336	683 exotic Bugzilla integration recipes. Here are a few possibilities:
jerojasro@336	684 \begin{itemize}
jerojasro@336	685 \item Require that every changeset pushed to the server have a valid
jerojasro@336	686 bug~ID in its commit comment. In this case, you'd want to configure
jerojasro@336	687 the hook as a \hook{pretxncommit} hook. This would allow the hook
jerojasro@336	688 to reject changes that didn't contain bug IDs.
jerojasro@336	689 \item Allow incoming changesets to automatically modify the
jerojasro@336	690 \emph{state} of a bug, as well as simply adding a comment. For
jerojasro@336	691 example, the hook could recognise the string ``fixed bug 31337'' as
jerojasro@336	692 indicating that it should update the state of bug 31337 to
jerojasro@336	693 ``requires testing''.
jerojasro@336	694 \end{itemize}
jerojasro@336	695
jerojasro@336	696 \subsubsection{Configuring the \hook{bugzilla} hook}
jerojasro@336	697 \label{sec:hook:bugzilla:config}
jerojasro@336	698
jerojasro@336	699 You should configure this hook in your server's \hgrc\ as an
jerojasro@336	700 \hook{incoming} hook, for example as follows:
jerojasro@336	701 \begin{codesample2}
jerojasro@336	702 [hooks]
jerojasro@336	703 incoming.bugzilla = python:hgext.bugzilla.hook
jerojasro@336	704 \end{codesample2}
jerojasro@336	705
jerojasro@336	706 Because of the specialised nature of this hook, and because Bugzilla
jerojasro@336	707 was not written with this kind of integration in mind, configuring
jerojasro@336	708 this hook is a somewhat involved process.
jerojasro@336	709
jerojasro@336	710 Before you begin, you must install the MySQL bindings for Python on
jerojasro@336	711 the host(s) where you'll be running the hook. If this is not
jerojasro@336	712 available as a binary package for your system, you can download it
jerojasro@336	713 from~\cite{web:mysql-python}.
jerojasro@336	714
jerojasro@336	715 Configuration information for this hook lives in the
jerojasro@336	716 \rcsection{bugzilla} section of your \hgrc.
jerojasro@336	717 \begin{itemize}
jerojasro@336	718 \item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
jerojasro@336	719 the server. The database schema that Bugzilla uses changes
jerojasro@336	720 occasionally, so this hook has to know exactly which schema to use.
jerojasro@336	721 At the moment, the only version supported is \texttt{2.16}.
jerojasro@336	722 \item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
jerojasro@336	723 stores your Bugzilla data. The database must be configured to allow
jerojasro@336	724 connections from whatever host you are running the \hook{bugzilla}
jerojasro@336	725 hook on.
jerojasro@336	726 \item[\rcitem{bugzilla}{user}] The username with which to connect to
jerojasro@336	727 the MySQL server. The database must be configured to allow this
jerojasro@336	728 user to connect from whatever host you are running the
jerojasro@336	729 \hook{bugzilla} hook on. This user must be able to access and
jerojasro@336	730 modify Bugzilla tables. The default value of this item is
jerojasro@336	731 \texttt{bugs}, which is the standard name of the Bugzilla user in a
jerojasro@336	732 MySQL database.
jerojasro@336	733 \item[\rcitem{bugzilla}{password}] The MySQL password for the user you
jerojasro@336	734 configured above. This is stored as plain text, so you should make
jerojasro@336	735 sure that unauthorised users cannot read the \hgrc\ file where you
jerojasro@336	736 store this information.
jerojasro@336	737 \item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
jerojasro@336	738 MySQL server. The default value of this item is \texttt{bugs},
jerojasro@336	739 which is the standard name of the MySQL database where Bugzilla
jerojasro@336	740 stores its data.
jerojasro@336	741 \item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
jerojasro@336	742 notification email to subscribers after this hook has added a
jerojasro@336	743 comment to a bug, you will need this hook to run a command whenever
jerojasro@336	744 it updates the database. The command to run depends on where you
jerojasro@336	745 have installed Bugzilla, but it will typically look something like
jerojasro@336	746 this, if you have Bugzilla installed in
jerojasro@336	747 \dirname{/var/www/html/bugzilla}:
jerojasro@336	748 \begin{codesample4}
jerojasro@336	749 cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
jerojasro@336	750 \end{codesample4}
jerojasro@336	751 The Bugzilla \texttt{processmail} program expects to be given a
jerojasro@336	752 bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
jerojasro@336	753 email address. It also expects to be able to write to some files in
jerojasro@336	754 the directory that it runs in. If Bugzilla and this hook are not
jerojasro@336	755 installed on the same machine, you will need to find a way to run
jerojasro@336	756 \texttt{processmail} on the server where Bugzilla is installed.
jerojasro@336	757 \end{itemize}
jerojasro@336	758
jerojasro@336	759 \subsubsection{Mapping committer names to Bugzilla user names}
jerojasro@336	760
jerojasro@336	761 By default, the \hgext{bugzilla} hook tries to use the email address
jerojasro@336	762 of a changeset's committer as the Bugzilla user name with which to
jerojasro@336	763 update a bug. If this does not suit your needs, you can map committer
jerojasro@336	764 email addresses to Bugzilla user names using a \rcsection{usermap}
jerojasro@336	765 section.
jerojasro@336	766
jerojasro@336	767 Each item in the \rcsection{usermap} section contains an email address
jerojasro@336	768 on the left, and a Bugzilla user name on the right.
jerojasro@336	769 \begin{codesample2}
jerojasro@336	770 [usermap]
jerojasro@336	771 jane.user@example.com = jane
jerojasro@336	772 \end{codesample2}
jerojasro@336	773 You can either keep the \rcsection{usermap} data in a normal \hgrc, or
jerojasro@336	774 tell the \hgext{bugzilla} hook to read the information from an
jerojasro@336	775 external \filename{usermap} file. In the latter case, you can store
jerojasro@336	776 \filename{usermap} data by itself in (for example) a user-modifiable
jerojasro@336	777 repository. This makes it possible to let your users maintain their
jerojasro@336	778 own \rcitem{bugzilla}{usermap} entries. The main \hgrc\ file might
jerojasro@336	779 look like this:
jerojasro@336	780 \begin{codesample2}
jerojasro@336	781 # regular hgrc file refers to external usermap file
jerojasro@336	782 [bugzilla]
jerojasro@336	783 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
jerojasro@336	784 \end{codesample2}
jerojasro@336	785 While the \filename{usermap} file that it refers to might look like
jerojasro@336	786 this:
jerojasro@336	787 \begin{codesample2}
jerojasro@336	788 # bugzilla-usermap.conf - inside a hg repository
jerojasro@336	789 [usermap]
jerojasro@336	790 stephanie@example.com = steph
jerojasro@336	791 \end{codesample2}
jerojasro@336	792
jerojasro@336	793 \subsubsection{Configuring the text that gets added to a bug}
jerojasro@336	794
jerojasro@336	795 You can configure the text that this hook adds as a comment; you
jerojasro@336	796 specify it in the form of a Mercurial template. Several \hgrc\
jerojasro@336	797 entries (still in the \rcsection{bugzilla} section) control this
jerojasro@336	798 behaviour.
jerojasro@336	799 \begin{itemize}
jerojasro@336	800 \item[\texttt{strip}] The number of leading path elements to strip
jerojasro@336	801 from a repository's path name to construct a partial path for a URL.
jerojasro@336	802 For example, if the repositories on your server live under
jerojasro@336	803 \dirname{/home/hg/repos}, and you have a repository whose path is
jerojasro@336	804 \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
jerojasro@336	805 \texttt{4} will give a partial path of \dirname{app/tests}. The
jerojasro@336	806 hook will make this partial path available when expanding a
jerojasro@336	807 template, as \texttt{webroot}.
jerojasro@336	808 \item[\texttt{template}] The text of the template to use. In addition
jerojasro@336	809 to the usual changeset-related variables, this template can use
jerojasro@336	810 \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
jerojasro@336	811 above) and \texttt{webroot} (the path constructed using
jerojasro@336	812 \texttt{strip} above).
jerojasro@336	813 \end{itemize}
jerojasro@336	814
jerojasro@336	815 In addition, you can add a \rcitem{web}{baseurl} item to the
jerojasro@336	816 \rcsection{web} section of your \hgrc. The \hgext{bugzilla} hook will
jerojasro@336	817 make this available when expanding a template, as the base string to
jerojasro@336	818 use when constructing a URL that will let users browse from a Bugzilla
jerojasro@336	819 comment to view a changeset. Example:
jerojasro@336	820 \begin{codesample2}
jerojasro@336	821 [web]
jerojasro@336	822 baseurl = http://hg.domain.com/
jerojasro@336	823 \end{codesample2}
jerojasro@336	824
jerojasro@336	825 Here is an example set of \hgext{bugzilla} hook config information.
jerojasro@336	826 \begin{codesample2}
jerojasro@336	827 [bugzilla]
jerojasro@336	828 host = bugzilla.example.com
jerojasro@336	829 password = mypassword
jerojasro@336	830 version = 2.16
jerojasro@336	831 # server-side repos live in /home/hg/repos, so strip 4 leading
jerojasro@336	832 # separators
jerojasro@336	833 strip = 4
jerojasro@336	834 hgweb = http://hg.example.com/
jerojasro@336	835 usermap = /home/hg/repos/notify/bugzilla.conf
jerojasro@336	836 template = Changeset \{node\|short\}, made by \{author\} in the \{webroot\}
jerojasro@336	837 repo, refers to this bug.\\nFor complete details, see
jerojasro@336	838 \{hgweb\}\{webroot\}?cmd=changeset;node=\{node\|short\}\\nChangeset
jerojasro@336	839 description:\\n\\t\{desc\|tabindent\}
jerojasro@336	840 \end{codesample2}
jerojasro@336	841
jerojasro@336	842 \subsubsection{Testing and troubleshooting}
jerojasro@336	843
jerojasro@336	844 The most common problems with configuring the \hgext{bugzilla} hook
jerojasro@336	845 relate to running Bugzilla's \filename{processmail} script and mapping
jerojasro@336	846 committer names to user names.
jerojasro@336	847
jerojasro@336	848 Recall from section~\ref{sec:hook:bugzilla:config} above that the user
jerojasro@336	849 that runs the Mercurial process on the server is also the one that
jerojasro@336	850 will run the \filename{processmail} script. The
jerojasro@336	851 \filename{processmail} script sometimes causes Bugzilla to write to
jerojasro@336	852 files in its configuration directory, and Bugzilla's configuration
jerojasro@336	853 files are usually owned by the user that your web server runs under.
jerojasro@336	854
jerojasro@336	855 You can cause \filename{processmail} to be run with the suitable
jerojasro@336	856 user's identity using the \command{sudo} command. Here is an example
jerojasro@336	857 entry for a \filename{sudoers} file.
jerojasro@336	858 \begin{codesample2}
jerojasro@336	859 hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
jerojasro@336	860 \end{codesample2}
jerojasro@336	861 This allows the \texttt{hg\_user} user to run a
jerojasro@336	862 \filename{processmail-wrapper} program under the identity of
jerojasro@336	863 \texttt{httpd\_user}.
jerojasro@336	864
jerojasro@336	865 This indirection through a wrapper script is necessary, because
jerojasro@336	866 \filename{processmail} expects to be run with its current directory
jerojasro@336	867 set to wherever you installed Bugzilla; you can't specify that kind of
jerojasro@336	868 constraint in a \filename{sudoers} file. The contents of the wrapper
jerojasro@336	869 script are simple:
jerojasro@336	870 \begin{codesample2}
jerojasro@336	871 #!/bin/sh
jerojasro@336	872 cd `dirname $0` && ./processmail "$1" nobody@example.com
jerojasro@336	873 \end{codesample2}
jerojasro@336	874 It doesn't seem to matter what email address you pass to
jerojasro@336	875 \filename{processmail}.
jerojasro@336	876
jerojasro@336	877 If your \rcsection{usermap} is not set up correctly, users will see an
jerojasro@336	878 error message from the \hgext{bugzilla} hook when they push changes
jerojasro@336	879 to the server. The error message will look like this:
jerojasro@336	880 \begin{codesample2}
jerojasro@336	881 cannot find bugzilla user id for john.q.public@example.com
jerojasro@336	882 \end{codesample2}
jerojasro@336	883 What this means is that the committer's address,
jerojasro@336	884 \texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
jerojasro@336	885 nor does it have an entry in your \rcsection{usermap} that maps it to
jerojasro@336	886 a valid Bugzilla user name.
jerojasro@336	887
jerojasro@336	888 \subsection{\hgext{notify}---send email notifications}
jerojasro@336	889
jerojasro@336	890 Although Mercurial's built-in web server provides RSS feeds of changes
jerojasro@336	891 in every repository, many people prefer to receive change
jerojasro@336	892 notifications via email. The \hgext{notify} hook lets you send out
jerojasro@336	893 notifications to a set of email addresses whenever changesets arrive
jerojasro@336	894 that those subscribers are interested in.
jerojasro@336	895
jerojasro@336	896 As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
jerojasro@336	897 template-driven, so you can customise the contents of the notification
jerojasro@336	898 messages that it sends.
jerojasro@336	899
jerojasro@336	900 By default, the \hgext{notify} hook includes a diff of every changeset
jerojasro@336	901 that it sends out; you can limit the size of the diff, or turn this
jerojasro@336	902 feature off entirely. It is useful for letting subscribers review
jerojasro@336	903 changes immediately, rather than clicking to follow a URL.
jerojasro@336	904
jerojasro@336	905 \subsubsection{Configuring the \hgext{notify} hook}
jerojasro@336	906
jerojasro@336	907 You can set up the \hgext{notify} hook to send one email message per
jerojasro@336	908 incoming changeset, or one per incoming group of changesets (all those
jerojasro@336	909 that arrived in a single pull or push).
jerojasro@336	910 \begin{codesample2}
jerojasro@336	911 [hooks]
jerojasro@336	912 # send one email per group of changes
jerojasro@336	913 changegroup.notify = python:hgext.notify.hook
jerojasro@336	914 # send one email per change
jerojasro@336	915 incoming.notify = python:hgext.notify.hook
jerojasro@336	916 \end{codesample2}
jerojasro@336	917
jerojasro@336	918 Configuration information for this hook lives in the
jerojasro@336	919 \rcsection{notify} section of a \hgrc\ file.
jerojasro@336	920 \begin{itemize}
jerojasro@336	921 \item[\rcitem{notify}{test}] By default, this hook does not send out
jerojasro@336	922 email at all; instead, it prints the message that it \emph{would}
jerojasro@336	923 send. Set this item to \texttt{false} to allow email to be sent.
jerojasro@336	924 The reason that sending of email is turned off by default is that it
jerojasro@336	925 takes several tries to configure this extension exactly as you would
jerojasro@336	926 like, and it would be bad form to spam subscribers with a number of
jerojasro@336	927 ``broken'' notifications while you debug your configuration.
jerojasro@336	928 \item[\rcitem{notify}{config}] The path to a configuration file that
jerojasro@336	929 contains subscription information. This is kept separate from the
jerojasro@336	930 main \hgrc\ so that you can maintain it in a repository of its own.
jerojasro@336	931 People can then clone that repository, update their subscriptions,
jerojasro@336	932 and push the changes back to your server.
jerojasro@336	933 \item[\rcitem{notify}{strip}] The number of leading path separator
jerojasro@336	934 characters to strip from a repository's path, when deciding whether
jerojasro@336	935 a repository has subscribers. For example, if the repositories on
jerojasro@336	936 your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
jerojasro@336	937 considering a repository named \dirname{/home/hg/repos/shared/test},
jerojasro@336	938 setting \rcitem{notify}{strip} to \texttt{4} will cause
jerojasro@336	939 \hgext{notify} to trim the path it considers down to
jerojasro@336	940 \dirname{shared/test}, and it will match subscribers against that.
jerojasro@336	941 \item[\rcitem{notify}{template}] The template text to use when sending
jerojasro@336	942 messages. This specifies both the contents of the message header
jerojasro@336	943 and its body.
jerojasro@336	944 \item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
jerojasro@336	945 data to append to the end of a message. If a diff is longer than
jerojasro@336	946 this, it is truncated. By default, this is set to 300. Set this to
jerojasro@336	947 \texttt{0} to omit diffs from notification emails.
jerojasro@336	948 \item[\rcitem{notify}{sources}] A list of sources of changesets to
jerojasro@336	949 consider. This lets you limit \hgext{notify} to only sending out
jerojasro@336	950 email about changes that remote users pushed into this repository
jerojasro@336	951 via a server, for example. See section~\ref{sec:hook:sources} for
jerojasro@336	952 the sources you can specify here.
jerojasro@336	953 \end{itemize}
jerojasro@336	954
jerojasro@336	955 If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
jerojasro@336	956 section, you can use it in a template; it will be available as
jerojasro@336	957 \texttt{webroot}.
jerojasro@336	958
jerojasro@336	959 Here is an example set of \hgext{notify} configuration information.
jerojasro@336	960 \begin{codesample2}
jerojasro@336	961 [notify]
jerojasro@336	962 # really send email
jerojasro@336	963 test = false
jerojasro@336	964 # subscriber data lives in the notify repo
jerojasro@336	965 config = /home/hg/repos/notify/notify.conf
jerojasro@336	966 # repos live in /home/hg/repos on server, so strip 4 "/" chars
jerojasro@336	967 strip = 4
jerojasro@336	968 template = X-Hg-Repo: \{webroot\}
jerojasro@336	969 Subject: \{webroot\}: \{desc\|firstline\|strip\}
jerojasro@336	970 From: \{author\}
jerojasro@336	971
jerojasro@336	972 changeset \{node\|short\} in \{root\}
jerojasro@336	973 details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node\|short\}
jerojasro@336	974 description:
jerojasro@336	975 \{desc\|tabindent\|strip\}
jerojasro@336	976
jerojasro@336	977 [web]
jerojasro@336	978 baseurl = http://hg.example.com/
jerojasro@336	979 \end{codesample2}
jerojasro@336	980
jerojasro@336	981 This will produce a message that looks like the following:
jerojasro@336	982 \begin{codesample2}
jerojasro@336	983 X-Hg-Repo: tests/slave
jerojasro@336	984 Subject: tests/slave: Handle error case when slave has no buffers
jerojasro@336	985 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
jerojasro@336	986
jerojasro@336	987 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
jerojasro@336	988 details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
jerojasro@336	989 description:
jerojasro@336	990 Handle error case when slave has no buffers
jerojasro@336	991 diffs (54 lines):
jerojasro@336	992
jerojasro@336	993 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
jerojasro@336	994 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
jerojasro@336	995 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
jerojasro@336	996 @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
jerojasro@336	997 [...snip...]
jerojasro@336	998 \end{codesample2}
jerojasro@336	999
jerojasro@336	1000 \subsubsection{Testing and troubleshooting}
jerojasro@336	1001
jerojasro@336	1002 Do not forget that by default, the \hgext{notify} extension \emph{will
jerojasro@336	1003 not send any mail} until you explicitly configure it to do so, by
jerojasro@336	1004 setting \rcitem{notify}{test} to \texttt{false}. Until you do that,
jerojasro@336	1005 it simply prints the message it \emph{would} send.
jerojasro@336	1006
jerojasro@336	1007 \section{Information for writers of hooks}
jerojasro@336	1008 \label{sec:hook:ref}
jerojasro@336	1009
jerojasro@336	1010 \subsection{In-process hook execution}
jerojasro@336	1011
jerojasro@336	1012 An in-process hook is called with arguments of the following form:
jerojasro@336	1013 \begin{codesample2}
jerojasro@336	1014 def myhook(ui, repo, **kwargs):
jerojasro@336	1015 pass
jerojasro@336	1016 \end{codesample2}
jerojasro@336	1017 The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
jerojasro@336	1018 The \texttt{repo} parameter is a
jerojasro@336	1019 \pymodclass{mercurial.localrepo}{localrepository} object. The
jerojasro@336	1020 names and values of the \texttt{**kwargs} parameters depend on the
jerojasro@336	1021 hook being invoked, with the following common features:
jerojasro@336	1022 \begin{itemize}
jerojasro@336	1023 \item If a parameter is named \texttt{node} or
jerojasro@336	1024 \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
jerojasro@336	1025 The empty string is used to represent ``null changeset ID'' instead
jerojasro@336	1026 of a string of zeroes.
jerojasro@336	1027 \item If a parameter is named \texttt{url}, it will contain the URL of
jerojasro@336	1028 a remote repository, if that can be determined.
jerojasro@336	1029 \item Boolean-valued parameters are represented as Python
jerojasro@336	1030 \texttt{bool} objects.
jerojasro@336	1031 \end{itemize}
jerojasro@336	1032
jerojasro@336	1033 An in-process hook is called without a change to the process's working
jerojasro@336	1034 directory (unlike external hooks, which are run in the root of the
jerojasro@336	1035 repository). It must not change the process's working directory, or
jerojasro@336	1036 it will cause any calls it makes into the Mercurial API to fail.
jerojasro@336	1037
jerojasro@336	1038 If a hook returns a boolean ``false'' value, it is considered to have
jerojasro@336	1039 succeeded. If it returns a boolean ``true'' value or raises an
jerojasro@336	1040 exception, it is considered to have failed. A useful way to think of
jerojasro@336	1041 the calling convention is ``tell me if you fail''.
jerojasro@336	1042
jerojasro@336	1043 Note that changeset IDs are passed into Python hooks as hexadecimal
jerojasro@336	1044 strings, not the binary hashes that Mercurial's APIs normally use. To
jerojasro@336	1045 convert a hash from hex to binary, use the
jerojasro@336	1046 \pymodfunc{mercurial.node}{bin} function.
jerojasro@336	1047
jerojasro@336	1048 \subsection{External hook execution}
jerojasro@336	1049
jerojasro@336	1050 An external hook is passed to the shell of the user running Mercurial.
jerojasro@336	1051 Features of that shell, such as variable substitution and command
jerojasro@336	1052 redirection, are available. The hook is run in the root directory of
jerojasro@336	1053 the repository (unlike in-process hooks, which are run in the same
jerojasro@336	1054 directory that Mercurial was run in).
jerojasro@336	1055
jerojasro@336	1056 Hook parameters are passed to the hook as environment variables. Each
jerojasro@336	1057 environment variable's name is converted in upper case and prefixed
jerojasro@336	1058 with the string ``\texttt{HG\_}''. For example, if the name of a
jerojasro@336	1059 parameter is ``\texttt{node}'', the name of the environment variable
jerojasro@336	1060 representing that parameter will be ``\texttt{HG\_NODE}''.
jerojasro@336	1061
jerojasro@336	1062 A boolean parameter is represented as the string ``\texttt{1}'' for
jerojasro@336	1063 ``true'', ``\texttt{0}'' for ``false''. If an environment variable is
jerojasro@336	1064 named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
jerojasro@336	1065 contains a changeset ID represented as a hexadecimal string. The
jerojasro@336	1066 empty string is used to represent ``null changeset ID'' instead of a
jerojasro@336	1067 string of zeroes. If an environment variable is named
jerojasro@336	1068 \envar{HG\_URL}, it will contain the URL of a remote repository, if
jerojasro@336	1069 that can be determined.
jerojasro@336	1070
jerojasro@336	1071 If a hook exits with a status of zero, it is considered to have
jerojasro@336	1072 succeeded. If it exits with a non-zero status, it is considered to
jerojasro@336	1073 have failed.
jerojasro@336	1074
jerojasro@336	1075 \subsection{Finding out where changesets come from}
jerojasro@336	1076
jerojasro@336	1077 A hook that involves the transfer of changesets between a local
jerojasro@336	1078 repository and another may be able to find out information about the
jerojasro@336	1079 ``far side''. Mercurial knows \emph{how} changes are being
jerojasro@336	1080 transferred, and in many cases \emph{where} they are being transferred
jerojasro@336	1081 to or from.
jerojasro@336	1082
jerojasro@336	1083 \subsubsection{Sources of changesets}
jerojasro@336	1084 \label{sec:hook:sources}
jerojasro@336	1085
jerojasro@336	1086 Mercurial will tell a hook what means are, or were, used to transfer
jerojasro@336	1087 changesets between repositories. This is provided by Mercurial in a
jerojasro@336	1088 Python parameter named \texttt{source}, or an environment variable named
jerojasro@336	1089 \envar{HG\_SOURCE}.
jerojasro@336	1090
jerojasro@336	1091 \begin{itemize}
jerojasro@336	1092 \item[\texttt{serve}] Changesets are transferred to or from a remote
jerojasro@336	1093 repository over http or ssh.
jerojasro@336	1094 \item[\texttt{pull}] Changesets are being transferred via a pull from
jerojasro@336	1095 one repository into another.
jerojasro@336	1096 \item[\texttt{push}] Changesets are being transferred via a push from
jerojasro@336	1097 one repository into another.
jerojasro@336	1098 \item[\texttt{bundle}] Changesets are being transferred to or from a
jerojasro@336	1099 bundle.
jerojasro@336	1100 \end{itemize}
jerojasro@336	1101
jerojasro@336	1102 \subsubsection{Where changes are going---remote repository URLs}
jerojasro@336	1103 \label{sec:hook:url}
jerojasro@336	1104
jerojasro@336	1105 When possible, Mercurial will tell a hook the location of the ``far
jerojasro@336	1106 side'' of an activity that transfers changeset data between
jerojasro@336	1107 repositories. This is provided by Mercurial in a Python parameter
jerojasro@336	1108 named \texttt{url}, or an environment variable named \envar{HG\_URL}.
jerojasro@336	1109
jerojasro@336	1110 This information is not always known. If a hook is invoked in a
jerojasro@336	1111 repository that is being served via http or ssh, Mercurial cannot tell
jerojasro@336	1112 where the remote repository is, but it may know where the client is
jerojasro@336	1113 connecting from. In such cases, the URL will take one of the
jerojasro@336	1114 following forms:
jerojasro@336	1115 \begin{itemize}
jerojasro@336	1116 \item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
jerojasro@336	1117 the given IP address.
jerojasro@336	1118 \item \texttt{remote:http:\emph{ip-address}}---remote http client, at
jerojasro@336	1119 the given IP address. If the client is using SSL, this will be of
jerojasro@336	1120 the form \texttt{remote:https:\emph{ip-address}}.
jerojasro@336	1121 \item Empty---no information could be discovered about the remote
jerojasro@336	1122 client.
jerojasro@336	1123 \end{itemize}
jerojasro@336	1124
jerojasro@336	1125 \section{Hook reference}
jerojasro@336	1126
jerojasro@336	1127 \subsection{\hook{changegroup}---after remote changesets added}
jerojasro@336	1128 \label{sec:hook:changegroup}
jerojasro@336	1129
jerojasro@336	1130 This hook is run after a group of pre-existing changesets has been
jerojasro@336	1131 added to the repository, for example via a \hgcmd{pull} or
jerojasro@336	1132 \hgcmd{unbundle}. This hook is run once per operation that added one
jerojasro@336	1133 or more changesets. This is in contrast to the \hook{incoming} hook,
jerojasro@336	1134 which is run once per changeset, regardless of whether the changesets
jerojasro@336	1135 arrive in a group.
jerojasro@336	1136
jerojasro@336	1137 Some possible uses for this hook include kicking off an automated
jerojasro@336	1138 build or test of the added changesets, updating a bug database, or
jerojasro@336	1139 notifying subscribers that a repository contains new changes.
jerojasro@336	1140
jerojasro@336	1141 Parameters to this hook:
jerojasro@336	1142 \begin{itemize}
jerojasro@336	1143 \item[\texttt{node}] A changeset ID. The changeset ID of the first
jerojasro@336	1144 changeset in the group that was added. All changesets between this
jerojasro@336	1145 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
jerojasro@336	1146 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
jerojasro@336	1147 \item[\texttt{source}] A string. The source of these changes. See
jerojasro@336	1148 section~\ref{sec:hook:sources} for details.
jerojasro@336	1149 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1150 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1151 \end{itemize}
jerojasro@336	1152
jerojasro@336	1153 See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
jerojasro@336	1154 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
jerojasro@336	1155 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
jerojasro@336	1156
jerojasro@336	1157 \subsection{\hook{commit}---after a new changeset is created}
jerojasro@336	1158 \label{sec:hook:commit}
jerojasro@336	1159
jerojasro@336	1160 This hook is run after a new changeset has been created.
jerojasro@336	1161
jerojasro@336	1162 Parameters to this hook:
jerojasro@336	1163 \begin{itemize}
jerojasro@336	1164 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
jerojasro@336	1165 committed changeset.
jerojasro@336	1166 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
jerojasro@336	1167 parent of the newly committed changeset.
jerojasro@336	1168 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
jerojasro@336	1169 parent of the newly committed changeset.
jerojasro@336	1170 \end{itemize}
jerojasro@336	1171
jerojasro@336	1172 See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
jerojasro@336	1173 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
jerojasro@336	1174
jerojasro@336	1175 \subsection{\hook{incoming}---after one remote changeset is added}
jerojasro@336	1176 \label{sec:hook:incoming}
jerojasro@336	1177
jerojasro@336	1178 This hook is run after a pre-existing changeset has been added to the
jerojasro@336	1179 repository, for example via a \hgcmd{push}. If a group of changesets
jerojasro@336	1180 was added in a single operation, this hook is called once for each
jerojasro@336	1181 added changeset.
jerojasro@336	1182
jerojasro@336	1183 You can use this hook for the same purposes as the \hook{changegroup}
jerojasro@336	1184 hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
jerojasro@336	1185 sometimes to run a hook once per group of changesets, while other
jerojasro@336	1186 times it's handier once per changeset.
jerojasro@336	1187
jerojasro@336	1188 Parameters to this hook:
jerojasro@336	1189 \begin{itemize}
jerojasro@336	1190 \item[\texttt{node}] A changeset ID. The ID of the newly added
jerojasro@336	1191 changeset.
jerojasro@336	1192 \item[\texttt{source}] A string. The source of these changes. See
jerojasro@336	1193 section~\ref{sec:hook:sources} for details.
jerojasro@336	1194 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1195 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1196 \end{itemize}
jerojasro@336	1197
jerojasro@336	1198 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	1199
jerojasro@336	1200 \subsection{\hook{outgoing}---after changesets are propagated}
jerojasro@336	1201 \label{sec:hook:outgoing}
jerojasro@336	1202
jerojasro@336	1203 This hook is run after a group of changesets has been propagated out
jerojasro@336	1204 of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
jerojasro@336	1205 command.
jerojasro@336	1206
jerojasro@336	1207 One possible use for this hook is to notify administrators that
jerojasro@336	1208 changes have been pulled.
jerojasro@336	1209
jerojasro@336	1210 Parameters to this hook:
jerojasro@336	1211 \begin{itemize}
jerojasro@336	1212 \item[\texttt{node}] A changeset ID. The changeset ID of the first
jerojasro@336	1213 changeset of the group that was sent.
jerojasro@336	1214 \item[\texttt{source}] A string. The source of the of the operation
jerojasro@336	1215 (see section~\ref{sec:hook:sources}). If a remote client pulled
jerojasro@336	1216 changes from this repository, \texttt{source} will be
jerojasro@336	1217 \texttt{serve}. If the client that obtained changes from this
jerojasro@336	1218 repository was local, \texttt{source} will be \texttt{bundle},
jerojasro@336	1219 \texttt{pull}, or \texttt{push}, depending on the operation the
jerojasro@336	1220 client performed.
jerojasro@336	1221 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1222 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1223 \end{itemize}
jerojasro@336	1224
jerojasro@336	1225 See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
jerojasro@336	1226
jerojasro@336	1227 \subsection{\hook{prechangegroup}---before starting to add remote changesets}
jerojasro@336	1228 \label{sec:hook:prechangegroup}
jerojasro@336	1229
jerojasro@336	1230 This controlling hook is run before Mercurial begins to add a group of
jerojasro@336	1231 changesets from another repository.
jerojasro@336	1232
jerojasro@336	1233 This hook does not have any information about the changesets to be
jerojasro@336	1234 added, because it is run before transmission of those changesets is
jerojasro@336	1235 allowed to begin. If this hook fails, the changesets will not be
jerojasro@336	1236 transmitted.
jerojasro@336	1237
jerojasro@336	1238 One use for this hook is to prevent external changes from being added
jerojasro@336	1239 to a repository. For example, you could use this to ``freeze'' a
jerojasro@336	1240 server-hosted branch temporarily or permanently so that users cannot
jerojasro@336	1241 push to it, while still allowing a local administrator to modify the
jerojasro@336	1242 repository.
jerojasro@336	1243
jerojasro@336	1244 Parameters to this hook:
jerojasro@336	1245 \begin{itemize}
jerojasro@336	1246 \item[\texttt{source}] A string. The source of these changes. See
jerojasro@336	1247 section~\ref{sec:hook:sources} for details.
jerojasro@336	1248 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1249 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1250 \end{itemize}
jerojasro@336	1251
jerojasro@336	1252 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
jerojasro@336	1253 \hook{incoming} (section~\ref{sec:hook:incoming}), ,
jerojasro@336	1254 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
jerojasro@336	1255
jerojasro@336	1256 \subsection{\hook{precommit}---before starting to commit a changeset}
jerojasro@336	1257 \label{sec:hook:precommit}
jerojasro@336	1258
jerojasro@336	1259 This hook is run before Mercurial begins to commit a new changeset.
jerojasro@336	1260 It is run before Mercurial has any of the metadata for the commit,
jerojasro@336	1261 such as the files to be committed, the commit message, or the commit
jerojasro@336	1262 date.
jerojasro@336	1263
jerojasro@336	1264 One use for this hook is to disable the ability to commit new
jerojasro@336	1265 changesets, while still allowing incoming changesets. Another is to
jerojasro@336	1266 run a build or test, and only allow the commit to begin if the build
jerojasro@336	1267 or test succeeds.
jerojasro@336	1268
jerojasro@336	1269 Parameters to this hook:
jerojasro@336	1270 \begin{itemize}
jerojasro@336	1271 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
jerojasro@336	1272 parent of the working directory.
jerojasro@336	1273 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
jerojasro@336	1274 parent of the working directory.
jerojasro@336	1275 \end{itemize}
jerojasro@336	1276 If the commit proceeds, the parents of the working directory will
jerojasro@336	1277 become the parents of the new changeset.
jerojasro@336	1278
jerojasro@336	1279 See also: \hook{commit} (section~\ref{sec:hook:commit}),
jerojasro@336	1280 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
jerojasro@336	1281
jerojasro@336	1282 \subsection{\hook{preoutgoing}---before starting to propagate changesets}
jerojasro@336	1283 \label{sec:hook:preoutgoing}
jerojasro@336	1284
jerojasro@336	1285 This hook is invoked before Mercurial knows the identities of the
jerojasro@336	1286 changesets to be transmitted.
jerojasro@336	1287
jerojasro@336	1288 One use for this hook is to prevent changes from being transmitted to
jerojasro@336	1289 another repository.
jerojasro@336	1290
jerojasro@336	1291 Parameters to this hook:
jerojasro@336	1292 \begin{itemize}
jerojasro@336	1293 \item[\texttt{source}] A string. The source of the operation that is
jerojasro@336	1294 attempting to obtain changes from this repository (see
jerojasro@336	1295 section~\ref{sec:hook:sources}). See the documentation for the
jerojasro@336	1296 \texttt{source} parameter to the \hook{outgoing} hook, in
jerojasro@336	1297 section~\ref{sec:hook:outgoing}, for possible values of this
jerojasro@336	1298 parameter.
jerojasro@336	1299 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1300 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1301 \end{itemize}
jerojasro@336	1302
jerojasro@336	1303 See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
jerojasro@336	1304
jerojasro@336	1305 \subsection{\hook{pretag}---before tagging a changeset}
jerojasro@336	1306 \label{sec:hook:pretag}
jerojasro@336	1307
jerojasro@336	1308 This controlling hook is run before a tag is created. If the hook
jerojasro@336	1309 succeeds, creation of the tag proceeds. If the hook fails, the tag is
jerojasro@336	1310 not created.
jerojasro@336	1311
jerojasro@336	1312 Parameters to this hook:
jerojasro@336	1313 \begin{itemize}
jerojasro@336	1314 \item[\texttt{local}] A boolean. Whether the tag is local to this
jerojasro@336	1315 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
jerojasro@336	1316 managed by Mercurial (stored in \sfilename{.hgtags}).
jerojasro@336	1317 \item[\texttt{node}] A changeset ID. The ID of the changeset to be tagged.
jerojasro@336	1318 \item[\texttt{tag}] A string. The name of the tag to be created.
jerojasro@336	1319 \end{itemize}
jerojasro@336	1320
jerojasro@336	1321 If the tag to be created is revision-controlled, the \hook{precommit}
jerojasro@336	1322 and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
jerojasro@336	1323 and~\ref{sec:hook:pretxncommit}) will also be run.
jerojasro@336	1324
jerojasro@336	1325 See also: \hook{tag} (section~\ref{sec:hook:tag})
jerojasro@336	1326
jerojasro@336	1327 \subsection{\hook{pretxnchangegroup}---before completing addition of
jerojasro@336	1328 remote changesets}
jerojasro@336	1329 \label{sec:hook:pretxnchangegroup}
jerojasro@336	1330
jerojasro@336	1331 This controlling hook is run before a transaction---that manages the
jerojasro@336	1332 addition of a group of new changesets from outside the
jerojasro@336	1333 repository---completes. If the hook succeeds, the transaction
jerojasro@336	1334 completes, and all of the changesets become permanent within this
jerojasro@336	1335 repository. If the hook fails, the transaction is rolled back, and
jerojasro@336	1336 the data for the changesets is erased.
jerojasro@336	1337
jerojasro@336	1338 This hook can access the metadata associated with the almost-added
jerojasro@336	1339 changesets, but it should not do anything permanent with this data.
jerojasro@336	1340 It must also not modify the working directory.
jerojasro@336	1341
jerojasro@336	1342 While this hook is running, if other Mercurial processes access this
jerojasro@336	1343 repository, they will be able to see the almost-added changesets as if
jerojasro@336	1344 they are permanent. This may lead to race conditions if you do not
jerojasro@336	1345 take steps to avoid them.
jerojasro@336	1346
jerojasro@336	1347 This hook can be used to automatically vet a group of changesets. If
jerojasro@336	1348 the hook fails, all of the changesets are ``rejected'' when the
jerojasro@336	1349 transaction rolls back.
jerojasro@336	1350
jerojasro@336	1351 Parameters to this hook:
jerojasro@336	1352 \begin{itemize}
jerojasro@336	1353 \item[\texttt{node}] A changeset ID. The changeset ID of the first
jerojasro@336	1354 changeset in the group that was added. All changesets between this
jerojasro@336	1355 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
jerojasro@336	1356 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
jerojasro@336	1357 \item[\texttt{source}] A string. The source of these changes. See
jerojasro@336	1358 section~\ref{sec:hook:sources} for details.
jerojasro@336	1359 \item[\texttt{url}] A URL. The location of the remote repository, if
jerojasro@336	1360 known. See section~\ref{sec:hook:url} for more information.
jerojasro@336	1361 \end{itemize}
jerojasro@336	1362
jerojasro@336	1363 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
jerojasro@336	1364 \hook{incoming} (section~\ref{sec:hook:incoming}),
jerojasro@336	1365 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
jerojasro@336	1366
jerojasro@336	1367 \subsection{\hook{pretxncommit}---before completing commit of new changeset}
jerojasro@336	1368 \label{sec:hook:pretxncommit}
jerojasro@336	1369
jerojasro@336	1370 This controlling hook is run before a transaction---that manages a new
jerojasro@336	1371 commit---completes. If the hook succeeds, the transaction completes
jerojasro@336	1372 and the changeset becomes permanent within this repository. If the
jerojasro@336	1373 hook fails, the transaction is rolled back, and the commit data is
jerojasro@336	1374 erased.
jerojasro@336	1375
jerojasro@336	1376 This hook can access the metadata associated with the almost-new
jerojasro@336	1377 changeset, but it should not do anything permanent with this data. It
jerojasro@336	1378 must also not modify the working directory.
jerojasro@336	1379
jerojasro@336	1380 While this hook is running, if other Mercurial processes access this
jerojasro@336	1381 repository, they will be able to see the almost-new changeset as if it
jerojasro@336	1382 is permanent. This may lead to race conditions if you do not take
jerojasro@336	1383 steps to avoid them.
jerojasro@336	1384
jerojasro@336	1385 Parameters to this hook:
jerojasro@336	1386 \begin{itemize}
jerojasro@336	1387 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
jerojasro@336	1388 committed changeset.
jerojasro@336	1389 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
jerojasro@336	1390 parent of the newly committed changeset.
jerojasro@336	1391 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
jerojasro@336	1392 parent of the newly committed changeset.
jerojasro@336	1393 \end{itemize}
jerojasro@336	1394
jerojasro@336	1395 See also: \hook{precommit} (section~\ref{sec:hook:precommit})
jerojasro@336	1396
jerojasro@336	1397 \subsection{\hook{preupdate}---before updating or merging working directory}
jerojasro@336	1398 \label{sec:hook:preupdate}
jerojasro@336	1399
jerojasro@336	1400 This controlling hook is run before an update or merge of the working
jerojasro@336	1401 directory begins. It is run only if Mercurial's normal pre-update
jerojasro@336	1402 checks determine that the update or merge can proceed. If the hook
jerojasro@336	1403 succeeds, the update or merge may proceed; if it fails, the update or
jerojasro@336	1404 merge does not start.
jerojasro@336	1405
jerojasro@336	1406 Parameters to this hook:
jerojasro@336	1407 \begin{itemize}
jerojasro@336	1408 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
jerojasro@336	1409 working directory is to be updated to. If the working directory is
jerojasro@336	1410 being merged, it will not change this parent.
jerojasro@336	1411 \item[\texttt{parent2}] A changeset ID. Only set if the working
jerojasro@336	1412 directory is being merged. The ID of the revision that the working
jerojasro@336	1413 directory is being merged with.
jerojasro@336	1414 \end{itemize}
jerojasro@336	1415
jerojasro@336	1416 See also: \hook{update} (section~\ref{sec:hook:update})
jerojasro@336	1417
jerojasro@336	1418 \subsection{\hook{tag}---after tagging a changeset}
jerojasro@336	1419 \label{sec:hook:tag}
jerojasro@336	1420
jerojasro@336	1421 This hook is run after a tag has been created.
jerojasro@336	1422
jerojasro@336	1423 Parameters to this hook:
jerojasro@336	1424 \begin{itemize}
jerojasro@336	1425 \item[\texttt{local}] A boolean. Whether the new tag is local to this
jerojasro@336	1426 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
jerojasro@336	1427 managed by Mercurial (stored in \sfilename{.hgtags}).
jerojasro@336	1428 \item[\texttt{node}] A changeset ID. The ID of the changeset that was
jerojasro@336	1429 tagged.
jerojasro@336	1430 \item[\texttt{tag}] A string. The name of the tag that was created.
jerojasro@336	1431 \end{itemize}
jerojasro@336	1432
jerojasro@336	1433 If the created tag is revision-controlled, the \hook{commit} hook
jerojasro@336	1434 (section~\ref{sec:hook:commit}) is run before this hook.
jerojasro@336	1435
jerojasro@336	1436 See also: \hook{pretag} (section~\ref{sec:hook:pretag})
jerojasro@336	1437
jerojasro@336	1438 \subsection{\hook{update}---after updating or merging working directory}
jerojasro@336	1439 \label{sec:hook:update}
jerojasro@336	1440
jerojasro@336	1441 This hook is run after an update or merge of the working directory
jerojasro@336	1442 completes. Since a merge can fail (if the external \command{hgmerge}
jerojasro@336	1443 command fails to resolve conflicts in a file), this hook communicates
jerojasro@336	1444 whether the update or merge completed cleanly.
jerojasro@336	1445
jerojasro@336	1446 \begin{itemize}
jerojasro@336	1447 \item[\texttt{error}] A boolean. Indicates whether the update or
jerojasro@336	1448 merge completed successfully.
jerojasro@336	1449 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
jerojasro@336	1450 working directory was updated to. If the working directory was
jerojasro@336	1451 merged, it will not have changed this parent.
jerojasro@336	1452 \item[\texttt{parent2}] A changeset ID. Only set if the working
jerojasro@336	1453 directory was merged. The ID of the revision that the working
jerojasro@336	1454 directory was merged with.
jerojasro@336	1455 \end{itemize}
jerojasro@336	1456
jerojasro@336	1457 See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
jerojasro@336	1458
jerojasro@336	1459 %%% Local Variables:
jerojasro@336	1460 %%% mode: latex
jerojasro@336	1461 %%% TeX-master: "00book"
jerojasro@336	1462 %%% End: