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