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@336
|
261 It is easy to write a Mercurial hook. Let's start with a hook that
|
jerojasro@336
|
262 runs when you finish a \hgcmd{commit}, and simply prints the hash of
|
jerojasro@336
|
263 the changeset you just created. The hook is called \hook{commit}.
|
jerojasro@336
|
264
|
jerojasro@336
|
265 \begin{figure}[ht]
|
jerojasro@336
|
266 \interaction{hook.simple.init}
|
jerojasro@336
|
267 \caption{A simple hook that runs when a changeset is committed}
|
jerojasro@336
|
268 \label{ex:hook:init}
|
jerojasro@336
|
269 \end{figure}
|
jerojasro@336
|
270
|
jerojasro@336
|
271 All hooks follow the pattern in example~\ref{ex:hook:init}. You add
|
jerojasro@336
|
272 an entry to the \rcsection{hooks} section of your \hgrc. On the left
|
jerojasro@336
|
273 is the name of the event to trigger on; on the right is the action to
|
jerojasro@336
|
274 take. As you can see, you can run an arbitrary shell command in a
|
jerojasro@336
|
275 hook. Mercurial passes extra information to the hook using
|
jerojasro@336
|
276 environment variables (look for \envar{HG\_NODE} in the example).
|
jerojasro@336
|
277
|
jerojasro@336
|
278 \subsection{Performing multiple actions per event}
|
jerojasro@336
|
279
|
jerojasro@336
|
280 Quite often, you will want to define more than one hook for a
|
jerojasro@336
|
281 particular kind of event, as shown in example~\ref{ex:hook:ext}.
|
jerojasro@336
|
282 Mercurial lets you do this by adding an \emph{extension} to the end of
|
jerojasro@336
|
283 a hook's name. You extend a hook's name by giving the name of the
|
jerojasro@336
|
284 hook, followed by a full stop (the ``\texttt{.}'' character), followed
|
jerojasro@336
|
285 by some more text of your choosing. For example, Mercurial will run
|
jerojasro@336
|
286 both \texttt{commit.foo} and \texttt{commit.bar} when the
|
jerojasro@336
|
287 \texttt{commit} event occurs.
|
jerojasro@336
|
288
|
jerojasro@336
|
289 \begin{figure}[ht]
|
jerojasro@336
|
290 \interaction{hook.simple.ext}
|
jerojasro@336
|
291 \caption{Defining a second \hook{commit} hook}
|
jerojasro@336
|
292 \label{ex:hook:ext}
|
jerojasro@336
|
293 \end{figure}
|
jerojasro@336
|
294
|
jerojasro@336
|
295 To give a well-defined order of execution when there are multiple
|
jerojasro@336
|
296 hooks defined for an event, Mercurial sorts hooks by extension, and
|
jerojasro@336
|
297 executes the hook commands in this sorted order. In the above
|
jerojasro@336
|
298 example, it will execute \texttt{commit.bar} before
|
jerojasro@336
|
299 \texttt{commit.foo}, and \texttt{commit} before both.
|
jerojasro@336
|
300
|
jerojasro@336
|
301 It is a good idea to use a somewhat descriptive extension when you
|
jerojasro@336
|
302 define a new hook. This will help you to remember what the hook was
|
jerojasro@336
|
303 for. If the hook fails, you'll get an error message that contains the
|
jerojasro@336
|
304 hook name and extension, so using a descriptive extension could give
|
jerojasro@336
|
305 you an immediate hint as to why the hook failed (see
|
jerojasro@336
|
306 section~\ref{sec:hook:perm} for an example).
|
jerojasro@336
|
307
|
jerojasro@336
|
308 \subsection{Controlling whether an activity can proceed}
|
jerojasro@336
|
309 \label{sec:hook:perm}
|
jerojasro@336
|
310
|
jerojasro@336
|
311 In our earlier examples, we used the \hook{commit} hook, which is
|
jerojasro@336
|
312 run after a commit has completed. This is one of several Mercurial
|
jerojasro@336
|
313 hooks that run after an activity finishes. Such hooks have no way of
|
jerojasro@336
|
314 influencing the activity itself.
|
jerojasro@336
|
315
|
jerojasro@336
|
316 Mercurial defines a number of events that occur before an activity
|
jerojasro@336
|
317 starts; or after it starts, but before it finishes. Hooks that
|
jerojasro@336
|
318 trigger on these events have the added ability to choose whether the
|
jerojasro@336
|
319 activity can continue, or will abort.
|
jerojasro@336
|
320
|
jerojasro@336
|
321 The \hook{pretxncommit} hook runs after a commit has all but
|
jerojasro@336
|
322 completed. In other words, the metadata representing the changeset
|
jerojasro@336
|
323 has been written out to disk, but the transaction has not yet been
|
jerojasro@336
|
324 allowed to complete. The \hook{pretxncommit} hook has the ability to
|
jerojasro@336
|
325 decide whether the transaction can complete, or must be rolled back.
|
jerojasro@336
|
326
|
jerojasro@336
|
327 If the \hook{pretxncommit} hook exits with a status code of zero, the
|
jerojasro@336
|
328 transaction is allowed to complete; the commit finishes; and the
|
jerojasro@336
|
329 \hook{commit} hook is run. If the \hook{pretxncommit} hook exits with
|
jerojasro@336
|
330 a non-zero status code, the transaction is rolled back; the metadata
|
jerojasro@336
|
331 representing the changeset is erased; and the \hook{commit} hook is
|
jerojasro@336
|
332 not run.
|
jerojasro@336
|
333
|
jerojasro@336
|
334 \begin{figure}[ht]
|
jerojasro@336
|
335 \interaction{hook.simple.pretxncommit}
|
jerojasro@336
|
336 \caption{Using the \hook{pretxncommit} hook to control commits}
|
jerojasro@336
|
337 \label{ex:hook:pretxncommit}
|
jerojasro@336
|
338 \end{figure}
|
jerojasro@336
|
339
|
jerojasro@336
|
340 The hook in example~\ref{ex:hook:pretxncommit} checks that a commit
|
jerojasro@336
|
341 comment contains a bug ID. If it does, the commit can complete. If
|
jerojasro@336
|
342 not, the commit is rolled back.
|
jerojasro@336
|
343
|
jerojasro@336
|
344 \section{Writing your own hooks}
|
jerojasro@336
|
345
|
jerojasro@336
|
346 When you are writing a hook, you might find it useful to run Mercurial
|
jerojasro@336
|
347 either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
|
jerojasro@336
|
348 item set to ``true''. When you do so, Mercurial will print a message
|
jerojasro@336
|
349 before it calls each hook.
|
jerojasro@336
|
350
|
jerojasro@336
|
351 \subsection{Choosing how your hook should run}
|
jerojasro@336
|
352 \label{sec:hook:lang}
|
jerojasro@336
|
353
|
jerojasro@336
|
354 You can write a hook either as a normal program---typically a shell
|
jerojasro@336
|
355 script---or as a Python function that is executed within the Mercurial
|
jerojasro@336
|
356 process.
|
jerojasro@336
|
357
|
jerojasro@336
|
358 Writing a hook as an external program has the advantage that it
|
jerojasro@336
|
359 requires no knowledge of Mercurial's internals. You can call normal
|
jerojasro@336
|
360 Mercurial commands to get any added information you need. The
|
jerojasro@336
|
361 trade-off is that external hooks are slower than in-process hooks.
|
jerojasro@336
|
362
|
jerojasro@336
|
363 An in-process Python hook has complete access to the Mercurial API,
|
jerojasro@336
|
364 and does not ``shell out'' to another process, so it is inherently
|
jerojasro@336
|
365 faster than an external hook. It is also easier to obtain much of the
|
jerojasro@336
|
366 information that a hook requires by using the Mercurial API than by
|
jerojasro@336
|
367 running Mercurial commands.
|
jerojasro@336
|
368
|
jerojasro@336
|
369 If you are comfortable with Python, or require high performance,
|
jerojasro@336
|
370 writing your hooks in Python may be a good choice. However, when you
|
jerojasro@336
|
371 have a straightforward hook to write and you don't need to care about
|
jerojasro@336
|
372 performance (probably the majority of hooks), a shell script is
|
jerojasro@336
|
373 perfectly fine.
|
jerojasro@336
|
374
|
jerojasro@336
|
375 \subsection{Hook parameters}
|
jerojasro@336
|
376 \label{sec:hook:param}
|
jerojasro@336
|
377
|
jerojasro@336
|
378 Mercurial calls each hook with a set of well-defined parameters. In
|
jerojasro@336
|
379 Python, a parameter is passed as a keyword argument to your hook
|
jerojasro@336
|
380 function. For an external program, a parameter is passed as an
|
jerojasro@336
|
381 environment variable.
|
jerojasro@336
|
382
|
jerojasro@336
|
383 Whether your hook is written in Python or as a shell script, the
|
jerojasro@336
|
384 hook-specific parameter names and values will be the same. A boolean
|
jerojasro@336
|
385 parameter will be represented as a boolean value in Python, but as the
|
jerojasro@336
|
386 number 1 (for ``true'') or 0 (for ``false'') as an environment
|
jerojasro@336
|
387 variable for an external hook. If a hook parameter is named
|
jerojasro@336
|
388 \texttt{foo}, the keyword argument for a Python hook will also be
|
jerojasro@336
|
389 named \texttt{foo}, while the environment variable for an external
|
jerojasro@336
|
390 hook will be named \texttt{HG\_FOO}.
|
jerojasro@336
|
391
|
jerojasro@336
|
392 \subsection{Hook return values and activity control}
|
jerojasro@336
|
393
|
jerojasro@336
|
394 A hook that executes successfully must exit with a status of zero if
|
jerojasro@336
|
395 external, or return boolean ``false'' if in-process. Failure is
|
jerojasro@336
|
396 indicated with a non-zero exit status from an external hook, or an
|
jerojasro@336
|
397 in-process hook returning boolean ``true''. If an in-process hook
|
jerojasro@336
|
398 raises an exception, the hook is considered to have failed.
|
jerojasro@336
|
399
|
jerojasro@336
|
400 For a hook that controls whether an activity can proceed, zero/false
|
jerojasro@336
|
401 means ``allow'', while non-zero/true/exception means ``deny''.
|
jerojasro@336
|
402
|
jerojasro@336
|
403 \subsection{Writing an external hook}
|
jerojasro@336
|
404
|
jerojasro@336
|
405 When you define an external hook in your \hgrc\ and the hook is run,
|
jerojasro@336
|
406 its value is passed to your shell, which interprets it. This means
|
jerojasro@336
|
407 that you can use normal shell constructs in the body of the hook.
|
jerojasro@336
|
408
|
jerojasro@336
|
409 An executable hook is always run with its current directory set to a
|
jerojasro@336
|
410 repository's root directory.
|
jerojasro@336
|
411
|
jerojasro@336
|
412 Each hook parameter is passed in as an environment variable; the name
|
jerojasro@336
|
413 is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
|
jerojasro@336
|
414
|
jerojasro@336
|
415 With the exception of hook parameters, Mercurial does not set or
|
jerojasro@336
|
416 modify any environment variables when running a hook. This is useful
|
jerojasro@336
|
417 to remember if you are writing a site-wide hook that may be run by a
|
jerojasro@336
|
418 number of different users with differing environment variables set.
|
jerojasro@336
|
419 In multi-user situations, you should not rely on environment variables
|
jerojasro@336
|
420 being set to the values you have in your environment when testing the
|
jerojasro@336
|
421 hook.
|
jerojasro@336
|
422
|
jerojasro@336
|
423 \subsection{Telling Mercurial to use an in-process hook}
|
jerojasro@336
|
424
|
jerojasro@336
|
425 The \hgrc\ syntax for defining an in-process hook is slightly
|
jerojasro@336
|
426 different than for an executable hook. The value of the hook must
|
jerojasro@336
|
427 start with the text ``\texttt{python:}'', and continue with the
|
jerojasro@336
|
428 fully-qualified name of a callable object to use as the hook's value.
|
jerojasro@336
|
429
|
jerojasro@336
|
430 The module in which a hook lives is automatically imported when a hook
|
jerojasro@336
|
431 is run. So long as you have the module name and \envar{PYTHONPATH}
|
jerojasro@336
|
432 right, it should ``just work''.
|
jerojasro@336
|
433
|
jerojasro@336
|
434 The following \hgrc\ example snippet illustrates the syntax and
|
jerojasro@336
|
435 meaning of the notions we just described.
|
jerojasro@336
|
436 \begin{codesample2}
|
jerojasro@336
|
437 [hooks]
|
jerojasro@336
|
438 commit.example = python:mymodule.submodule.myhook
|
jerojasro@336
|
439 \end{codesample2}
|
jerojasro@336
|
440 When Mercurial runs the \texttt{commit.example} hook, it imports
|
jerojasro@336
|
441 \texttt{mymodule.submodule}, looks for the callable object named
|
jerojasro@336
|
442 \texttt{myhook}, and calls it.
|
jerojasro@336
|
443
|
jerojasro@336
|
444 \subsection{Writing an in-process hook}
|
jerojasro@336
|
445
|
jerojasro@336
|
446 The simplest in-process hook does nothing, but illustrates the basic
|
jerojasro@336
|
447 shape of the hook API:
|
jerojasro@336
|
448 \begin{codesample2}
|
jerojasro@336
|
449 def myhook(ui, repo, **kwargs):
|
jerojasro@336
|
450 pass
|
jerojasro@336
|
451 \end{codesample2}
|
jerojasro@336
|
452 The first argument to a Python hook is always a
|
jerojasro@336
|
453 \pymodclass{mercurial.ui}{ui} object. The second is a repository object;
|
jerojasro@336
|
454 at the moment, it is always an instance of
|
jerojasro@336
|
455 \pymodclass{mercurial.localrepo}{localrepository}. Following these two
|
jerojasro@336
|
456 arguments are other keyword arguments. Which ones are passed in
|
jerojasro@336
|
457 depends on the hook being called, but a hook can ignore arguments it
|
jerojasro@336
|
458 doesn't care about by dropping them into a keyword argument dict, as
|
jerojasro@336
|
459 with \texttt{**kwargs} above.
|
jerojasro@336
|
460
|
jerojasro@336
|
461 \section{Some hook examples}
|
jerojasro@336
|
462
|
jerojasro@336
|
463 \subsection{Writing meaningful commit messages}
|
jerojasro@336
|
464
|
jerojasro@336
|
465 It's hard to imagine a useful commit message being very short. The
|
jerojasro@336
|
466 simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go}
|
jerojasro@336
|
467 will prevent you from committing a changeset with a message that is
|
jerojasro@336
|
468 less than ten bytes long.
|
jerojasro@336
|
469
|
jerojasro@336
|
470 \begin{figure}[ht]
|
jerojasro@336
|
471 \interaction{hook.msglen.go}
|
jerojasro@336
|
472 \caption{A hook that forbids overly short commit messages}
|
jerojasro@336
|
473 \label{ex:hook:msglen.go}
|
jerojasro@336
|
474 \end{figure}
|
jerojasro@336
|
475
|
jerojasro@336
|
476 \subsection{Checking for trailing whitespace}
|
jerojasro@336
|
477
|
jerojasro@336
|
478 An interesting use of a commit-related hook is to help you to write
|
jerojasro@336
|
479 cleaner code. A simple example of ``cleaner code'' is the dictum that
|
jerojasro@336
|
480 a change should not add any new lines of text that contain ``trailing
|
jerojasro@336
|
481 whitespace''. Trailing whitespace is a series of space and tab
|
jerojasro@336
|
482 characters at the end of a line of text. In most cases, trailing
|
jerojasro@336
|
483 whitespace is unnecessary, invisible noise, but it is occasionally
|
jerojasro@336
|
484 problematic, and people often prefer to get rid of it.
|
jerojasro@336
|
485
|
jerojasro@336
|
486 You can use either the \hook{precommit} or \hook{pretxncommit} hook to
|
jerojasro@336
|
487 tell whether you have a trailing whitespace problem. If you use the
|
jerojasro@336
|
488 \hook{precommit} hook, the hook will not know which files you are
|
jerojasro@336
|
489 committing, so it will have to check every modified file in the
|
jerojasro@336
|
490 repository for trailing white space. If you want to commit a change
|
jerojasro@336
|
491 to just the file \filename{foo}, but the file \filename{bar} contains
|
jerojasro@336
|
492 trailing whitespace, doing a check in the \hook{precommit} hook will
|
jerojasro@336
|
493 prevent you from committing \filename{foo} due to the problem with
|
jerojasro@336
|
494 \filename{bar}. This doesn't seem right.
|
jerojasro@336
|
495
|
jerojasro@336
|
496 Should you choose the \hook{pretxncommit} hook, the check won't occur
|
jerojasro@336
|
497 until just before the transaction for the commit completes. This will
|
jerojasro@336
|
498 allow you to check for problems only the exact files that are being
|
jerojasro@336
|
499 committed. However, if you entered the commit message interactively
|
jerojasro@336
|
500 and the hook fails, the transaction will roll back; you'll have to
|
jerojasro@336
|
501 re-enter the commit message after you fix the trailing whitespace and
|
jerojasro@336
|
502 run \hgcmd{commit} again.
|
jerojasro@336
|
503
|
jerojasro@336
|
504 \begin{figure}[ht]
|
jerojasro@336
|
505 \interaction{hook.ws.simple}
|
jerojasro@336
|
506 \caption{A simple hook that checks for trailing whitespace}
|
jerojasro@336
|
507 \label{ex:hook:ws.simple}
|
jerojasro@336
|
508 \end{figure}
|
jerojasro@336
|
509
|
jerojasro@336
|
510 Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
|
jerojasro@336
|
511 hook that checks for trailing whitespace. This hook is short, but not
|
jerojasro@336
|
512 very helpful. It exits with an error status if a change adds a line
|
jerojasro@336
|
513 with trailing whitespace to any file, but does not print any
|
jerojasro@336
|
514 information that might help us to identify the offending file or
|
jerojasro@336
|
515 line. It also has the nice property of not paying attention to
|
jerojasro@336
|
516 unmodified lines; only lines that introduce new trailing whitespace
|
jerojasro@336
|
517 cause problems.
|
jerojasro@336
|
518
|
jerojasro@336
|
519 \begin{figure}[ht]
|
jerojasro@336
|
520 \interaction{hook.ws.better}
|
jerojasro@336
|
521 \caption{A better trailing whitespace hook}
|
jerojasro@336
|
522 \label{ex:hook:ws.better}
|
jerojasro@336
|
523 \end{figure}
|
jerojasro@336
|
524
|
jerojasro@336
|
525 The example of figure~\ref{ex:hook:ws.better} is much more complex,
|
jerojasro@336
|
526 but also more useful. It parses a unified diff to see if any lines
|
jerojasro@336
|
527 add trailing whitespace, and prints the name of the file and the line
|
jerojasro@336
|
528 number of each such occurrence. Even better, if the change adds
|
jerojasro@336
|
529 trailing whitespace, this hook saves the commit comment and prints the
|
jerojasro@336
|
530 name of the save file before exiting and telling Mercurial to roll the
|
jerojasro@336
|
531 transaction back, so you can use
|
jerojasro@336
|
532 \hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
|
jerojasro@336
|
533 saved commit message once you've corrected the problem.
|
jerojasro@336
|
534
|
jerojasro@336
|
535 As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
|
jerojasro@336
|
536 \command{perl}'s in-place editing feature to get rid of trailing
|
jerojasro@336
|
537 whitespace from a file. This is concise and useful enough that I will
|
jerojasro@336
|
538 reproduce it here.
|
jerojasro@336
|
539 \begin{codesample2}
|
jerojasro@336
|
540 perl -pi -e 's,\\s+\$,,' filename
|
jerojasro@336
|
541 \end{codesample2}
|
jerojasro@336
|
542
|
jerojasro@336
|
543 \section{Bundled hooks}
|
jerojasro@336
|
544
|
jerojasro@336
|
545 Mercurial ships with several bundled hooks. You can find them in the
|
jerojasro@336
|
546 \dirname{hgext} directory of a Mercurial source tree. If you are
|
jerojasro@336
|
547 using a Mercurial binary package, the hooks will be located in the
|
jerojasro@336
|
548 \dirname{hgext} directory of wherever your package installer put
|
jerojasro@336
|
549 Mercurial.
|
jerojasro@336
|
550
|
jerojasro@336
|
551 \subsection{\hgext{acl}---access control for parts of a repository}
|
jerojasro@336
|
552
|
jerojasro@336
|
553 The \hgext{acl} extension lets you control which remote users are
|
jerojasro@336
|
554 allowed to push changesets to a networked server. You can protect any
|
jerojasro@336
|
555 portion of a repository (including the entire repo), so that a
|
jerojasro@336
|
556 specific remote user can push changes that do not affect the protected
|
jerojasro@336
|
557 portion.
|
jerojasro@336
|
558
|
jerojasro@336
|
559 This extension implements access control based on the identity of the
|
jerojasro@336
|
560 user performing a push, \emph{not} on who committed the changesets
|
jerojasro@336
|
561 they're pushing. It makes sense to use this hook only if you have a
|
jerojasro@336
|
562 locked-down server environment that authenticates remote users, and
|
jerojasro@336
|
563 you want to be sure that only specific users are allowed to push
|
jerojasro@336
|
564 changes to that server.
|
jerojasro@336
|
565
|
jerojasro@336
|
566 \subsubsection{Configuring the \hook{acl} hook}
|
jerojasro@336
|
567
|
jerojasro@336
|
568 In order to manage incoming changesets, the \hgext{acl} hook must be
|
jerojasro@336
|
569 used as a \hook{pretxnchangegroup} hook. This lets it see which files
|
jerojasro@336
|
570 are modified by each incoming changeset, and roll back a group of
|
jerojasro@336
|
571 changesets if they modify ``forbidden'' files. Example:
|
jerojasro@336
|
572 \begin{codesample2}
|
jerojasro@336
|
573 [hooks]
|
jerojasro@336
|
574 pretxnchangegroup.acl = python:hgext.acl.hook
|
jerojasro@336
|
575 \end{codesample2}
|
jerojasro@336
|
576
|
jerojasro@336
|
577 The \hgext{acl} extension is configured using three sections.
|
jerojasro@336
|
578
|
jerojasro@336
|
579 The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
|
jerojasro@336
|
580 which lists the sources of incoming changesets that the hook should
|
jerojasro@336
|
581 pay attention to. You don't normally need to configure this section.
|
jerojasro@336
|
582 \begin{itemize}
|
jerojasro@336
|
583 \item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
|
jerojasro@336
|
584 from a remote repository over http or ssh. This is the default
|
jerojasro@336
|
585 value of \rcitem{acl}{sources}, and usually the only setting you'll
|
jerojasro@336
|
586 need for this configuration item.
|
jerojasro@336
|
587 \item[\rcitem{acl}{pull}] Control incoming changesets that are
|
jerojasro@336
|
588 arriving via a pull from a local repository.
|
jerojasro@336
|
589 \item[\rcitem{acl}{push}] Control incoming changesets that are
|
jerojasro@336
|
590 arriving via a push from a local repository.
|
jerojasro@336
|
591 \item[\rcitem{acl}{bundle}] Control incoming changesets that are
|
jerojasro@336
|
592 arriving from another repository via a bundle.
|
jerojasro@336
|
593 \end{itemize}
|
jerojasro@336
|
594
|
jerojasro@336
|
595 The \rcsection{acl.allow} section controls the users that are allowed to
|
jerojasro@336
|
596 add changesets to the repository. If this section is not present, all
|
jerojasro@336
|
597 users that are not explicitly denied are allowed. If this section is
|
jerojasro@336
|
598 present, all users that are not explicitly allowed are denied (so an
|
jerojasro@336
|
599 empty section means that all users are denied).
|
jerojasro@336
|
600
|
jerojasro@336
|
601 The \rcsection{acl.deny} section determines which users are denied
|
jerojasro@336
|
602 from adding changesets to the repository. If this section is not
|
jerojasro@336
|
603 present or is empty, no users are denied.
|
jerojasro@336
|
604
|
jerojasro@336
|
605 The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
|
jerojasro@336
|
606 sections are identical. On the left of each entry is a glob pattern
|
jerojasro@336
|
607 that matches files or directories, relative to the root of the
|
jerojasro@336
|
608 repository; on the right, a user name.
|
jerojasro@336
|
609
|
jerojasro@336
|
610 In the following example, the user \texttt{docwriter} can only push
|
jerojasro@336
|
611 changes to the \dirname{docs} subtree of the repository, while
|
jerojasro@336
|
612 \texttt{intern} can push changes to any file or directory except
|
jerojasro@336
|
613 \dirname{source/sensitive}.
|
jerojasro@336
|
614 \begin{codesample2}
|
jerojasro@336
|
615 [acl.allow]
|
jerojasro@336
|
616 docs/** = docwriter
|
jerojasro@336
|
617
|
jerojasro@336
|
618 [acl.deny]
|
jerojasro@336
|
619 source/sensitive/** = intern
|
jerojasro@336
|
620 \end{codesample2}
|
jerojasro@336
|
621
|
jerojasro@336
|
622 \subsubsection{Testing and troubleshooting}
|
jerojasro@336
|
623
|
jerojasro@336
|
624 If you want to test the \hgext{acl} hook, run it with Mercurial's
|
jerojasro@336
|
625 debugging output enabled. Since you'll probably be running it on a
|
jerojasro@336
|
626 server where it's not convenient (or sometimes possible) to pass in
|
jerojasro@336
|
627 the \hggopt{--debug} option, don't forget that you can enable
|
jerojasro@336
|
628 debugging output in your \hgrc:
|
jerojasro@336
|
629 \begin{codesample2}
|
jerojasro@336
|
630 [ui]
|
jerojasro@336
|
631 debug = true
|
jerojasro@336
|
632 \end{codesample2}
|
jerojasro@336
|
633 With this enabled, the \hgext{acl} hook will print enough information
|
jerojasro@336
|
634 to let you figure out why it is allowing or forbidding pushes from
|
jerojasro@336
|
635 specific users.
|
jerojasro@336
|
636
|
jerojasro@336
|
637 \subsection{\hgext{bugzilla}---integration with Bugzilla}
|
jerojasro@336
|
638
|
jerojasro@336
|
639 The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
|
jerojasro@336
|
640 whenever it finds a reference to that bug ID in a commit comment. You
|
jerojasro@336
|
641 can install this hook on a shared server, so that any time a remote
|
jerojasro@336
|
642 user pushes changes to this server, the hook gets run.
|
jerojasro@336
|
643
|
jerojasro@336
|
644 It adds a comment to the bug that looks like this (you can configure
|
jerojasro@336
|
645 the contents of the comment---see below):
|
jerojasro@336
|
646 \begin{codesample2}
|
jerojasro@336
|
647 Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
|
jerojasro@336
|
648 the frobnitz repository, refers to this bug.
|
jerojasro@336
|
649
|
jerojasro@336
|
650 For complete details, see
|
jerojasro@336
|
651 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
|
jerojasro@336
|
652
|
jerojasro@336
|
653 Changeset description:
|
jerojasro@336
|
654 Fix bug 10483 by guarding against some NULL pointers
|
jerojasro@336
|
655 \end{codesample2}
|
jerojasro@336
|
656 The value of this hook is that it automates the process of updating a
|
jerojasro@336
|
657 bug any time a changeset refers to it. If you configure the hook
|
jerojasro@336
|
658 properly, it makes it easy for people to browse straight from a
|
jerojasro@336
|
659 Bugzilla bug to a changeset that refers to that bug.
|
jerojasro@336
|
660
|
jerojasro@336
|
661 You can use the code in this hook as a starting point for some more
|
jerojasro@336
|
662 exotic Bugzilla integration recipes. Here are a few possibilities:
|
jerojasro@336
|
663 \begin{itemize}
|
jerojasro@336
|
664 \item Require that every changeset pushed to the server have a valid
|
jerojasro@336
|
665 bug~ID in its commit comment. In this case, you'd want to configure
|
jerojasro@336
|
666 the hook as a \hook{pretxncommit} hook. This would allow the hook
|
jerojasro@336
|
667 to reject changes that didn't contain bug IDs.
|
jerojasro@336
|
668 \item Allow incoming changesets to automatically modify the
|
jerojasro@336
|
669 \emph{state} of a bug, as well as simply adding a comment. For
|
jerojasro@336
|
670 example, the hook could recognise the string ``fixed bug 31337'' as
|
jerojasro@336
|
671 indicating that it should update the state of bug 31337 to
|
jerojasro@336
|
672 ``requires testing''.
|
jerojasro@336
|
673 \end{itemize}
|
jerojasro@336
|
674
|
jerojasro@336
|
675 \subsubsection{Configuring the \hook{bugzilla} hook}
|
jerojasro@336
|
676 \label{sec:hook:bugzilla:config}
|
jerojasro@336
|
677
|
jerojasro@336
|
678 You should configure this hook in your server's \hgrc\ as an
|
jerojasro@336
|
679 \hook{incoming} hook, for example as follows:
|
jerojasro@336
|
680 \begin{codesample2}
|
jerojasro@336
|
681 [hooks]
|
jerojasro@336
|
682 incoming.bugzilla = python:hgext.bugzilla.hook
|
jerojasro@336
|
683 \end{codesample2}
|
jerojasro@336
|
684
|
jerojasro@336
|
685 Because of the specialised nature of this hook, and because Bugzilla
|
jerojasro@336
|
686 was not written with this kind of integration in mind, configuring
|
jerojasro@336
|
687 this hook is a somewhat involved process.
|
jerojasro@336
|
688
|
jerojasro@336
|
689 Before you begin, you must install the MySQL bindings for Python on
|
jerojasro@336
|
690 the host(s) where you'll be running the hook. If this is not
|
jerojasro@336
|
691 available as a binary package for your system, you can download it
|
jerojasro@336
|
692 from~\cite{web:mysql-python}.
|
jerojasro@336
|
693
|
jerojasro@336
|
694 Configuration information for this hook lives in the
|
jerojasro@336
|
695 \rcsection{bugzilla} section of your \hgrc.
|
jerojasro@336
|
696 \begin{itemize}
|
jerojasro@336
|
697 \item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
|
jerojasro@336
|
698 the server. The database schema that Bugzilla uses changes
|
jerojasro@336
|
699 occasionally, so this hook has to know exactly which schema to use.
|
jerojasro@336
|
700 At the moment, the only version supported is \texttt{2.16}.
|
jerojasro@336
|
701 \item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
|
jerojasro@336
|
702 stores your Bugzilla data. The database must be configured to allow
|
jerojasro@336
|
703 connections from whatever host you are running the \hook{bugzilla}
|
jerojasro@336
|
704 hook on.
|
jerojasro@336
|
705 \item[\rcitem{bugzilla}{user}] The username with which to connect to
|
jerojasro@336
|
706 the MySQL server. The database must be configured to allow this
|
jerojasro@336
|
707 user to connect from whatever host you are running the
|
jerojasro@336
|
708 \hook{bugzilla} hook on. This user must be able to access and
|
jerojasro@336
|
709 modify Bugzilla tables. The default value of this item is
|
jerojasro@336
|
710 \texttt{bugs}, which is the standard name of the Bugzilla user in a
|
jerojasro@336
|
711 MySQL database.
|
jerojasro@336
|
712 \item[\rcitem{bugzilla}{password}] The MySQL password for the user you
|
jerojasro@336
|
713 configured above. This is stored as plain text, so you should make
|
jerojasro@336
|
714 sure that unauthorised users cannot read the \hgrc\ file where you
|
jerojasro@336
|
715 store this information.
|
jerojasro@336
|
716 \item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
|
jerojasro@336
|
717 MySQL server. The default value of this item is \texttt{bugs},
|
jerojasro@336
|
718 which is the standard name of the MySQL database where Bugzilla
|
jerojasro@336
|
719 stores its data.
|
jerojasro@336
|
720 \item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
|
jerojasro@336
|
721 notification email to subscribers after this hook has added a
|
jerojasro@336
|
722 comment to a bug, you will need this hook to run a command whenever
|
jerojasro@336
|
723 it updates the database. The command to run depends on where you
|
jerojasro@336
|
724 have installed Bugzilla, but it will typically look something like
|
jerojasro@336
|
725 this, if you have Bugzilla installed in
|
jerojasro@336
|
726 \dirname{/var/www/html/bugzilla}:
|
jerojasro@336
|
727 \begin{codesample4}
|
jerojasro@336
|
728 cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
|
jerojasro@336
|
729 \end{codesample4}
|
jerojasro@336
|
730 The Bugzilla \texttt{processmail} program expects to be given a
|
jerojasro@336
|
731 bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
|
jerojasro@336
|
732 email address. It also expects to be able to write to some files in
|
jerojasro@336
|
733 the directory that it runs in. If Bugzilla and this hook are not
|
jerojasro@336
|
734 installed on the same machine, you will need to find a way to run
|
jerojasro@336
|
735 \texttt{processmail} on the server where Bugzilla is installed.
|
jerojasro@336
|
736 \end{itemize}
|
jerojasro@336
|
737
|
jerojasro@336
|
738 \subsubsection{Mapping committer names to Bugzilla user names}
|
jerojasro@336
|
739
|
jerojasro@336
|
740 By default, the \hgext{bugzilla} hook tries to use the email address
|
jerojasro@336
|
741 of a changeset's committer as the Bugzilla user name with which to
|
jerojasro@336
|
742 update a bug. If this does not suit your needs, you can map committer
|
jerojasro@336
|
743 email addresses to Bugzilla user names using a \rcsection{usermap}
|
jerojasro@336
|
744 section.
|
jerojasro@336
|
745
|
jerojasro@336
|
746 Each item in the \rcsection{usermap} section contains an email address
|
jerojasro@336
|
747 on the left, and a Bugzilla user name on the right.
|
jerojasro@336
|
748 \begin{codesample2}
|
jerojasro@336
|
749 [usermap]
|
jerojasro@336
|
750 jane.user@example.com = jane
|
jerojasro@336
|
751 \end{codesample2}
|
jerojasro@336
|
752 You can either keep the \rcsection{usermap} data in a normal \hgrc, or
|
jerojasro@336
|
753 tell the \hgext{bugzilla} hook to read the information from an
|
jerojasro@336
|
754 external \filename{usermap} file. In the latter case, you can store
|
jerojasro@336
|
755 \filename{usermap} data by itself in (for example) a user-modifiable
|
jerojasro@336
|
756 repository. This makes it possible to let your users maintain their
|
jerojasro@336
|
757 own \rcitem{bugzilla}{usermap} entries. The main \hgrc\ file might
|
jerojasro@336
|
758 look like this:
|
jerojasro@336
|
759 \begin{codesample2}
|
jerojasro@336
|
760 # regular hgrc file refers to external usermap file
|
jerojasro@336
|
761 [bugzilla]
|
jerojasro@336
|
762 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
|
jerojasro@336
|
763 \end{codesample2}
|
jerojasro@336
|
764 While the \filename{usermap} file that it refers to might look like
|
jerojasro@336
|
765 this:
|
jerojasro@336
|
766 \begin{codesample2}
|
jerojasro@336
|
767 # bugzilla-usermap.conf - inside a hg repository
|
jerojasro@336
|
768 [usermap]
|
jerojasro@336
|
769 stephanie@example.com = steph
|
jerojasro@336
|
770 \end{codesample2}
|
jerojasro@336
|
771
|
jerojasro@336
|
772 \subsubsection{Configuring the text that gets added to a bug}
|
jerojasro@336
|
773
|
jerojasro@336
|
774 You can configure the text that this hook adds as a comment; you
|
jerojasro@336
|
775 specify it in the form of a Mercurial template. Several \hgrc\
|
jerojasro@336
|
776 entries (still in the \rcsection{bugzilla} section) control this
|
jerojasro@336
|
777 behaviour.
|
jerojasro@336
|
778 \begin{itemize}
|
jerojasro@336
|
779 \item[\texttt{strip}] The number of leading path elements to strip
|
jerojasro@336
|
780 from a repository's path name to construct a partial path for a URL.
|
jerojasro@336
|
781 For example, if the repositories on your server live under
|
jerojasro@336
|
782 \dirname{/home/hg/repos}, and you have a repository whose path is
|
jerojasro@336
|
783 \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
|
jerojasro@336
|
784 \texttt{4} will give a partial path of \dirname{app/tests}. The
|
jerojasro@336
|
785 hook will make this partial path available when expanding a
|
jerojasro@336
|
786 template, as \texttt{webroot}.
|
jerojasro@336
|
787 \item[\texttt{template}] The text of the template to use. In addition
|
jerojasro@336
|
788 to the usual changeset-related variables, this template can use
|
jerojasro@336
|
789 \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
|
jerojasro@336
|
790 above) and \texttt{webroot} (the path constructed using
|
jerojasro@336
|
791 \texttt{strip} above).
|
jerojasro@336
|
792 \end{itemize}
|
jerojasro@336
|
793
|
jerojasro@336
|
794 In addition, you can add a \rcitem{web}{baseurl} item to the
|
jerojasro@336
|
795 \rcsection{web} section of your \hgrc. The \hgext{bugzilla} hook will
|
jerojasro@336
|
796 make this available when expanding a template, as the base string to
|
jerojasro@336
|
797 use when constructing a URL that will let users browse from a Bugzilla
|
jerojasro@336
|
798 comment to view a changeset. Example:
|
jerojasro@336
|
799 \begin{codesample2}
|
jerojasro@336
|
800 [web]
|
jerojasro@336
|
801 baseurl = http://hg.domain.com/
|
jerojasro@336
|
802 \end{codesample2}
|
jerojasro@336
|
803
|
jerojasro@336
|
804 Here is an example set of \hgext{bugzilla} hook config information.
|
jerojasro@336
|
805 \begin{codesample2}
|
jerojasro@336
|
806 [bugzilla]
|
jerojasro@336
|
807 host = bugzilla.example.com
|
jerojasro@336
|
808 password = mypassword
|
jerojasro@336
|
809 version = 2.16
|
jerojasro@336
|
810 # server-side repos live in /home/hg/repos, so strip 4 leading
|
jerojasro@336
|
811 # separators
|
jerojasro@336
|
812 strip = 4
|
jerojasro@336
|
813 hgweb = http://hg.example.com/
|
jerojasro@336
|
814 usermap = /home/hg/repos/notify/bugzilla.conf
|
jerojasro@336
|
815 template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
|
jerojasro@336
|
816 repo, refers to this bug.\\nFor complete details, see
|
jerojasro@336
|
817 \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
|
jerojasro@336
|
818 description:\\n\\t\{desc|tabindent\}
|
jerojasro@336
|
819 \end{codesample2}
|
jerojasro@336
|
820
|
jerojasro@336
|
821 \subsubsection{Testing and troubleshooting}
|
jerojasro@336
|
822
|
jerojasro@336
|
823 The most common problems with configuring the \hgext{bugzilla} hook
|
jerojasro@336
|
824 relate to running Bugzilla's \filename{processmail} script and mapping
|
jerojasro@336
|
825 committer names to user names.
|
jerojasro@336
|
826
|
jerojasro@336
|
827 Recall from section~\ref{sec:hook:bugzilla:config} above that the user
|
jerojasro@336
|
828 that runs the Mercurial process on the server is also the one that
|
jerojasro@336
|
829 will run the \filename{processmail} script. The
|
jerojasro@336
|
830 \filename{processmail} script sometimes causes Bugzilla to write to
|
jerojasro@336
|
831 files in its configuration directory, and Bugzilla's configuration
|
jerojasro@336
|
832 files are usually owned by the user that your web server runs under.
|
jerojasro@336
|
833
|
jerojasro@336
|
834 You can cause \filename{processmail} to be run with the suitable
|
jerojasro@336
|
835 user's identity using the \command{sudo} command. Here is an example
|
jerojasro@336
|
836 entry for a \filename{sudoers} file.
|
jerojasro@336
|
837 \begin{codesample2}
|
jerojasro@336
|
838 hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
|
jerojasro@336
|
839 \end{codesample2}
|
jerojasro@336
|
840 This allows the \texttt{hg\_user} user to run a
|
jerojasro@336
|
841 \filename{processmail-wrapper} program under the identity of
|
jerojasro@336
|
842 \texttt{httpd\_user}.
|
jerojasro@336
|
843
|
jerojasro@336
|
844 This indirection through a wrapper script is necessary, because
|
jerojasro@336
|
845 \filename{processmail} expects to be run with its current directory
|
jerojasro@336
|
846 set to wherever you installed Bugzilla; you can't specify that kind of
|
jerojasro@336
|
847 constraint in a \filename{sudoers} file. The contents of the wrapper
|
jerojasro@336
|
848 script are simple:
|
jerojasro@336
|
849 \begin{codesample2}
|
jerojasro@336
|
850 #!/bin/sh
|
jerojasro@336
|
851 cd `dirname $0` && ./processmail "$1" nobody@example.com
|
jerojasro@336
|
852 \end{codesample2}
|
jerojasro@336
|
853 It doesn't seem to matter what email address you pass to
|
jerojasro@336
|
854 \filename{processmail}.
|
jerojasro@336
|
855
|
jerojasro@336
|
856 If your \rcsection{usermap} is not set up correctly, users will see an
|
jerojasro@336
|
857 error message from the \hgext{bugzilla} hook when they push changes
|
jerojasro@336
|
858 to the server. The error message will look like this:
|
jerojasro@336
|
859 \begin{codesample2}
|
jerojasro@336
|
860 cannot find bugzilla user id for john.q.public@example.com
|
jerojasro@336
|
861 \end{codesample2}
|
jerojasro@336
|
862 What this means is that the committer's address,
|
jerojasro@336
|
863 \texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
|
jerojasro@336
|
864 nor does it have an entry in your \rcsection{usermap} that maps it to
|
jerojasro@336
|
865 a valid Bugzilla user name.
|
jerojasro@336
|
866
|
jerojasro@336
|
867 \subsection{\hgext{notify}---send email notifications}
|
jerojasro@336
|
868
|
jerojasro@336
|
869 Although Mercurial's built-in web server provides RSS feeds of changes
|
jerojasro@336
|
870 in every repository, many people prefer to receive change
|
jerojasro@336
|
871 notifications via email. The \hgext{notify} hook lets you send out
|
jerojasro@336
|
872 notifications to a set of email addresses whenever changesets arrive
|
jerojasro@336
|
873 that those subscribers are interested in.
|
jerojasro@336
|
874
|
jerojasro@336
|
875 As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
|
jerojasro@336
|
876 template-driven, so you can customise the contents of the notification
|
jerojasro@336
|
877 messages that it sends.
|
jerojasro@336
|
878
|
jerojasro@336
|
879 By default, the \hgext{notify} hook includes a diff of every changeset
|
jerojasro@336
|
880 that it sends out; you can limit the size of the diff, or turn this
|
jerojasro@336
|
881 feature off entirely. It is useful for letting subscribers review
|
jerojasro@336
|
882 changes immediately, rather than clicking to follow a URL.
|
jerojasro@336
|
883
|
jerojasro@336
|
884 \subsubsection{Configuring the \hgext{notify} hook}
|
jerojasro@336
|
885
|
jerojasro@336
|
886 You can set up the \hgext{notify} hook to send one email message per
|
jerojasro@336
|
887 incoming changeset, or one per incoming group of changesets (all those
|
jerojasro@336
|
888 that arrived in a single pull or push).
|
jerojasro@336
|
889 \begin{codesample2}
|
jerojasro@336
|
890 [hooks]
|
jerojasro@336
|
891 # send one email per group of changes
|
jerojasro@336
|
892 changegroup.notify = python:hgext.notify.hook
|
jerojasro@336
|
893 # send one email per change
|
jerojasro@336
|
894 incoming.notify = python:hgext.notify.hook
|
jerojasro@336
|
895 \end{codesample2}
|
jerojasro@336
|
896
|
jerojasro@336
|
897 Configuration information for this hook lives in the
|
jerojasro@336
|
898 \rcsection{notify} section of a \hgrc\ file.
|
jerojasro@336
|
899 \begin{itemize}
|
jerojasro@336
|
900 \item[\rcitem{notify}{test}] By default, this hook does not send out
|
jerojasro@336
|
901 email at all; instead, it prints the message that it \emph{would}
|
jerojasro@336
|
902 send. Set this item to \texttt{false} to allow email to be sent.
|
jerojasro@336
|
903 The reason that sending of email is turned off by default is that it
|
jerojasro@336
|
904 takes several tries to configure this extension exactly as you would
|
jerojasro@336
|
905 like, and it would be bad form to spam subscribers with a number of
|
jerojasro@336
|
906 ``broken'' notifications while you debug your configuration.
|
jerojasro@336
|
907 \item[\rcitem{notify}{config}] The path to a configuration file that
|
jerojasro@336
|
908 contains subscription information. This is kept separate from the
|
jerojasro@336
|
909 main \hgrc\ so that you can maintain it in a repository of its own.
|
jerojasro@336
|
910 People can then clone that repository, update their subscriptions,
|
jerojasro@336
|
911 and push the changes back to your server.
|
jerojasro@336
|
912 \item[\rcitem{notify}{strip}] The number of leading path separator
|
jerojasro@336
|
913 characters to strip from a repository's path, when deciding whether
|
jerojasro@336
|
914 a repository has subscribers. For example, if the repositories on
|
jerojasro@336
|
915 your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
|
jerojasro@336
|
916 considering a repository named \dirname{/home/hg/repos/shared/test},
|
jerojasro@336
|
917 setting \rcitem{notify}{strip} to \texttt{4} will cause
|
jerojasro@336
|
918 \hgext{notify} to trim the path it considers down to
|
jerojasro@336
|
919 \dirname{shared/test}, and it will match subscribers against that.
|
jerojasro@336
|
920 \item[\rcitem{notify}{template}] The template text to use when sending
|
jerojasro@336
|
921 messages. This specifies both the contents of the message header
|
jerojasro@336
|
922 and its body.
|
jerojasro@336
|
923 \item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
|
jerojasro@336
|
924 data to append to the end of a message. If a diff is longer than
|
jerojasro@336
|
925 this, it is truncated. By default, this is set to 300. Set this to
|
jerojasro@336
|
926 \texttt{0} to omit diffs from notification emails.
|
jerojasro@336
|
927 \item[\rcitem{notify}{sources}] A list of sources of changesets to
|
jerojasro@336
|
928 consider. This lets you limit \hgext{notify} to only sending out
|
jerojasro@336
|
929 email about changes that remote users pushed into this repository
|
jerojasro@336
|
930 via a server, for example. See section~\ref{sec:hook:sources} for
|
jerojasro@336
|
931 the sources you can specify here.
|
jerojasro@336
|
932 \end{itemize}
|
jerojasro@336
|
933
|
jerojasro@336
|
934 If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
|
jerojasro@336
|
935 section, you can use it in a template; it will be available as
|
jerojasro@336
|
936 \texttt{webroot}.
|
jerojasro@336
|
937
|
jerojasro@336
|
938 Here is an example set of \hgext{notify} configuration information.
|
jerojasro@336
|
939 \begin{codesample2}
|
jerojasro@336
|
940 [notify]
|
jerojasro@336
|
941 # really send email
|
jerojasro@336
|
942 test = false
|
jerojasro@336
|
943 # subscriber data lives in the notify repo
|
jerojasro@336
|
944 config = /home/hg/repos/notify/notify.conf
|
jerojasro@336
|
945 # repos live in /home/hg/repos on server, so strip 4 "/" chars
|
jerojasro@336
|
946 strip = 4
|
jerojasro@336
|
947 template = X-Hg-Repo: \{webroot\}
|
jerojasro@336
|
948 Subject: \{webroot\}: \{desc|firstline|strip\}
|
jerojasro@336
|
949 From: \{author\}
|
jerojasro@336
|
950
|
jerojasro@336
|
951 changeset \{node|short\} in \{root\}
|
jerojasro@336
|
952 details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
|
jerojasro@336
|
953 description:
|
jerojasro@336
|
954 \{desc|tabindent|strip\}
|
jerojasro@336
|
955
|
jerojasro@336
|
956 [web]
|
jerojasro@336
|
957 baseurl = http://hg.example.com/
|
jerojasro@336
|
958 \end{codesample2}
|
jerojasro@336
|
959
|
jerojasro@336
|
960 This will produce a message that looks like the following:
|
jerojasro@336
|
961 \begin{codesample2}
|
jerojasro@336
|
962 X-Hg-Repo: tests/slave
|
jerojasro@336
|
963 Subject: tests/slave: Handle error case when slave has no buffers
|
jerojasro@336
|
964 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
|
jerojasro@336
|
965
|
jerojasro@336
|
966 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
|
jerojasro@336
|
967 details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
|
jerojasro@336
|
968 description:
|
jerojasro@336
|
969 Handle error case when slave has no buffers
|
jerojasro@336
|
970 diffs (54 lines):
|
jerojasro@336
|
971
|
jerojasro@336
|
972 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
|
jerojasro@336
|
973 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
|
jerojasro@336
|
974 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
|
jerojasro@336
|
975 @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
|
jerojasro@336
|
976 [...snip...]
|
jerojasro@336
|
977 \end{codesample2}
|
jerojasro@336
|
978
|
jerojasro@336
|
979 \subsubsection{Testing and troubleshooting}
|
jerojasro@336
|
980
|
jerojasro@336
|
981 Do not forget that by default, the \hgext{notify} extension \emph{will
|
jerojasro@336
|
982 not send any mail} until you explicitly configure it to do so, by
|
jerojasro@336
|
983 setting \rcitem{notify}{test} to \texttt{false}. Until you do that,
|
jerojasro@336
|
984 it simply prints the message it \emph{would} send.
|
jerojasro@336
|
985
|
jerojasro@336
|
986 \section{Information for writers of hooks}
|
jerojasro@336
|
987 \label{sec:hook:ref}
|
jerojasro@336
|
988
|
jerojasro@336
|
989 \subsection{In-process hook execution}
|
jerojasro@336
|
990
|
jerojasro@336
|
991 An in-process hook is called with arguments of the following form:
|
jerojasro@336
|
992 \begin{codesample2}
|
jerojasro@336
|
993 def myhook(ui, repo, **kwargs):
|
jerojasro@336
|
994 pass
|
jerojasro@336
|
995 \end{codesample2}
|
jerojasro@336
|
996 The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
|
jerojasro@336
|
997 The \texttt{repo} parameter is a
|
jerojasro@336
|
998 \pymodclass{mercurial.localrepo}{localrepository} object. The
|
jerojasro@336
|
999 names and values of the \texttt{**kwargs} parameters depend on the
|
jerojasro@336
|
1000 hook being invoked, with the following common features:
|
jerojasro@336
|
1001 \begin{itemize}
|
jerojasro@336
|
1002 \item If a parameter is named \texttt{node} or
|
jerojasro@336
|
1003 \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
|
jerojasro@336
|
1004 The empty string is used to represent ``null changeset ID'' instead
|
jerojasro@336
|
1005 of a string of zeroes.
|
jerojasro@336
|
1006 \item If a parameter is named \texttt{url}, it will contain the URL of
|
jerojasro@336
|
1007 a remote repository, if that can be determined.
|
jerojasro@336
|
1008 \item Boolean-valued parameters are represented as Python
|
jerojasro@336
|
1009 \texttt{bool} objects.
|
jerojasro@336
|
1010 \end{itemize}
|
jerojasro@336
|
1011
|
jerojasro@336
|
1012 An in-process hook is called without a change to the process's working
|
jerojasro@336
|
1013 directory (unlike external hooks, which are run in the root of the
|
jerojasro@336
|
1014 repository). It must not change the process's working directory, or
|
jerojasro@336
|
1015 it will cause any calls it makes into the Mercurial API to fail.
|
jerojasro@336
|
1016
|
jerojasro@336
|
1017 If a hook returns a boolean ``false'' value, it is considered to have
|
jerojasro@336
|
1018 succeeded. If it returns a boolean ``true'' value or raises an
|
jerojasro@336
|
1019 exception, it is considered to have failed. A useful way to think of
|
jerojasro@336
|
1020 the calling convention is ``tell me if you fail''.
|
jerojasro@336
|
1021
|
jerojasro@336
|
1022 Note that changeset IDs are passed into Python hooks as hexadecimal
|
jerojasro@336
|
1023 strings, not the binary hashes that Mercurial's APIs normally use. To
|
jerojasro@336
|
1024 convert a hash from hex to binary, use the
|
jerojasro@336
|
1025 \pymodfunc{mercurial.node}{bin} function.
|
jerojasro@336
|
1026
|
jerojasro@336
|
1027 \subsection{External hook execution}
|
jerojasro@336
|
1028
|
jerojasro@336
|
1029 An external hook is passed to the shell of the user running Mercurial.
|
jerojasro@336
|
1030 Features of that shell, such as variable substitution and command
|
jerojasro@336
|
1031 redirection, are available. The hook is run in the root directory of
|
jerojasro@336
|
1032 the repository (unlike in-process hooks, which are run in the same
|
jerojasro@336
|
1033 directory that Mercurial was run in).
|
jerojasro@336
|
1034
|
jerojasro@336
|
1035 Hook parameters are passed to the hook as environment variables. Each
|
jerojasro@336
|
1036 environment variable's name is converted in upper case and prefixed
|
jerojasro@336
|
1037 with the string ``\texttt{HG\_}''. For example, if the name of a
|
jerojasro@336
|
1038 parameter is ``\texttt{node}'', the name of the environment variable
|
jerojasro@336
|
1039 representing that parameter will be ``\texttt{HG\_NODE}''.
|
jerojasro@336
|
1040
|
jerojasro@336
|
1041 A boolean parameter is represented as the string ``\texttt{1}'' for
|
jerojasro@336
|
1042 ``true'', ``\texttt{0}'' for ``false''. If an environment variable is
|
jerojasro@336
|
1043 named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
|
jerojasro@336
|
1044 contains a changeset ID represented as a hexadecimal string. The
|
jerojasro@336
|
1045 empty string is used to represent ``null changeset ID'' instead of a
|
jerojasro@336
|
1046 string of zeroes. If an environment variable is named
|
jerojasro@336
|
1047 \envar{HG\_URL}, it will contain the URL of a remote repository, if
|
jerojasro@336
|
1048 that can be determined.
|
jerojasro@336
|
1049
|
jerojasro@336
|
1050 If a hook exits with a status of zero, it is considered to have
|
jerojasro@336
|
1051 succeeded. If it exits with a non-zero status, it is considered to
|
jerojasro@336
|
1052 have failed.
|
jerojasro@336
|
1053
|
jerojasro@336
|
1054 \subsection{Finding out where changesets come from}
|
jerojasro@336
|
1055
|
jerojasro@336
|
1056 A hook that involves the transfer of changesets between a local
|
jerojasro@336
|
1057 repository and another may be able to find out information about the
|
jerojasro@336
|
1058 ``far side''. Mercurial knows \emph{how} changes are being
|
jerojasro@336
|
1059 transferred, and in many cases \emph{where} they are being transferred
|
jerojasro@336
|
1060 to or from.
|
jerojasro@336
|
1061
|
jerojasro@336
|
1062 \subsubsection{Sources of changesets}
|
jerojasro@336
|
1063 \label{sec:hook:sources}
|
jerojasro@336
|
1064
|
jerojasro@336
|
1065 Mercurial will tell a hook what means are, or were, used to transfer
|
jerojasro@336
|
1066 changesets between repositories. This is provided by Mercurial in a
|
jerojasro@336
|
1067 Python parameter named \texttt{source}, or an environment variable named
|
jerojasro@336
|
1068 \envar{HG\_SOURCE}.
|
jerojasro@336
|
1069
|
jerojasro@336
|
1070 \begin{itemize}
|
jerojasro@336
|
1071 \item[\texttt{serve}] Changesets are transferred to or from a remote
|
jerojasro@336
|
1072 repository over http or ssh.
|
jerojasro@336
|
1073 \item[\texttt{pull}] Changesets are being transferred via a pull from
|
jerojasro@336
|
1074 one repository into another.
|
jerojasro@336
|
1075 \item[\texttt{push}] Changesets are being transferred via a push from
|
jerojasro@336
|
1076 one repository into another.
|
jerojasro@336
|
1077 \item[\texttt{bundle}] Changesets are being transferred to or from a
|
jerojasro@336
|
1078 bundle.
|
jerojasro@336
|
1079 \end{itemize}
|
jerojasro@336
|
1080
|
jerojasro@336
|
1081 \subsubsection{Where changes are going---remote repository URLs}
|
jerojasro@336
|
1082 \label{sec:hook:url}
|
jerojasro@336
|
1083
|
jerojasro@336
|
1084 When possible, Mercurial will tell a hook the location of the ``far
|
jerojasro@336
|
1085 side'' of an activity that transfers changeset data between
|
jerojasro@336
|
1086 repositories. This is provided by Mercurial in a Python parameter
|
jerojasro@336
|
1087 named \texttt{url}, or an environment variable named \envar{HG\_URL}.
|
jerojasro@336
|
1088
|
jerojasro@336
|
1089 This information is not always known. If a hook is invoked in a
|
jerojasro@336
|
1090 repository that is being served via http or ssh, Mercurial cannot tell
|
jerojasro@336
|
1091 where the remote repository is, but it may know where the client is
|
jerojasro@336
|
1092 connecting from. In such cases, the URL will take one of the
|
jerojasro@336
|
1093 following forms:
|
jerojasro@336
|
1094 \begin{itemize}
|
jerojasro@336
|
1095 \item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
|
jerojasro@336
|
1096 the given IP address.
|
jerojasro@336
|
1097 \item \texttt{remote:http:\emph{ip-address}}---remote http client, at
|
jerojasro@336
|
1098 the given IP address. If the client is using SSL, this will be of
|
jerojasro@336
|
1099 the form \texttt{remote:https:\emph{ip-address}}.
|
jerojasro@336
|
1100 \item Empty---no information could be discovered about the remote
|
jerojasro@336
|
1101 client.
|
jerojasro@336
|
1102 \end{itemize}
|
jerojasro@336
|
1103
|
jerojasro@336
|
1104 \section{Hook reference}
|
jerojasro@336
|
1105
|
jerojasro@336
|
1106 \subsection{\hook{changegroup}---after remote changesets added}
|
jerojasro@336
|
1107 \label{sec:hook:changegroup}
|
jerojasro@336
|
1108
|
jerojasro@336
|
1109 This hook is run after a group of pre-existing changesets has been
|
jerojasro@336
|
1110 added to the repository, for example via a \hgcmd{pull} or
|
jerojasro@336
|
1111 \hgcmd{unbundle}. This hook is run once per operation that added one
|
jerojasro@336
|
1112 or more changesets. This is in contrast to the \hook{incoming} hook,
|
jerojasro@336
|
1113 which is run once per changeset, regardless of whether the changesets
|
jerojasro@336
|
1114 arrive in a group.
|
jerojasro@336
|
1115
|
jerojasro@336
|
1116 Some possible uses for this hook include kicking off an automated
|
jerojasro@336
|
1117 build or test of the added changesets, updating a bug database, or
|
jerojasro@336
|
1118 notifying subscribers that a repository contains new changes.
|
jerojasro@336
|
1119
|
jerojasro@336
|
1120 Parameters to this hook:
|
jerojasro@336
|
1121 \begin{itemize}
|
jerojasro@336
|
1122 \item[\texttt{node}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1123 changeset in the group that was added. All changesets between this
|
jerojasro@336
|
1124 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
|
jerojasro@336
|
1125 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
|
jerojasro@336
|
1126 \item[\texttt{source}] A string. The source of these changes. See
|
jerojasro@336
|
1127 section~\ref{sec:hook:sources} for details.
|
jerojasro@336
|
1128 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1129 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1130 \end{itemize}
|
jerojasro@336
|
1131
|
jerojasro@336
|
1132 See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
|
jerojasro@336
|
1133 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
|
jerojasro@336
|
1134 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
|
jerojasro@336
|
1135
|
jerojasro@336
|
1136 \subsection{\hook{commit}---after a new changeset is created}
|
jerojasro@336
|
1137 \label{sec:hook:commit}
|
jerojasro@336
|
1138
|
jerojasro@336
|
1139 This hook is run after a new changeset has been created.
|
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 newly
|
jerojasro@336
|
1144 committed changeset.
|
jerojasro@336
|
1145 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1146 parent of the newly committed changeset.
|
jerojasro@336
|
1147 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
|
jerojasro@336
|
1148 parent of the newly committed changeset.
|
jerojasro@336
|
1149 \end{itemize}
|
jerojasro@336
|
1150
|
jerojasro@336
|
1151 See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
|
jerojasro@336
|
1152 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
|
jerojasro@336
|
1153
|
jerojasro@336
|
1154 \subsection{\hook{incoming}---after one remote changeset is added}
|
jerojasro@336
|
1155 \label{sec:hook:incoming}
|
jerojasro@336
|
1156
|
jerojasro@336
|
1157 This hook is run after a pre-existing changeset has been added to the
|
jerojasro@336
|
1158 repository, for example via a \hgcmd{push}. If a group of changesets
|
jerojasro@336
|
1159 was added in a single operation, this hook is called once for each
|
jerojasro@336
|
1160 added changeset.
|
jerojasro@336
|
1161
|
jerojasro@336
|
1162 You can use this hook for the same purposes as the \hook{changegroup}
|
jerojasro@336
|
1163 hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
|
jerojasro@336
|
1164 sometimes to run a hook once per group of changesets, while other
|
jerojasro@336
|
1165 times it's handier once per changeset.
|
jerojasro@336
|
1166
|
jerojasro@336
|
1167 Parameters to this hook:
|
jerojasro@336
|
1168 \begin{itemize}
|
jerojasro@336
|
1169 \item[\texttt{node}] A changeset ID. The ID of the newly added
|
jerojasro@336
|
1170 changeset.
|
jerojasro@336
|
1171 \item[\texttt{source}] A string. The source of these changes. See
|
jerojasro@336
|
1172 section~\ref{sec:hook:sources} for details.
|
jerojasro@336
|
1173 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1174 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1175 \end{itemize}
|
jerojasro@336
|
1176
|
jerojasro@336
|
1177 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
|
1178
|
jerojasro@336
|
1179 \subsection{\hook{outgoing}---after changesets are propagated}
|
jerojasro@336
|
1180 \label{sec:hook:outgoing}
|
jerojasro@336
|
1181
|
jerojasro@336
|
1182 This hook is run after a group of changesets has been propagated out
|
jerojasro@336
|
1183 of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
|
jerojasro@336
|
1184 command.
|
jerojasro@336
|
1185
|
jerojasro@336
|
1186 One possible use for this hook is to notify administrators that
|
jerojasro@336
|
1187 changes have been pulled.
|
jerojasro@336
|
1188
|
jerojasro@336
|
1189 Parameters to this hook:
|
jerojasro@336
|
1190 \begin{itemize}
|
jerojasro@336
|
1191 \item[\texttt{node}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1192 changeset of the group that was sent.
|
jerojasro@336
|
1193 \item[\texttt{source}] A string. The source of the of the operation
|
jerojasro@336
|
1194 (see section~\ref{sec:hook:sources}). If a remote client pulled
|
jerojasro@336
|
1195 changes from this repository, \texttt{source} will be
|
jerojasro@336
|
1196 \texttt{serve}. If the client that obtained changes from this
|
jerojasro@336
|
1197 repository was local, \texttt{source} will be \texttt{bundle},
|
jerojasro@336
|
1198 \texttt{pull}, or \texttt{push}, depending on the operation the
|
jerojasro@336
|
1199 client performed.
|
jerojasro@336
|
1200 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1201 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1202 \end{itemize}
|
jerojasro@336
|
1203
|
jerojasro@336
|
1204 See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
|
jerojasro@336
|
1205
|
jerojasro@336
|
1206 \subsection{\hook{prechangegroup}---before starting to add remote changesets}
|
jerojasro@336
|
1207 \label{sec:hook:prechangegroup}
|
jerojasro@336
|
1208
|
jerojasro@336
|
1209 This controlling hook is run before Mercurial begins to add a group of
|
jerojasro@336
|
1210 changesets from another repository.
|
jerojasro@336
|
1211
|
jerojasro@336
|
1212 This hook does not have any information about the changesets to be
|
jerojasro@336
|
1213 added, because it is run before transmission of those changesets is
|
jerojasro@336
|
1214 allowed to begin. If this hook fails, the changesets will not be
|
jerojasro@336
|
1215 transmitted.
|
jerojasro@336
|
1216
|
jerojasro@336
|
1217 One use for this hook is to prevent external changes from being added
|
jerojasro@336
|
1218 to a repository. For example, you could use this to ``freeze'' a
|
jerojasro@336
|
1219 server-hosted branch temporarily or permanently so that users cannot
|
jerojasro@336
|
1220 push to it, while still allowing a local administrator to modify the
|
jerojasro@336
|
1221 repository.
|
jerojasro@336
|
1222
|
jerojasro@336
|
1223 Parameters to this hook:
|
jerojasro@336
|
1224 \begin{itemize}
|
jerojasro@336
|
1225 \item[\texttt{source}] A string. The source of these changes. See
|
jerojasro@336
|
1226 section~\ref{sec:hook:sources} for details.
|
jerojasro@336
|
1227 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1228 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1229 \end{itemize}
|
jerojasro@336
|
1230
|
jerojasro@336
|
1231 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
|
jerojasro@336
|
1232 \hook{incoming} (section~\ref{sec:hook:incoming}), ,
|
jerojasro@336
|
1233 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
|
jerojasro@336
|
1234
|
jerojasro@336
|
1235 \subsection{\hook{precommit}---before starting to commit a changeset}
|
jerojasro@336
|
1236 \label{sec:hook:precommit}
|
jerojasro@336
|
1237
|
jerojasro@336
|
1238 This hook is run before Mercurial begins to commit a new changeset.
|
jerojasro@336
|
1239 It is run before Mercurial has any of the metadata for the commit,
|
jerojasro@336
|
1240 such as the files to be committed, the commit message, or the commit
|
jerojasro@336
|
1241 date.
|
jerojasro@336
|
1242
|
jerojasro@336
|
1243 One use for this hook is to disable the ability to commit new
|
jerojasro@336
|
1244 changesets, while still allowing incoming changesets. Another is to
|
jerojasro@336
|
1245 run a build or test, and only allow the commit to begin if the build
|
jerojasro@336
|
1246 or test succeeds.
|
jerojasro@336
|
1247
|
jerojasro@336
|
1248 Parameters to this hook:
|
jerojasro@336
|
1249 \begin{itemize}
|
jerojasro@336
|
1250 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1251 parent of the working directory.
|
jerojasro@336
|
1252 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
|
jerojasro@336
|
1253 parent of the working directory.
|
jerojasro@336
|
1254 \end{itemize}
|
jerojasro@336
|
1255 If the commit proceeds, the parents of the working directory will
|
jerojasro@336
|
1256 become the parents of the new changeset.
|
jerojasro@336
|
1257
|
jerojasro@336
|
1258 See also: \hook{commit} (section~\ref{sec:hook:commit}),
|
jerojasro@336
|
1259 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
|
jerojasro@336
|
1260
|
jerojasro@336
|
1261 \subsection{\hook{preoutgoing}---before starting to propagate changesets}
|
jerojasro@336
|
1262 \label{sec:hook:preoutgoing}
|
jerojasro@336
|
1263
|
jerojasro@336
|
1264 This hook is invoked before Mercurial knows the identities of the
|
jerojasro@336
|
1265 changesets to be transmitted.
|
jerojasro@336
|
1266
|
jerojasro@336
|
1267 One use for this hook is to prevent changes from being transmitted to
|
jerojasro@336
|
1268 another repository.
|
jerojasro@336
|
1269
|
jerojasro@336
|
1270 Parameters to this hook:
|
jerojasro@336
|
1271 \begin{itemize}
|
jerojasro@336
|
1272 \item[\texttt{source}] A string. The source of the operation that is
|
jerojasro@336
|
1273 attempting to obtain changes from this repository (see
|
jerojasro@336
|
1274 section~\ref{sec:hook:sources}). See the documentation for the
|
jerojasro@336
|
1275 \texttt{source} parameter to the \hook{outgoing} hook, in
|
jerojasro@336
|
1276 section~\ref{sec:hook:outgoing}, for possible values of this
|
jerojasro@336
|
1277 parameter.
|
jerojasro@336
|
1278 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1279 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1280 \end{itemize}
|
jerojasro@336
|
1281
|
jerojasro@336
|
1282 See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
|
jerojasro@336
|
1283
|
jerojasro@336
|
1284 \subsection{\hook{pretag}---before tagging a changeset}
|
jerojasro@336
|
1285 \label{sec:hook:pretag}
|
jerojasro@336
|
1286
|
jerojasro@336
|
1287 This controlling hook is run before a tag is created. If the hook
|
jerojasro@336
|
1288 succeeds, creation of the tag proceeds. If the hook fails, the tag is
|
jerojasro@336
|
1289 not created.
|
jerojasro@336
|
1290
|
jerojasro@336
|
1291 Parameters to this hook:
|
jerojasro@336
|
1292 \begin{itemize}
|
jerojasro@336
|
1293 \item[\texttt{local}] A boolean. Whether the tag is local to this
|
jerojasro@336
|
1294 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
|
jerojasro@336
|
1295 managed by Mercurial (stored in \sfilename{.hgtags}).
|
jerojasro@336
|
1296 \item[\texttt{node}] A changeset ID. The ID of the changeset to be tagged.
|
jerojasro@336
|
1297 \item[\texttt{tag}] A string. The name of the tag to be created.
|
jerojasro@336
|
1298 \end{itemize}
|
jerojasro@336
|
1299
|
jerojasro@336
|
1300 If the tag to be created is revision-controlled, the \hook{precommit}
|
jerojasro@336
|
1301 and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
|
jerojasro@336
|
1302 and~\ref{sec:hook:pretxncommit}) will also be run.
|
jerojasro@336
|
1303
|
jerojasro@336
|
1304 See also: \hook{tag} (section~\ref{sec:hook:tag})
|
jerojasro@336
|
1305
|
jerojasro@336
|
1306 \subsection{\hook{pretxnchangegroup}---before completing addition of
|
jerojasro@336
|
1307 remote changesets}
|
jerojasro@336
|
1308 \label{sec:hook:pretxnchangegroup}
|
jerojasro@336
|
1309
|
jerojasro@336
|
1310 This controlling hook is run before a transaction---that manages the
|
jerojasro@336
|
1311 addition of a group of new changesets from outside the
|
jerojasro@336
|
1312 repository---completes. If the hook succeeds, the transaction
|
jerojasro@336
|
1313 completes, and all of the changesets become permanent within this
|
jerojasro@336
|
1314 repository. If the hook fails, the transaction is rolled back, and
|
jerojasro@336
|
1315 the data for the changesets is erased.
|
jerojasro@336
|
1316
|
jerojasro@336
|
1317 This hook can access the metadata associated with the almost-added
|
jerojasro@336
|
1318 changesets, but it should not do anything permanent with this data.
|
jerojasro@336
|
1319 It must also not modify the working directory.
|
jerojasro@336
|
1320
|
jerojasro@336
|
1321 While this hook is running, if other Mercurial processes access this
|
jerojasro@336
|
1322 repository, they will be able to see the almost-added changesets as if
|
jerojasro@336
|
1323 they are permanent. This may lead to race conditions if you do not
|
jerojasro@336
|
1324 take steps to avoid them.
|
jerojasro@336
|
1325
|
jerojasro@336
|
1326 This hook can be used to automatically vet a group of changesets. If
|
jerojasro@336
|
1327 the hook fails, all of the changesets are ``rejected'' when the
|
jerojasro@336
|
1328 transaction rolls back.
|
jerojasro@336
|
1329
|
jerojasro@336
|
1330 Parameters to this hook:
|
jerojasro@336
|
1331 \begin{itemize}
|
jerojasro@336
|
1332 \item[\texttt{node}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1333 changeset in the group that was added. All changesets between this
|
jerojasro@336
|
1334 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
|
jerojasro@336
|
1335 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
|
jerojasro@336
|
1336 \item[\texttt{source}] A string. The source of these changes. See
|
jerojasro@336
|
1337 section~\ref{sec:hook:sources} for details.
|
jerojasro@336
|
1338 \item[\texttt{url}] A URL. The location of the remote repository, if
|
jerojasro@336
|
1339 known. See section~\ref{sec:hook:url} for more information.
|
jerojasro@336
|
1340 \end{itemize}
|
jerojasro@336
|
1341
|
jerojasro@336
|
1342 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
|
jerojasro@336
|
1343 \hook{incoming} (section~\ref{sec:hook:incoming}),
|
jerojasro@336
|
1344 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
|
jerojasro@336
|
1345
|
jerojasro@336
|
1346 \subsection{\hook{pretxncommit}---before completing commit of new changeset}
|
jerojasro@336
|
1347 \label{sec:hook:pretxncommit}
|
jerojasro@336
|
1348
|
jerojasro@336
|
1349 This controlling hook is run before a transaction---that manages a new
|
jerojasro@336
|
1350 commit---completes. If the hook succeeds, the transaction completes
|
jerojasro@336
|
1351 and the changeset becomes permanent within this repository. If the
|
jerojasro@336
|
1352 hook fails, the transaction is rolled back, and the commit data is
|
jerojasro@336
|
1353 erased.
|
jerojasro@336
|
1354
|
jerojasro@336
|
1355 This hook can access the metadata associated with the almost-new
|
jerojasro@336
|
1356 changeset, but it should not do anything permanent with this data. It
|
jerojasro@336
|
1357 must also not modify the working directory.
|
jerojasro@336
|
1358
|
jerojasro@336
|
1359 While this hook is running, if other Mercurial processes access this
|
jerojasro@336
|
1360 repository, they will be able to see the almost-new changeset as if it
|
jerojasro@336
|
1361 is permanent. This may lead to race conditions if you do not take
|
jerojasro@336
|
1362 steps to avoid them.
|
jerojasro@336
|
1363
|
jerojasro@336
|
1364 Parameters to this hook:
|
jerojasro@336
|
1365 \begin{itemize}
|
jerojasro@336
|
1366 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
|
jerojasro@336
|
1367 committed changeset.
|
jerojasro@336
|
1368 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
|
jerojasro@336
|
1369 parent of the newly committed changeset.
|
jerojasro@336
|
1370 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
|
jerojasro@336
|
1371 parent of the newly committed changeset.
|
jerojasro@336
|
1372 \end{itemize}
|
jerojasro@336
|
1373
|
jerojasro@336
|
1374 See also: \hook{precommit} (section~\ref{sec:hook:precommit})
|
jerojasro@336
|
1375
|
jerojasro@336
|
1376 \subsection{\hook{preupdate}---before updating or merging working directory}
|
jerojasro@336
|
1377 \label{sec:hook:preupdate}
|
jerojasro@336
|
1378
|
jerojasro@336
|
1379 This controlling hook is run before an update or merge of the working
|
jerojasro@336
|
1380 directory begins. It is run only if Mercurial's normal pre-update
|
jerojasro@336
|
1381 checks determine that the update or merge can proceed. If the hook
|
jerojasro@336
|
1382 succeeds, the update or merge may proceed; if it fails, the update or
|
jerojasro@336
|
1383 merge does not start.
|
jerojasro@336
|
1384
|
jerojasro@336
|
1385 Parameters to this hook:
|
jerojasro@336
|
1386 \begin{itemize}
|
jerojasro@336
|
1387 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
|
jerojasro@336
|
1388 working directory is to be updated to. If the working directory is
|
jerojasro@336
|
1389 being merged, it will not change this parent.
|
jerojasro@336
|
1390 \item[\texttt{parent2}] A changeset ID. Only set if the working
|
jerojasro@336
|
1391 directory is being merged. The ID of the revision that the working
|
jerojasro@336
|
1392 directory is being merged with.
|
jerojasro@336
|
1393 \end{itemize}
|
jerojasro@336
|
1394
|
jerojasro@336
|
1395 See also: \hook{update} (section~\ref{sec:hook:update})
|
jerojasro@336
|
1396
|
jerojasro@336
|
1397 \subsection{\hook{tag}---after tagging a changeset}
|
jerojasro@336
|
1398 \label{sec:hook:tag}
|
jerojasro@336
|
1399
|
jerojasro@336
|
1400 This hook is run after a tag has been created.
|
jerojasro@336
|
1401
|
jerojasro@336
|
1402 Parameters to this hook:
|
jerojasro@336
|
1403 \begin{itemize}
|
jerojasro@336
|
1404 \item[\texttt{local}] A boolean. Whether the new tag is local to this
|
jerojasro@336
|
1405 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
|
jerojasro@336
|
1406 managed by Mercurial (stored in \sfilename{.hgtags}).
|
jerojasro@336
|
1407 \item[\texttt{node}] A changeset ID. The ID of the changeset that was
|
jerojasro@336
|
1408 tagged.
|
jerojasro@336
|
1409 \item[\texttt{tag}] A string. The name of the tag that was created.
|
jerojasro@336
|
1410 \end{itemize}
|
jerojasro@336
|
1411
|
jerojasro@336
|
1412 If the created tag is revision-controlled, the \hook{commit} hook
|
jerojasro@336
|
1413 (section~\ref{sec:hook:commit}) is run before this hook.
|
jerojasro@336
|
1414
|
jerojasro@336
|
1415 See also: \hook{pretag} (section~\ref{sec:hook:pretag})
|
jerojasro@336
|
1416
|
jerojasro@336
|
1417 \subsection{\hook{update}---after updating or merging working directory}
|
jerojasro@336
|
1418 \label{sec:hook:update}
|
jerojasro@336
|
1419
|
jerojasro@336
|
1420 This hook is run after an update or merge of the working directory
|
jerojasro@336
|
1421 completes. Since a merge can fail (if the external \command{hgmerge}
|
jerojasro@336
|
1422 command fails to resolve conflicts in a file), this hook communicates
|
jerojasro@336
|
1423 whether the update or merge completed cleanly.
|
jerojasro@336
|
1424
|
jerojasro@336
|
1425 \begin{itemize}
|
jerojasro@336
|
1426 \item[\texttt{error}] A boolean. Indicates whether the update or
|
jerojasro@336
|
1427 merge completed successfully.
|
jerojasro@336
|
1428 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
|
jerojasro@336
|
1429 working directory was updated to. If the working directory was
|
jerojasro@336
|
1430 merged, it will not have changed this parent.
|
jerojasro@336
|
1431 \item[\texttt{parent2}] A changeset ID. Only set if the working
|
jerojasro@336
|
1432 directory was merged. The ID of the revision that the working
|
jerojasro@336
|
1433 directory was merged with.
|
jerojasro@336
|
1434 \end{itemize}
|
jerojasro@336
|
1435
|
jerojasro@336
|
1436 See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
|
jerojasro@336
|
1437
|
jerojasro@336
|
1438 %%% Local Variables:
|
jerojasro@336
|
1439 %%% mode: latex
|
jerojasro@336
|
1440 %%% TeX-master: "00book"
|
jerojasro@336
|
1441 %%% End:
|