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