hgbook
view es/hook.tex @ 653:6b1577ef5135
Update Chinese translation
| author | Dongsheng Song <dongsheng.song@gmail.com> |
|---|---|
| date | Fri Mar 20 17:17:55 2009 +0800 (2009-03-20) |
| parents | e0e65bfe7776 |
| children |
line source
1 \chapter{Manejo de eventos en repositorios mediante ganchos}
2 \label{chap:hook}
4 Mercurial ofrece un poderoso mecanismo para permitirle a usted
5 automatizar la ejecución de acciones en respuesta a eventos que
6 ocurran en un repositorio. En algunos casos, usted puede controlar
7 incluso la respuesta de Mercurial a dichos eventos.
9 Mercurial usa el término \emph{gancho} para identificar estas
10 acciones. Los ganchos son conocidos como ``disparadores'' en algunos
11 sistemas de control de revisiones, pero los dos nombres se refieren al
12 mismo concepto.
14 \section{Vistazo general de ganchos en Mercurial}
16 A continuación se encuentra una breve lista de los ganchos que
17 Mercurial soporta. Volveremos a cada uno de estos ganchos con más
18 detalle después, en la sección~\ref{sec:hook:ref}.
20 \begin{itemize}
21 \item[\small\hook{changegroup}] Es ejecutado luego de que un grupo de
22 conjuntos de cambios ha sido traído al repositorio desde algún
23 otro sitio.
24 \item[\small\hook{commit}] Es ejecutado después de la creación de
25 un conjunto de cambios en el repositorio local.
26 \item[\small\hook{incoming}] Es ejecutado una vez por cada conjunto de
27 cambios traído al repositorio desde otra ubicación. Note la
28 diferencia respecto al gancho \hook{changegroup}, que es ejecutado
29 una vez por cada \emph{grupo} de conjuntos de cambios que se
30 traiga.
31 \item[\small\hook{outgoing}] Es ejecutado luego de que un grupo de
32 conjuntos de cambios ha sido transmitido desde el repositorio.
33 \item[\small\hook{prechangegroup}] Es ejecutado antes de iniciar la
34 recepción de un grupo de conjuntos de cambios en el repositorio.
35 \item[\small\hook{precommit}] De control. Es ejecutado antes de
36 iniciar una consignación.
37 \item[\small\hook{preoutgoing}] De control. Es ejecutado antes de
38 iniciar la transmisión de un grupo de conjuntos de cambios desde
39 el repositorio.
40 \item[\small\hook{pretag}] De control. Es ejecutado antes de crear una
41 etiqueta.
42 \item[\small\hook{pretxnchangegroup}] De control. Es ejecutado después
43 de haber recibido un grupo de conjuntos de cambios en el
44 repositorio local, pero antes de que la transacción se complete y
45 los cambios sean permanentes dentro del repositorio.
46 \item[\small\hook{pretxncommit}] De control. Es ejecutado luego de la
47 creación de un conjunto de cambios en el repositorio local, pero
48 antes de que la transacción que hace permanente el cambio sea
49 completada.
50 \item[\small\hook{preupdate}] De control. Es ejecutado antes de
51 iniciar una actualización o fusión en el directorio de trabajo.
52 \item[\small\hook{tag}] Es ejecutado después de la creación de una
53 etiqueta.
54 \item[\small\hook{update}] Es ejecutado después de que termina una
55 actualización o una fusión.
56 \end{itemize}
57 Cada uno de los ganchos cuya descripción empieza con la frase
58 ``de control'' tiene la facultad de determinar si una actividad puede
59 continuar. Si el gancho se ejecuta con éxito, la actividad puede
60 continuar; si falla, o bien la actividad no es permitida, o se
61 deshacen los cambios que se puedan haber llevado a cabo, dependiendo
62 del gancho involucrado.
64 \section{Ganchos y seguridad}
66 \subsection{Los ganchos se ejecutan con sus privilegios de usuario}
68 Cuando usted ejecuta un comando de Mercurial en un repositorio, y el
69 comando causa la ejecución de un gancho, dicho gancho se ejecuta en
70 \emph{su} sistema, en \emph{su} cuenta de usuario, con \emph{sus}
71 privilegios. Ya que los ganchos son elementos arbitrarios de código
72 ejecutable, usted debería tratarlos con un nivel adecuado de
73 desconfianza. No instale un gancho a menos en que confíe en quien lo
74 creó y en lo que el gancho hace.
76 En algunos casos, usted puede estar expuesto a ganchos que usted no
77 %TODO acá introduzco algo de texto por mi cuenta, por claridad
78 instaló. Si usted usa Mercurial en un sistema extraño, tenga en cuenta
79 que Mercurial ejecutará los ganchos definidos en el fichero \hgrc.
81 Si está trabajando con un repositorio propiedad de otro usuario,
82 Mercurial podrá ejecutar los ganchos definidos en el repositorio de
83 dicho usuario, pero los ejecutará como ``usted''. Por ejemplo, si
84 usted jala (\hgcmd{pull}) desde ese repositorio, y el
85 \sfilename{.hg/hgrc} define un gancho saliente (\hook{outgoing}),
86 dicho gancho se ejecuta bajo su cuenta de usuario, aun cuando usted no
87 es el propietario del repositorio.
89 \begin{note}
90 Esto sólo aplica si usted está jalando desde un repositorio en un
91 sistema de ficheros local o de red. Si está jalando a través de http
92 o ssh, cualquier gancho saliente (\hook{outgoing}) se ejecutará bajo
93 la cuenta que está ejecutando el proceso servidor, en el servidor.
94 \end{note}
96 XXX Para ver qué ganchos han sido definidos en un repositorio, use el
97 comando \hgcmdargs{config}{hooks}. Si usted está trabajando en un
98 repositorio, pero comunicándose con otro que no le pertenece
99 (por ejemplo, usando \hgcmd{pull} o \hgcmd{incoming}), recuerde que
100 los ganchos que debe considerar son los del otro repositorio, no los
101 del suyo.
103 \subsection{Los ganchos no se propagan}
105 En Mercurial, no se hace control de revisiones de los ganchos, y no se
106 propagan cuando usted clona, o jala de, un repositorio. El motivo para
107 esto es simple: un gancho es código ejecutable arbitrario. Se ejecuta
108 bajo su identidad, con su nivel de privilegios, en su máquina.
110 Sería extremadamente descuidado de parte de cualquier sistema
111 distribuido de control de revisiones el implementar control de
112 revisiones para ganchos, ya que esto ofrecería maneras fácilmente
113 %TODO subvertir
114 aprovechables de subvertir las cuentas de los usuarios del sistema de
115 control de revisiones.
117 Ya que Mercurial no propaga los ganchos, si usted está colaborando con
118 otras personas en un proyecto común, no debería asumir que ellos están
119 usando los mismos ganchos para Mercurial que usted usa, o que los de
120 ellos están configurado correctamente. Usted debería documentar los
121 ganchos que usted espera que la gente use.
123 En una intranet corporativa, esto es algo más fácil de manejar, ya que
124 usted puede, por ejemplo, proveer una instalación ``estándar'' de
125 Mercurial en un sistema de ficheros NFS, y usar un fichero \hgrc\
126 global para definir los ganchos que verán todos los usuarios. Sin
127 embargo, este enfoque tiene sus límites; vea más abajo.
129 \subsection{Es posible hacer caso omiso de los ganchos}
131 Mercurial le permite hacer caso omiso de la deficinión de un gancho,
132 a través de la redefinición del mismo. Usted puede deshabilitar el
133 gancho fijando su valor como una cadena vacía, o cambiar su
134 comportamiento como desee.
136 Si usted instala un fichero \hgrc\ a nivel de sistema o sitio completo
137 que define algunos ganchos, debe entender que sus usuarios pueden
138 deshabilitar o hacer caso omiso de los mismos.
140 \subsection{Asegurarse de que ganchos críticos sean ejecutados}
142 Algunas veces usted puede querer hacer respetar una política, y no
143 permitir que los demás sean capaces de evitarla. Por ejemplo, usted
144 puede tener como requerimiento que cada conjunto de cambios debe pasar
145 un riguroso conjunto de pruebas. Definir este requerimientos a través
146 de un gancho en un fichero \hgrc\ global no servirá con usuarios
147 remotos en computadoras portátiles, y por supuesto que los usuarios
148 locales pueden evitar esto a voluntad haciendo caso omiso del gancho.
150 En vez de eso, usted puede definir las políticas para usar Mercurial
151 de tal forma que se espere que los usuarios propaguen los cambios a
152 través de un servidor ``canónico'' bien conocido que usted ha
153 asegurado y configurado apropiadamente.
155 Una manera de hacer esto es a través de una combinación de ingeniería
156 social y tecnología. Cree una cuenta de acceso restringido; los
157 usuarios pueden empujar cambios a través de la red a los repositorios
158 administrados por esta cuenta, pero no podrán ingresar a dicha cuenta
159 para ejecutar órdenes en el intérprete de comandos. En este escenario,
160 un usuario puede enviar un conjunto de cambios que contenga la
161 porquería que él desee.
163 Cuando alguien empuja un conjunto de cambios al servidor del que todos
164 jalan, el servidor probará el conjunto de cambios antes de aceptarlo
165 como permanente, y lo rechazará si no logra pasar el conjunto de
166 pruebas. Si la gente sólo jala cambios desde este servidor de filtro,
167 servirá para asegurarse de que todos los cambios que la gente jala han
168 sido examinados automáticamente
170 \section{Precauciones con ganchos \texttt{pretxn} en un repositorio de
171 acceso compartido}
173 Si usted desea usar ganchos para llevar a cabo automáticamente algún
174 trabajo en un repositorio al que varias personas tienen acceso
175 compartido, debe tener cuidado con la forma de hacerlo.
177 Mercurial sólo bloquea un repositorio cuando está escribiendo al
178 mismo, y sólo las partes de Mercurial que escriben al repositorio le
179 prestan atención a los bloqueos. Los bloqueos de escritura son
180 necesarios para evitar que múltiples escritores simultáneos
181 interfieran entre sí, corrompiendo el repositorio.
183 Ya que Mercurial tiene cuidado con el orden en que lee y escribe
184 datos, no necesita adquirir un bloqueo cuando desea leer datos del
185 repositorio. Las partes de Mercurial que leen del repositorio nunca le
186 prestan atención a los bloqueos. Este esquema de lectura libre de
187 bloqueos incremententa en gran medida el desempeño y la concurrencia.
189 Sin embargo, para tener un gran desempeño es necesario hacer
190 sacrificios, uno de los cuales tiene el potencial de causarle
191 problemas a menos de que usted esté consciente de él. Describirlo
192 requiere algo de detalle respecto a cómo Mercurial añade conjuntos de
193 cambios al repositorio y cómo lee esos cambios de vuelta.
195 Cuando Mercurial \emph{escribe} metadatos, los escribe directamente en
196 el fichero de destino. Primero escribe los datos del fichero, luego
197 los datos del manifiesto (que contienen punteros a los nuevos datos
198 del fichero), luego datos de la bitácora de cambios (que contienen
199 punteros a los nuevos datos del manifiesto). Antes de la primera
200 escritura a cada fichero, se guarda un registro de dónde estaba el
201 final de fichero en su registro de transacciones. Si la transacción
202 debe ser deshecha, Mercurial simplemente trunca cada fichero de vuelta
203 al tamaño que tenía antes de que empezara la transacción.
205 Cuando Mercurial \emph{lee} metadatos, lee la bitácora de cambios
206 primero, y luego todo lo demás. Como un lector sólo accederá a las
207 partes del manifiesto o de los metadatos de fichero que él puede ver
208 en la bitácora de cambios, nunca puede ver datos parcialmente
209 escritos.
211 Algunos ganchos de control (\hook{pretxncommit} y
212 \hook{pretxnchangegroup}) se ejecutan cuando una transacción está casi
213 completa. Todos los metadatos han sido escritos, pero Mercurial aún
214 puede deshacer la transacción y hacer que los datos recién escritos
215 desaparezcan.
217 Si alguno de estos ganchos permanece en ejecución por mucho tiempo,
218 abre una ventana de tiempo en la que un lector puede ver los metadatos
219 de conjuntos de cambios que aún no son permanentes y que no debería
220 considerarse que estén ``realmante ahí''. Entre más tiempo tome la
221 ejecución del gancho, más tiempo estará abierta esta ventana.
223 \subsection{Ilustración del problema}
225 En principio, un buen uso del gancho \hook{pretxnchangegroup} sería
226 ensamblar y probar automáticamente todos los cambios entrantes antes
227 de que sean aceptados en un repositorio central. Esto le permitiría a
228 usted garantizar que nadie pueda empujar cambios que ``rompan el
229 ensamblaje''. Pero si un cliente puede jalar cambios mientras están
230 siendo probados, la utilidad de esta prueba es nula; alguien confiado
231 puede jalar cambios sin probar, lo que potencialmente podría romper su
232 proceso de ensamblaje.
234 La respuesta técnica más segura frente a este retos es montar dicho
235 repositorio ``guardián'' como \emph{unidireccional}. Permita que
236 reciba cambios desde el exterior, pero no permita que nadie jale
237 cambios de él (use el gancho \hook{preoutgoing} para bloquear esto).
238 Configure un gancho \hook{changegroup} para que si el ensamblaje o
239 prueba tiene éxito, el gancho empuje los nuevos cambios a otro
240 repositorio del que la gente \emph{pueda} jalar.
242 En la práctica, montar un cuello de botella centralizado como éste a
243 menudo no es una buena idea, y la visibilidad de las transacciones no
244 tiene nada que ver con el problema. A medida que el tamaño de un
245 proyecto---y el tiempo que toma ensamblarlo y probarlo---crece, usted
246 se acerca rápidamente a un límite con este enfoque ``pruebe antes de
247 comprar'', en el que tiene más conjuntos de cambios a probar que
248 tiempo para ocuparse de ellos. El resultado inevitable es frustración
249 para todos los que estén involucrados.
251 Una aproximación que permite manejar mejor el crecimiento es hacer que
252 la gente ensamble y pruebe antes de empujar, y ejecutar el ensamble y
253 pruebas automáticas centralmente \emph{después} de empujar, para
254 asegurarse de que todo esté bien. La ventaja de este enfoque es que no
255 impone un límite a la rata en la que un repositorio puede aceptar
256 cambios.
258 \section{Tutorial corto de uso de ganchos}
259 \label{sec:hook:simple}
261 Escribir un gancho para Mercurial es fácil. Empecemos con un gancho
262 que se ejecute cuando usted termine un \hgcmd{commit}, y simplemente
263 muestre el hash del conjunto de cambios que usted acaba de crear. El
264 gancho se llamará \hook{commit}.
266 \begin{figure}[ht]
267 \interaction{hook.simple.init}
268 \caption{Un gancho simple que se ejecuta al hacer la consignación de
269 un conjunto de cambios}
270 \label{ex:hook:init}
271 \end{figure}
273 Todos los ganchos siguen el patrón del ejemplo~\ref{ex:hook:init}.
274 Usted puede añadir una entrada a la sección \rcsection{hooks} de su
275 fichero \hgrc. A la izquierda está el nombre del evento respecto al
276 cual dispararse; a la derecha está la acción a llevar a cabo. Como
277 puede ver, es posible ejecutar cualquier orden de la línea de comandos
278 en un gancho. Mercurial le pasa información extra al gancho usando
279 variables de entorno (busque \envar{HG\_NODE} en el ejemplo).
281 \subsection{Llevar a cabo varias acciones por evento}
283 A menudo, usted querrá definir más de un gancho para un tipo de evento
284 particular, como se muestra en el ejemplo~\ref{ex:hook:ext}.
285 Mercurial le permite hacer esto añadiendo una \emph{extensión} al
286 final del nombre de un gancho. Usted extiende el nombre del gancho
287 %TODO Yuk, no me gusta ese "parada completa"
288 poniendo el nombre del gancho, seguido por una parada completa (el
289 caracter ``\texttt{.}''), seguido de algo más de texto de su elección.
290 Por ejemplo, Mercurial ejecutará tanto \texttt{commit.foo} como
291 \texttt{commit.bar} cuando ocurra el evento \texttt{commit}.
293 \begin{figure}[ht]
294 \interaction{hook.simple.ext}
295 \caption{Definición de un segundo gancho \hook{commit}}
296 \label{ex:hook:ext}
297 \end{figure}
299 Para dar un orden bien definido de ejecución cuando hay múltiples
300 ganchos definidos para un evento, Mercurial ordena los ganchos de
301 acuerdo a su extensión, y los ejecuta en dicho orden. En el ejemplo de
302 arribam \texttt{commit.bar} se ejecutará antes que
303 \texttt{commit.foo}, y \texttt{commit} se ejecutará antes de ambos.
305 Es una buena idea usar una extensión descriptiva cuando usted define
306 un gancho. Esto le ayudará a recordar para qué se usa el gancho. Si el
307 gancho falla, usted recibirá un mensaje de error que contiene el
308 nombre y la extensión del gancho, así que usar una extensión
309 descriptiva le dará una pista inmediata de porqué el gancho falló (vea
310 un ejemplo en la sección~\ref{sec:hook:perm}).
312 \subsection{Controlar cuándo puede llevarse a cabo una actividad}
313 \label{sec:hook:perm}
315 En los ejemplos anteriores, usamos el gancho \hook{commit}, que es
316 ejecutado después de que se ha completado una consignación. Este es
317 uno de los varios ganchos que Mercurial ejecuta luego de que una
318 actividad termina. Tales ganchos no tienen forma de influenciar la
319 actividad como tal.
321 Mercurial define un número de eventos que ocurren antes de que una
322 actividad empiece; o luego de que empiece, pero antes de que termine.
323 Los ganchos que se disparan con estos eventos tienen la capacidad
324 adicional de elegir si la actividad puede continuar, o si su ejecución
325 es abortada.
327 El gancho \hook{pretxncommit} se ejecuta justo antes de que una
328 consignación se ejecute. En otras palabras, los metadatos que
329 representan el conjunto de cambios han sido escritos al disco, pero no
330 se ha terminado la transacción. El gancho \hook{pretxncommit} tiene la
331 capacidad de decidir si una transacción se completa, o debe
332 deshacerse.
334 Si el gancho \hook{pretxncommit} termina con un código de salida de
335 cero, se permite que la transacción se complete; la consignación
336 termina; y el gancho \hook{commit} es ejecutado. Si el gancho
337 \hook{pretxncommit} termina con un código de salida diferente de cero,
338 la transacción es revertida; los metadatos representando el conjunto
339 de cambios son borrados; y el gancho \hook{commit} no es ejecutado.
341 \begin{figure}[ht]
342 \interaction{hook.simple.pretxncommit}
343 \caption{Uso del gancho \hook{pretxncommit} para controlar consignaciones}
344 \label{ex:hook:pretxncommit}
345 \end{figure}
347 El gancho en el ejemplo~\ref{ex:hook:pretxncommit} revisa si el
348 mensaje de consignación contiene el ID de algún fallo. Si lo contiene,
349 la consignación puede continuar. Si no, la consignación es cancelada.
351 \section{Escribir sus propios ganchos}
353 Cuando usted escriba un gancho, puede encontrar útil el ejecutar
354 Mercurial o bien pasándole la opción \hggopt{-v}, o con el valor de
355 configuración \rcitem{ui}{verbose} fijado en ``true'' (verdadero).
356 Cuando lo haga, Mercurial imprimirá un mensaje antes de llamar cada
357 gancho.
359 \subsection{Escoger cómo debe ejecutarse su gancho}
360 \label{sec:hook:lang}
362 Usted puede escribir un gancho que funcione como un programa normal
363 ---típicamente un guión de línea de comandos---o como una función de
364 Python que se ejecuta dentro del proceso Mercurial.
366 Escribir un gancho como un programa externo tiene la ventaja de que no
367 requiere ningún conocimiento del funcionamiento interno de Mercurial.
368 Usted puede ejecutar comandos Mercurial normales para obtener la
369 informción extra que pueda necesitar. La contraparte de esto es que
370 los ganchos externos son más lentos que los ganchos internos
371 ejecutados dentro del proceso.
373 Un gancho Python interno tiene acceso completo a la API de Mercurial,
374 y no se ``externaliza'' a otro proceso, así que es inherentemente más
375 rápido que un gancho externo. Adicionalmente es más fácil obtener la
376 mayoría de la información que un gancho requiere a través de llamadas
377 directas a la API de Mercurial que hacerlo ejecutando comandos
378 Mercurial.
380 Si se siente a gusto con Python, o requiere un alto desempeño,
381 escribir sus ganchos en Python puede ser una buena elección. Sin
382 embargo, cuando usted tiene un gancho bastante directo por escribir y
383 no le importa el desempeño (el caso de la mayoría de los ganchos), es
384 perfectamente admisible un guión de línea de comandos.
386 \subsection{Parámetros para ganchos}
387 \label{sec:hook:param}
389 Mercurial llama cada gancho con un conjunto de paŕametros bien
390 definidos. En Python, un parámetro se pasa como argumento de palabra
391 clave a su función de gancho. Para un programa externo, los parámetros
392 son pasados como variables de entornos.
394 Sin importar si su gancho está escrito en Python o como guión de línea
395 de comandos, los nombres y valores de los parámetros específicos de
396 los ganchos serán los mismos. Un parámetro booleano será representado
397 como un valor booleano en Python, pero como el número 1 (para
398 ``verdadero'') o 0 (para falso) en una variable de entorno para un
399 gancho externo. Si un parámetro se llama \texttt{foo}, el argumento de
400 palabra clave para un gancho en Python también se llamará
401 \texttt{foo}, mientras que la variable de entorno para un gancho
402 externo se llamará \texttt{HG\_FOO}.
404 \subsection{Valores de retorno de ganchos y control de actividades}
406 Un gancho que se ejecuta exitosamente debe terminar con un código de
407 salida de cero, si es externo, o retornar el valor booleano
408 ``falso'', si es interno. Un fallo se indica con un código de salida
409 diferente de cero desde un gancho externo, o un valor de retorno
410 booleano ``verdadero''. Si un gancho interno genera una excepción, se
411 considera que el gancho ha fallado.
413 Para los ganchos que controlan si una actividad puede continuar o no,
414 cero/falso quiere decir ``permitir'', mientras que
415 % TODO me suena mejor "no permitir" que "denegar"
416 no-cero/verdadero/excepción quiere decir ``no permitir''.
418 \subsection{Escribir un gancho externo}
420 Cuando usted define un gancho externo en su fichero \hgrc\ y el mismo
421 es ejecutado, dicha definición pasa a su intérprete de comandos, que
422 hace la interpretación correspondiente. Esto significa que usted puede
423 usar elementos normales del intérprete en el cuerpo del gancho.
425 Un gancho ejecutable siempre es ejecutado con su directorio actual
426 fijado al directorio raíz del repositorio.
428 Cada parámetro para el gancho es pasado como una variable de entorno;
429 el nombre está en mayúsculas, y tiene como prefijo la cadena
430 ``\texttt{HG\_}''.
432 Con la excepción de los parámetros para los ganchos, Mercurial no
433 define o modifica ninguna variable de entorno al ejecutar un gancho.
434 Es útil recordar esto al escribir un gancho global que podría ser
435 ejecutado por varios usuarios con distintas variables de entorno
436 fijadas. En situaciones con múltiples usuarios, usted no debería
437 asumir la existencia de ninguna variable de entorno, ni que sus
438 valores sean los mismos que tenían cuando usted probó el gancho en su
439 ambiente de trabajo.
441 \subsection{Indicar a Mercurial que use un gancho interno}
443 La sintaxis para definir un gancho interno en el fichero \hgrc\ es
444 ligeramente diferente de la usada para un gancho externo. El valor del
445 gancho debe comenzar con el texto ``\texttt{python:}'', y continuar
446 con el nombre completamente cualificado de un objeto invocable que se
447 usará como el valor del gancho.
449 El módulo en que vive un gancho es importado automáticamente cuando se
450 ejecuta un gancho. Siempre que usted tenga el nombre del módulo y la
451 variable de entorno \envar{PYTHONPATH} ajustada adecuadamente, todo
452 debería funcionar sin problemas.
454 El siguiente fragmento de ejemplo de un fichero \hgrc\ ilustra la
455 sintaxis y significado de los conceptos que acabamos de describir.
456 \begin{codesample2}
457 [hooks]
458 commit.example = python:mymodule.submodule.myhook
459 \end{codesample2}
460 Cuando Mercurial ejecuta el gancho \texttt{commit.example}, importa
461 \texttt{mymodule.submodule}, busca el objeto invocable llamado
462 \texttt{myhook}, y lo invoca (llama).
464 \subsection{Escribir un gancho interno}
466 El gancho interno más sencillo no hace nada, pero ilustra la
467 estructura básica de la API\ndt{\emph{Application Progamming
468 Interface}, Interfaz para Programación de Aplicaciones} para ganchos:
469 \begin{codesample2}
470 def myhook(ui, repo, **kwargs):
471 pass
472 \end{codesample2}
473 El primer argumento para un gancho Python siempre es un objeto
474 \pymodclass{mercurial.ui}{ui}. El segundo es un objeto repositorio;
475 de momento, siempre es una instancia de
476 \pymodclass{mercurial.localrepo}{localrepository}. Después de estos
477 dos argumentos están los argumentos de palabra clave. Los argumentos
478 que se pasen dependerán del tipo de gancho que se esté llamando, pero
479 un gancho siempre puede ignorar los argumentos que no le interesen,
480 relegándolos a un diccionario de argumentos por palabras clave, como se
481 hizo arriba con \texttt{**kwargs}.
483 \section{Ejemplos de ganchos}
485 \subsection{Escribir mensajes de consignación significativos}
487 Es difícil de imaginar un mensaje de consignación útil y al mismo
488 tiempo muy corto. El simple gancho \hook{pretxncommit} de la
489 figura~\ref{ex:hook:msglen.go} evitará que usted consigne un conjunto
490 de cambios con un mensaje de menos de 10 bytes de longitud.
492 \begin{figure}[ht]
493 \interaction{hook.msglen.go}
494 \caption{Un gancho que prohíbe mensajes de consignación demasiado
495 cortos}
496 \label{ex:hook:msglen.go}
497 \end{figure}
499 \subsection{Comprobar espacios en blanco finales}
501 Un uso interesante para ganchos relacionados con consignaciones es
502 ayudarle a escribir código más limpio. Un ejemplo simple de
503 %TODO dictum => regla
504 ``código más limpio'' es la regla de que un cambio no debe añadir
505 líneas de texto que contengan ``espacios en blanco finales''. El
506 espacio en blanco final es una serie de caracteres de espacio y
507 tabulación que se encuentran al final de una línea de texto. En la
508 mayoría de los casos, el espacio en blanco final es innecesario, ruido
509 invisible, pero ocasionalmente es problemático, y la gente en general
510 prefiere deshacerse de él.
512 Usted puede usar cualquiera de los ganchos \hook{precommit} o
513 \hook{pretxncommit} para revisar si tiene el problema de los espacios
514 en blanco finales. Si usa el gancho \hook{precommit}, el gancho no
515 sabrá qué ficheros se están consignando, por lo que se tendrá que
516 revisar cada fichero modificado en el repositorio para ver si tiene
517 espacios en blanco finales. Si usted sólo quiere consignar un cambio
518 al fichero \filename{foo}, y el fichero \filename{bar} contiene
519 espacios en blanco finales, hacer la revisión en el gancho
520 \hook{precommit} evitará que usted haga la consignación de
521 \filename{foo} debido al problem en \filename{bar}. Este no parece el
522 enfoque adeucado.
524 Si usted escogiera el gancho \hook{pretxncommit}, la revisión no
525 ocurriría sino hasta justo antes de que la transacción para la
526 consignación se complete. Esto le permitirá comprobar por posibles
527 problemas sólo en los ficheros que serán consignados. Sin embargo, si
528 usted ingresó el mensaje de consignación de manera interactiva y el
529 %TODO roll-back
530 gancho falla, la transacción será deshecha; usted tendrá que
531 reingresar el mensaje de consignación luego de que corrija el problema
532 con los espacios en blanco finales y ejecute \hgcmd{commit} de nuevo.
534 \begin{figure}[ht]
535 \interaction{hook.ws.simple}
536 \caption{Un gancho simple que revisa si hay espacios en blanco
537 finales}
538 \label{ex:hook:ws.simple}
539 \end{figure}
541 La figura~\ref{ex:hook:ws.simple} presenta un gancho
542 \hook{pretxncommit} simple que comprueba la existencia de espacios en
543 blanco finales. Este gancho es corto, pero no brinda mucha ayuda.
544 Termina con un código de salida de error si un cambio añade una línea
545 con espacio en blanco final a cualquier fichero, pero no muestra
546 ninguna información que pueda ser útil para identificar el fichero o
547 la línea de texto origen del problema. También tiene la agradable
548 propiedad de no prestar atención a las líneas que no sufrieron
549 modificaciones; sólo las líneas que introducen nuevos espacios en
550 blanco finales causan problemas.
552 \begin{figure}[ht]
553 \interaction{hook.ws.better}
554 \caption{Un mejor gancho para espacios en blanco finales}
555 \label{ex:hook:ws.better}
556 \end{figure}
558 El ejemplo de la figura~\ref{ex:hook:ws.better} es mucho más complejo,
559 pero también más útil. El gancho procesa un diff unificado para
560 revisar si alguna línea añade espacios en blanco finales, e imprime el
561 nombre del fichero y el número de línea de cada ocurrencia. Aún mejor,
562 si el cambio añade espacios en blanco finales, este gancho guarda el
563 mensaje de consignación e imprime el nombre del fichero en el que el
564 mensaje fue guardado, antes de terminar e indicarle a Mercurial que
565 deshaga la transacción, para que uste pueda usar
566 \hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{nombre\_fichero}} para
567 reutilizar el mensaje de consignación guardado anteriormente, una vez
568 usted haya corregido el problema.
570 Como anotación final, note en la figura~\ref{ex:hook:ws.better} el
571 %TODO on-site => in-situ ?
572 uso de la característica de edición \emph{in-situ} de \command{perl}
573 para eliminar los espacios en blanco finales en un fichero. Esto es
574 lo suficientemente conciso y poderoso para que lo presente aquí.
575 % TODO corregí el backslash, y comprobé por mi cuenta un archivo
576 % aparte, y el comando hace lo que debe hacer. Favor copiar del pdf el
577 % comando perl y comprobar con un archivo con espacios en blanco
578 % finales, y si todo está bien (que debería), borrar esta nota
579 \begin{codesample2}
580 perl -pi -e 's,\textbackslash{}s+\$,,' nombre\_fichero
581 \end{codesample2}
583 \section{Ganchos adicionales}
585 Mercurial se instala con varios ganchos adicionales. Usted puede
586 encontrarlos en el directorio \dirname{hgext} del árbol de ficheros
587 fuente de Mercurial. Si usted está usando un paquete binario de
588 Mercurial, los ganchos estarán ubicados en el directorio
589 \dirname{hgext} en donde su instalador de paquetes haya puesto a
590 Mercurial.
592 \subsection{\hgext{acl}---control de acceso a partes de un repositorio}
594 La extensión \hgext{acl} le permite controlar a qué usuarios remotos
595 les está permitido empujar conjuntos de cambios a un servidor en red.
596 Usted puede proteger cualquier porción de un repositorio (incluyendo
597 el repositorio completo), de tal manera que un usuario remoto
598 específico pueda empujar cambios que no afecten la porción protegida.
600 Esta extensión implementa control de acceso basado en la identidad del
601 usuario que empuja los conjuntos de cambios, \emph{no} en la identidad
602 de quien hizo la consignación de los mismos. Usar este gancho tiene
603 sentido sólo si se tiene un servidor adecuadamente asegurado que
604 autentique a los usuarios remotos, y si usted desea segurarse de que
605 sólo se le permita a ciertos usuarios empujar cambios a dicho
606 servidor.
608 \subsubsection{Configuración del gancho \hook{acl}}
610 Para administrar los conjuntos de cambios entrantes, se debe usar el
611 gancho \hgext{acl} como un gancho de tipo \hook{pretxnchangegroup}.
612 Esto le permite ver qué ficheros son modificados por cada conjunto de
613 %TODO rollback => "deshacer el efecto"
614 cambios entrante, y deshacer el efecto de un grupo de conjuntos de
615 cambios si alguno de ellos modifica algún fichero ``prohibido''.
616 Ejemplo:
617 \begin{codesample2}
618 [hooks]
619 pretxnchangegroup.acl = python:hgext.acl.hook
620 \end{codesample2}
622 La extensión \hgext{acl} es configurada mediante tres secciones.
624 La sección \rcsection{acl} sólo tiene una entrada,
625 \rcitem{acl}{sources}\ndt{Fuentes.}, que lista las fuentes de los
626 conjuntos de cambios entrantes a las que el gancho debe prestar
627 atención. Usualmente usted no necesita configurar esta sección.
628 \begin{itemize}
629 \item[\rcitem{acl}{serve}] Controlar conjuntos de
630 cambios entrantes que están llegando desde un repositorio a
631 través de http o ssh. Este es el valor por defecto de
632 \rcitem{acl}{sources}, y usualmente es el único valor de
633 configuración que necesitará para este ítem.
634 \item[\rcitem{acl}{pull}] Controlar conjuntos de cambios entrantes que
635 lleguen vía un pull (jalado) desde un repositorio local.
636 \item[\rcitem{acl}{push}] Controlar conjuntos de cambios entrantes que
637 lleguen vía un push (empuje) desde un repositorio local.
638 \item[\rcitem{acl}{bundle}] Controlar conjuntos de cambios entrantes
639 %TODO bundle
640 que lleguen desde otro repositorio a través de un paquete.
641 \end{itemize}
643 La sección \rcsection{acl.allow} controla los usuarios a los que les
644 está permitido añadir conjuntos de cambios al repositorio. Si esta
645 sección no está presente, se le permite acceso a todos los usuarios
646 excepto a los que se les haya negado explícitamente el acceso. Si
647 esta sección no está presente, se niega el acceso a todos los usuarios
648 excepto a todos a los que se les haya permitido de manera explícita
649 (así que una sección vacía implica que se niega el acceso a todos los
650 usuarios).
652 La sección \rcsection{acl.deny} determina a qué usuarios no se les
653 permite añadir conjuntos de cambios al repositorio. Si esta sección no
654 está presente o está vacía, no se niega el acceso a ningún usuario.
656 La sintaxis para los ficheros \rcsection{acl.allow} y
657 \rcsection{acl.deny} es idéntica. A la izquierda de cada entrada se
658 encuentra un patrón glob que asocia ficheros o directorios, respecto a
659 la raíz del repositorio; a la derecha, un nombre usuario.
661 En el siguiente ejemplo, el usuario \texttt{escritordoc} sólo puede
662 empujar cambios al directorio \dirname{docs} del repositorio, mientras
663 que \texttt{practicante} puede enviar cambios a cualquier fichero o
664 directorio excepto \dirname{fuentes/sensitivo}.
665 \begin{codesample2}
666 [acl.allow]
667 docs/** = escritordoc
669 [acl.deny]
670 fuentes/sensitivo/** = practicante
671 \end{codesample2}
673 \subsubsection{Pruebas y resolución de problemas}
675 Si usted desea probar el gancho \hgext{acl}, ejecútelo habilitando la
676 opción de salida de depuración habilitada. Ya que usted probablemente
677 lo estará ejecutando en un servidor donde no es conveniente (o incluso
678 posible) pasar la opción \hggopt{--debug}, no olvide que usted puede
679 habilitar la salida de depuración en su \hgrc:
680 \begin{codesample2}
681 [ui]
682 debug = true
683 \end{codesample2}
684 Con esto habilitado, el gancho \hgext{acl} imprimirá suficiente
685 información para permitirle saber porqué está permitiendo o denegando
686 la operación de empujar a usuarios específicos.
688 \subsection{\hgext{bugzilla}---integración con Bugzilla}
690 La extensión \hgext{bugzilla} añade un comentario a un fallo Bugzilla
691 siempre que encuentre una referencia al ID de dicho fallo en un
692 mensaje de consignación. Usted puede instalar este gancho en un
693 servidor compartido, para que cada vez que un usuario remoto empuje
694 cambios al servidor, el gancho sea ejecutado.
696 Se añade un comentario al fallo que se ve así (usted puede configurar
697 los contenidos del comentario---vea más abajo):
698 %TODO traducir?
699 \begin{codesample2}
700 Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
701 the frobnitz repository, refers to this bug.
703 For complete details, see
704 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
706 Changeset description:
707 Fix bug 10483 by guarding against some NULL pointers
708 \end{codesample2}
709 El valor de este gancho se encuentra en que automatiza el proceso de
710 actualizar un fallo cuando un conjunto de cambios se refiera a él. Si
711 usted configura este gancho adecuadamente, hará fácil para la gente
712 navegar directamente desde un fallo Bugzilla a un conjunto de cambios
713 que se refiere a ese fallo.
715 Usted puede usar el código de este gancho como un punto de partida
716 para otras recetas de integración con Bugzilla aún más exóticas. Acá
717 hay algunas posibilidades:
718 \begin{itemize}
719 \item Requerir que cada conjunto de cambios tenga un ID de fallo en su
720 mensaje de consignación. En este caso, usted querrá configurar el
721 gancho como uno de tipo \hook{pretxncommit}. Esto le permitirá al
722 gancho rechazar cambios que no contiene IDs de fallos.
723 \item Permitir a los conjuntos de cambios entrantes modificar
724 automáticamente el \emph{estado} de un fallo, así como simplemente
725 añadir un comentario. Por ejemplo, el gancho podría reconocer la
726 cadena ``corregido fallo 31337'' como la señal de que debería
727 actualizar el estado del fallo 31337 a ``requiere pruebas''.
728 \end{itemize}
730 \subsubsection{Configuración del gancho \hook{bugzilla}}
731 \label{sec:hook:bugzilla:config}
733 Usted debería configurar este gancho en el \hgrc\ de su servidor como
734 un gancho \hook{incoming}\ndt{Entrante.}, por ejemplo como sigue:
735 \begin{codesample2}
736 [hooks]
737 incoming.bugzilla = python:hgext.bugzilla.hook
738 \end{codesample2}
740 Debido a la naturaleza especializada de este gancho, y porque Bugzilla
741 no fue escrito con este tipo de integración en mente, configurar este
742 % TODO involved => complejo ? no intarwebs here :(
743 gancho es un proceso algo complejo.
745 Antes de empezar, usted debe instalar la interfaz de Python para MySQL
746 en los sistemas en los que se vaya a ejecutar el gancho. Si no está
747 disponible como paquete binario para su sistema, usted puede descargar
748 el paquete desde~\cite{web:mysql-python}.
750 La información para configurar este gancho se ubica en la sección
751 \rcsection{bugzilla} de su \hgrc.
752 \begin{itemize}
753 \item[\rcitem{bugzilla}{version}] La versión de Bugzilla instalada en
754 el servidor. El esquema de base de datos que Bugzilla usa cambia
755 ocasionalmente, así que este gancho debe saber exactamente qué
756 esquema usar. A la fecha, la única versión soportada es la
757 \texttt{2.16}.
758 \item[\rcitem{bugzilla}{host}] El nombre de máquina (\emph{hostname})
759 del servidor MySQL que almacena sus datos Bugzilla. La base de datos
760 debe ser configurada para permitir conexiones desde las máquinas en
761 las que usted ejecute el gancho \hook{bugzilla}.
762 \item[\rcitem{bugzilla}{user}] El nombre de usuario que se usará para
763 conectarse al servidor MySQL. La base de datos debe ser configurada
764 para permitir a dicho usuario conectarse desde cualquiera de las
765 máquinas en las que se ejecute el gancho \hook{bugzilla}. Este
766 usuario debe tener acceso y poder modificar las tablas de Bugzilla.
767 El valor por defecto para este ítem es \texttt{bugs}, que es el
768 nombre estándar del usuario para Bugzilla en una base de datos
769 MySQL.
770 \item[\rcitem{bugzilla}{password}] La contraseña MySQL para el usuario
771 configurado anteriormente. Ésta es almacenada como texto plano, así
772 que usted deberá asegurarse de que los usuarios no autorizados no
773 puedan leer el fichero \hgrc\ en donde usted guarda esta
774 información.
775 \item[\rcitem{bugzilla}{db}] El nombre de la base de datos Bugzilla en
776 el servidor MySQL. El nombre por defecto para este ítem es
777 \texttt{bugs}, que es el nombre estándar de la base de datos MySQL
778 en donde Bugzilla almacena sus datos.
779 \item[\rcitem{bugzilla}{notify}] Si usted desea que Bugzilla envíe un
780 %TODO suBscriptores?
781 correo de notificación a los suscriptores después de que el gancho
782 haya añadido un comentario a un fallo, necesitará que este gancho
783 ejecute un comando siempre que actualice la base de datos. El
784 comando que se ejecute depende de en dónde haya sido instalado
785 Bugzilla, pero típicamente se verá así, si usted ha instalado
786 Bugzilla en \dirname{/var/www/html/bugzilla}:
787 \begin{codesample4}
788 cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
789 \end{codesample4}
790 El programa \texttt{processmail} de Bugzilla espera recibir un ID de
791 fallo (el gancho reemplaza ``\texttt{\%s}'' por el ID del fallo) y
792 una dirección de correo. También espera poder escribir a ciertos
793 ficheros en el directorio en que se ejecuta. Si Bugzilla y éste
794 gancho no están instalados en la misma máquina, usted deberá
795 encontrar una manera de ejecutar \texttt{processmail} en el servidor
796 donde está instalado Bugzilla.
797 \end{itemize}
799 \subsubsection{Asociar nombres de consignadores a nombres de usuario
800 Bugzilla}
802 Por defecto, el gancho \hgext{bugzilla} trata de usar la dirección de
803 correo electrónico de la persona que hizo la consignación del conjunto
804 de cambios como el nombre de usuario Bugzilla con el cual debe
805 actualizar el fallo. Si esto no se ajusta a sus necesidades, es
806 posible asociar direcciones de correo a nombres de usuario Bugzilla
807 usando una sección \rcsection{usermap}.
809 Cada ítem en la sección \rcsection{usermap} contiene una dirección de
810 correo electrónico a la izquierda, y un nombre de usuario Bugzilla a
811 la derecha.
812 \begin{codesample2}
813 [usermap]
814 jane.user@example.com = jane
815 \end{codesample2}
816 Usted puede mantener los datos de \rcsection{usermap} en un fichero
817 \hgrc, o decirle al gancho \hgext{bugzilla} que lea la información
818 desde un fichero \filename{usermap} externo. En este caso, usted
819 puede almacenar los datos de \filename{usermap} en (por ejemplo) un
820 repositorio modificable por los usuarios. Esto hace posible para sus
821 usuarios mantener sus propias entradas \rcitem{bugzilla}{usermap}. El
822 fichero \hgrc\ principal se vería así:
823 \begin{codesample2}
824 # fichero hgrc normal se refiere a un fichero usermap externo
825 [bugzilla]
826 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
827 \end{codesample2}
828 Mientras que el fichero \filename{usermap} al que se hace referencia
829 se vería así:
830 \begin{codesample2}
831 # bugzilla-usermap.conf - dentro de un repositorio hg
832 [usermap]
833 stephanie@example.com = steph
834 \end{codesample2}
836 \subsubsection{Configurar el texto que se añade a un fallo}
838 Usted puede configurar el texto que este gancho añade como comentario;
839 usted los especifica como una plantilla Mercurial. Varias entradas
840 \hgrc\ (aún en la sección \rcsection{bugzilla}) controlan este
841 comportamiento.
842 \begin{itemize}
843 \item[\texttt{strip}] La cantidad de elementos iniciales de ruta a
844 remover de un nombre de ruta del repositorio para construir una ruta
845 parcial para una URL. Por ejemplo, si los repositorios en su
846 servidor se ubican en \dirname{/home/hg/repos}, y usted tiene un
847 repositorio cuya ruta es \dirname{/home/hg/repos/app/tests},
848 entonces fijar \texttt{strip} a \texttt{4} resultará en una ruta
849 parcial de \dirname{app/tests}. El gancho hará disponible esta ruta
850 parcial cuando expanda una plantilla, como \texttt{webroot}.
851 \item[\texttt{template}] El texto de la plantilla a usar. En adición a
852 las variables usuales relacionadas con conjuntos de cambios, esta
853 plantilla puede usar \texttt{hgweb} (el valor del ítem de
854 configuración \texttt{hgweb} de arriba) y \texttt{webroot} (la ruta
855 construida usando \texttt{strip} arriba).
856 \end{itemize}
858 Adicionalmente, usted puede añadir un ítem \rcitem{web}{baseurl} a la
859 sección \rcsection{web} de su \hgrc. El gancho \hgext{bugzilla}
860 publicará esto cuando expanda una plantilla, como la cadena base a
861 usar cuando se construya una URL que le permita a los usuarios navegar
862 desde un comentario de Bugzilla a la vista de un conjunto de cambios.
863 Ejemplo:
864 \begin{codesample2}
865 [web]
866 baseurl = http://hg.domain.com/
867 \end{codesample2}
869 A continuación se presenta un ejemplo completo de configuración para
870 el gancho \hgext{bugzilla}.
871 %TODO traducir?
872 \begin{codesample2}
873 [bugzilla]
874 host = bugzilla.example.com
875 password = mypassword
876 version = 2.16
877 # server-side repos live in /home/hg/repos, so strip 4 leading
878 # separators
879 strip = 4
880 hgweb = http://hg.example.com/
881 usermap = /home/hg/repos/notify/bugzilla.conf
882 template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
883 repo, refers to this bug.\\nFor complete details, see
884 \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
885 description:\\n\\t\{desc|tabindent\}
886 \end{codesample2}
888 \subsubsection{Pruebas y resolución de problemas}
890 Los problemas más comunes que aparecen en la configuración del gancho
891 \hgext{bugzilla} suelen estar relacionados con la ejecución del guión
892 de Bugzilla \filename{processmail} y la asociación de nombres de
893 consignadores a nombres de usuario.
895 Recuerde que en la sección~\ref{sec:hook:bugzilla:config} arriba el
896 usuario que ejecuta el proceso Mercurial en el servidor es también
897 el usuario que ejecutará el guión \filename{processmail}. El guión
898 \filename{processmail} algunas veces hace que Bugzilla escriba en
899 ficheros en su directorio de configuración, y los ficheros de
900 configuración de Bugzilla usualmente son propiedad del usuario bajo el
901 cual se ejecuta el servidor web.
903 Usted puede hacer que \filename{processmail} sea ejecutado con la
904 identidad del usuario adecuado usando el comando \command{sudo}. A
905 continuación se presenta una entrada de ejemplo para un fichero
906 \filename{sudoers}.
907 \begin{codesample2}
908 hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
909 \end{codesample2}
910 Esto permite que el usuario \texttt{hg\_user} ejecute el programa
911 \filename{processmail-wrapper} con la identidad del usuario
912 \texttt{httpd\_user}.
914 Esta indirección a través de un guión envoltorio es necesaria, porque
915 \filename{processmail} espera que al ser ejecutado su directorio
916 actual sea aquel en el cual se instaló Bugzilla; usted no puede
917 especificar ese tipo de condición en un fichero \filename{sudoers}.
918 Los contenidos del giuón envoltorio son simples:
919 \begin{codesample2}
920 #!/bin/sh
921 cd `dirname $0` && ./processmail "$1" nobody@example.com
922 \end{codesample2}
923 No parece importar qué dirección de correo se le pase a
924 \filename{processmail}.
926 Si su \rcsection{usermap} no es configurada correctamente, los
927 usuarios verán un mensaje de error del gancho \hgext{bugzilla} cuando
928 empujen cambios al servidor. El mensaje de error se verá así:
929 \begin{codesample2}
930 cannot find bugzilla user id for john.q.public@example.com
931 \end{codesample2}
932 Lo que esto quiere decir es que la dirección del consignador,
933 \texttt{john.q.public@example.com}, no es un nombre de usuario
934 Bugzilla válido, ni tiene una entrada en su \rcsection{usermap} que lo
935 asocie con un nombre de usuario válido Bugzilla.
937 \subsection{\hgext{notify}---enviar notificaciones de correo
938 electrónico}
940 %TODO feeds => notificaciones: lo más fácil es mirar en wikipedia
941 Aunque el servidor web embebido de Mercurial provee notificaciones de
942 cambios en cada repositorio, muchas personas prefieren recibir las
943 notificaciones de cambios vía correo electrónico. El gancho
944 \hgext{notify}\ndt{Notificación.} le permite a usted enviar
945 notificaciones a un conjunto de direcciones de correo cuando lleguen
946 conjuntos de cambios en los que los subscriptores estén interesados.
948 De la misma forma que con el gancho \hgext{bugzilla}, el gancho
949 \hgext{notify} está orientado a plantillas, así que usted puede
950 personalizar los contenidos del mensaje de notificación que se envía.
952 Por defecto, el gancho \hgext{notify} incluye un diff de cada conjunto
953 %TODO que se envía? revisar, pienso que es ``que se recibe''
954 de cambios que se envía; usted puede limitar el tamaño del diff, o
955 desactivar completamente esta característica. Es útil para permitir a
956 los subscriptores revisar los cambios inmediatamente, en vez de tener
957 que hacer clic para visitar una URL.
959 \subsubsection{Configuración del gancho \hgext{notify}}
961 Usted puede configurar el gancho \hgext{notify} para enviar un mensaje
962 de correo por conjunto de cambios entrante, o uno por grupo entrante
963 de conjuntos de cambios (todos los que llegaron en un único empuje o
964 jalado).
965 \begin{codesample2}
966 [hooks]
967 # enviar un correo por grupo de cambios
968 changegroup.notify = python:hgext.notify.hook
969 # enviar un correo por cambio
970 incoming.notify = python:hgext.notify.hook
971 \end{codesample2}
973 La información para configurar este gancho se ubica en la sección
974 \rcsection{notify} de un fichero \hgrc.
975 \begin{itemize}
976 \item[\rcitem{notify}{test}] Por defecto, este gancho no envía correos
977 en absoluto; en vez de eso, imprime el mensaje que se
978 \emph{enviaría}. Fije este ítem en \texttt{false} para permitir el
979 envío de correos. El motivo por el que el envío de correos está
980 desactivado es que hacen falta varios intentos para configurar esta
981 extensión exactamente como usted desea, y sería maleducado enviar a
982 los subscriptores una cantidad de notificaciones ``rotas'' mientras
983 usted depura su configuración.
984 \item[\rcitem{notify}{config}] La ruta a un fichero de configuración
985 que contiene información de subscripción. Esto se mantiene separado
986 del \hgrc\ principal para que usted pueda mantenerlo en un
987 repositorio. La gente puede clonar ese repositorio, actualizar sus
988 subscripciones, y empujar los cambios de vuelta a su servidor.
989 \item[\rcitem{notify}{strip}] La cantidad de caracteres iniciales de
990 separación de ruta a remover de la ruta del repositorio, al decidir
991 si un repositorio tiene subscriptores. Por ejemplo, si los
992 repositorios en su servidor están en \dirname{/home/hg/repos}, y
993 \hgext{notify} está trabajando con un repositorio llamado
994 \dirname{/home/hg/repos/shared/test}, fijar \rcitem{notify}{strip} a
995 \texttt{4} hará que \hgext{notify} elimine las partes iniciales de
996 la ruta hasta \dirname{shared/test}, y asociará los subscriptores
997 frente a dicha ruta.
998 \item[\rcitem{notify}{template}] El texto de plantilla a usar cuando
999 se envíen mensajes. Especifica los contenidos de la cabecera del
1000 mensaje y el cuerpo del mismo.
1001 \item[\rcitem{notify}{maxdiff}] El número máximo de líneas de datos de
1002 diff a añadir al final de un mensaje. Si la longitud de un diff es
1003 mayor a eso, se trunca. Por defecto, está fijado en 300. Fije esto a
1004 \texttt{0} para omitir los diffs en los correos de notificación.
1005 \item[\rcitem{notify}{sources}] Una lista de fuentes de conjuntos de
1006 cambios a considerar. Esto le permite a usted indicar a
1007 \hgext{notify} para que sólo envíe correos acerca de cambios que
1008 usuarios remotos hayan empujado al repositorio vía un servidor, por
1009 ejemplo. Vea la sección~\ref{sec:hook:sources} para las fuentes que
1010 usted puede especificar aquí.
1011 \end{itemize}
1013 Si usted fija el ítem \rcitem{web}{baseurl} en la sección
1014 \rcsection{web}, usted lo puede usar en una plantilla; estará
1015 disponible como \texttt{webroot}.
1017 A continuación se presenta un ejemplo completo de configuración para
1018 el gancho \hgext{notify}.
1019 \begin{codesample2}
1020 [notify]
1021 # enviar correo
1022 test = false
1023 # datos de subscriptores están en el repositorio notify
1024 config = /home/hg/repos/notify/notify.conf
1025 # repos están en /home/hg/repos on server, así que elimine 4
1026 # caracteres"/"
1027 strip = 4
1028 template = X-Hg-Repo: \{webroot\}
1029 Subject: \{webroot\}: \{desc|firstline|strip\}
1030 From: \{author\}
1032 changeset \{node|short\} in \{root\}
1033 details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
1034 description:
1035 \{desc|tabindent|strip\}
1037 [web]
1038 baseurl = http://hg.example.com/
1039 \end{codesample2}
1041 Esto producirá un mensaje que se verá como el siguiente:
1042 \begin{codesample2}
1043 X-Hg-Repo: tests/slave
1044 Subject: tests/slave: Handle error case when slave has no buffers
1045 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
1047 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
1048 details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
1049 description:
1050 Handle error case when slave has no buffers
1051 diffs (54 lines):
1053 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
1054 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
1055 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
1056 @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
1057 [...snip...]
1058 \end{codesample2}
1060 \subsubsection{Pruebas y resolución de problemas}
1062 No olvide que por defecto, la extensión \hgext{notify} \emph{no
1063 enviará ningún correo electrónico} hasta que usted la configure
1064 explícitamente para hacerlo, fijando el valor de \rcitem{notify}{test}
1065 a \texttt{false}. Hasta que usted haga eso, simplemente se imprimirá
1066 el mensaje que se \emph{enviaría}.
1068 \section{Información para escritores de ganchos}
1069 \label{sec:hook:ref}
1071 \subsection{Ejecución de ganchos internos}
1073 Un gancho interno es llamado con argumentos de la siguiente forma:
1074 \begin{codesample2}
1075 def myhook(ui, repo, **kwargs):
1076 pass
1077 \end{codesample2}
1078 El parámetro \texttt{ui} es un objeto \pymodclass{mercurial.ui}{ui}.
1079 El parámetro \texttt{repo} es un objeto
1080 \pymodclass{mercurial.localrepo}{localrepository}. Los nombres y
1081 valores de los parámetros en \texttt{**kwargs} dependen del gancho que
1082 se invoque, con las siguientes características en común:
1083 \begin{itemize}
1084 \item Si hay un parámetro llamado \texttt{node} o
1085 \texttt{parent\emph{N}}, contendrá un ID hexadecimal de un conjunto
1086 de cambios. La cadena vacía es usada para representar un
1087 ``ID de conjunto de cambios nulo'' en vez de una cadena de ceros.
1088 \item Si hay un parámetro llamado \texttt{url}, contendrá la URL de un
1089 repositorio remoto, si puede ser determinada.
1090 \item Los parámetros booleanos son representados como objetos
1091 \texttt{bool} de Python.
1092 \end{itemize}
1094 Un gancho interno es ejecutado sin cambiar el directorio de trabajo
1095 del proceso (a diferencia de los ganchos externos, que son ejecutados
1096 desde la raíz del repositorio). El gancho no debe cambiar el
1097 directorio de trabajo del proceso, porque esto haría que falle
1098 cualquier llamada que se haga a la API de Mercurial.
1100 Si un gancho retorna el valor booleano ``false''\ndt{Falso.}, se
1101 considera que éste tuvo éxito. Si retorna
1102 ``true''\ndt{Verdadero.} o genera una excepción, se considera que
1103 ha fallado. Una manera útil de pensar en esta convención de llamado es
1104 ``dígame si usted falló''.
1106 Note que los IDs de conjuntos de cambios son pasados a los ganchos de
1107 Python como cadenas hexadecimales, no como los hashes binarios que la
1108 API de Mercurial usa normalmente. Para convertir un hash de
1109 hexadecimal a binario, use la función \pymodfunc{mercurial.node}{bin}.
1111 \subsection{Ejecución de ganchos externos}
1113 Un gancho externo es pasado al intérprete de comandos del usuario bajo
1114 el cual se ejecuta Mercurial. Las características del intérprete, como
1115 sustitución de variables y redirección de comandos, están disponibles.
1116 El gancho es ejecutado desde el directorio raíz del repositorio
1117 (a diferencia de los ganchos internos, que se ejecutan desde el mismo
1118 directorio en que Mercurial fue ejecutado).
1120 Los parámetros para el gancho se pasan como variables de entorno. El
1121 nombre de cada variable de entorno se pasa a mayúsculas y se le añade
1122 el prefijo ``\texttt{HG\_}''. Por ejemplo, si el nombre de un
1123 parámetro es ``\texttt{node}'', el nombre de la variable de entorno
1124 que almacena el parámetro se llamará ``\texttt{HG\_NODE}''.
1126 Un parámetro booleano se representa con la cadena ``\texttt{1}'' para
1127 ``true'', ``\texttt{0}'' para ``false''. Si una variable se llama
1128 \envar{HG\_NODE}, \envar{HG\_PARENT1} o \envar{HG\_PARENT2},
1129 contendrá un ID de conjunto de cambios representado como una cadena
1130 hexadecimal. La cadena vacía es usada para representar un ``ID de
1131 conjunto de cambios nulo'' en vez de una cadena de ceros. Si una
1132 variable de entorno se llama \envar{HG\_URL}, contendrá la URL de un
1133 repositorio remoto, si puede ser determinada.
1135 Si un gancho termina con un código de salida de cero, se considera que
1136 tuvo éxito. Si termina con un código de salida diferente de cero, se
1137 considera que falló.
1139 \subsection{Averiguar de dónde vienen los conjuntos de cambios}
1140 %TODO los trae la cigüeña. De París. Y quedan debajo de una col.
1142 Un gancho que involucra la transferencia de conjuntos de cambios entre
1143 un repositorio local y otro puede ser capaz de averiguar información
1144 acerca de ``el otro lado''. Mercurial sabe \emph{cómo} son
1145 transferidos los conjuntos de cambios, y en muchos casos también desde
1146 o hacia donde están siendo transferidos.
1148 \subsubsection{Fuentes de conjuntos de cambios}
1149 \label{sec:hook:sources}
1151 Mercurial le indicará a un gancho cuáles son, o fueron, los medios
1152 usados para transferir los conjuntos de cambios entre repositorios.
1153 Esta información es provista por Mercurial en un parámetro Python
1154 llamado \texttt{source}\ndt{Fuente.}, o una variable de entorno
1155 llamada \envar{HG\_SOURCE}.
1157 \begin{itemize}
1158 \item[\texttt{serve}] Los conjuntos de cambios son transferidos desde
1159 o hacia un repositorio remoto a través de http o ssh.
1160 \item[\texttt{pull}] Los conjuntos de cambios son transferidos vía una
1161 operación de jalado de un repositorio a otro.
1162 \item[\texttt{push}] Los conjuntos de cambios son transferidos vía un
1163 empuje de un repositorio a otro.
1164 \item[\texttt{bundle}] Los conjuntos de cambios son transferidos desde
1165 %TODO bundle
1166 o hacia un paquete.
1167 \end{itemize}
1169 \subsubsection{A dónde van los cambios---URLs de repositorios remotos}
1170 \label{sec:hook:url}
1171 %TODO al cielo? no, ésos son los perros
1173 Cuando es posible, Mercurial le indicará a los ganchos la ubicación de
1174 ``el otro lado'' de una actividad que transfiera datos de conjuntos de
1175 cambios entre repositorios. Esto es provisto por Mercurial en un
1176 parámetro Python llamado \texttt{url}, o en una variable de entorno
1177 llamada \envar{HG\_URL}.
1179 No siempre esta información está disponible. Si un gancho es invocado
1180 un repositorio que es servido a través de http o ssh, Mercurial no
1181 puede averiguar dónde está el repositorio remoto, pero puede saber
1182 desde dónde se conecta el cliente. En esos casos, la URL tendrá una de
1183 las siguientes formas:
1184 \begin{itemize}
1185 \item \texttt{remote:ssh:\emph{ip-address}}---cliente ssh remoto, en
1186 la dirección IP dada.
1187 \item \texttt{remote:http:\emph{ip-address}}---cliente remoto http, en
1188 la dirección IP dada. Si el cliente está usando SSL, tendrá la forma
1189 \texttt{remote:https:\emph{ip-address}}.
1190 \item Vacío---no se pudo descubrir información acerca del cliente
1191 remoto.
1192 \end{itemize}
1194 \section{Referencia de ganchos}
1196 \subsection{\hook{changegroup}---luego de añadir conjuntos de cambios
1197 remotos}
1198 \label{sec:hook:changegroup}
1200 Este gancho es ejecutado luego de que un grupo de conjuntos de cambios
1201 preexistentes ha sido añadido al repositorio, por ejemplo vía un
1202 \hgcmd{pull} o \hgcmd{unbundle}. Este gancho es ejecutado una vez por
1203 cada operación que añade uno o más conjuntos de cambios. Este gancho
1204 se diferencia del gancho \hook{incoming}, que es ejecutado una vez por
1205 cada conjunto de cambios, sin importar si los cambios llegan en grupo.
1207 Algunos usos posibles para este gancho includen el probar o ensamblar
1208 los conjuntos de cambios añadidos, actualizar una base de datos de
1209 fallos, o notificar a subscriptores de que el repositorio contiene
1210 nuevos cambios.
1212 Parámetros para este gancho:
1213 \begin{itemize}
1214 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer conjunto
1215 de cambios que fue añadido en el grupo. Todos los conjuntos de
1216 cambios entre éste y la punta
1217 %TODO mirar qué hacer con el índice
1218 \index{tags!\texttt{tip}}(\texttt{tip}), inclusive, fueron añadidos
1219 %TODO unbundle
1220 por un único jalado (\hgcmd{pull}), empuje (\hgcmd{push}) o \hgcmd{unbundle}.
1221 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
1222 sección~\ref{sec:hook:sources} para más detalles.
1223 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1224 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1225 \end{itemize}
1227 Veta también: \hook{incoming} (sección~\ref{sec:hook:incoming}),
1228 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup}),
1229 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
1231 \subsection{\hook{commit}---luego de la creación de un nuevo conjunto
1232 de cambios}
1233 \label{sec:hook:commit}
1235 Este gancho es ejecutado luego de la creación de un nuevo conjunto de
1236 cambios.
1238 Parámetros para este gancho:
1239 \begin{itemize}
1240 \item[\texttt{node}] Un ID de conjunto de cambios. El ID de conjunto
1241 de cambios del conjunto de cambios que acabó de ser consignado.
1242 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
1243 conjunto de cambios del primer padre del conjunto de cambios que
1244 acaba de ser consignado.
1245 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
1246 conjunto de cambios del segundo padre del conjunto de cambios que
1247 acaba de ser consignado.
1248 \end{itemize}
1250 Vea también: \hook{precommit} (sección~\ref{sec:hook:precommit}),
1251 \hook{pretxncommit} (sección~\ref{sec:hook:pretxncommit})
1253 \subsection{\hook{incoming}---luego de que un conjunto de cambios
1254 remoto es añadido}
1255 \label{sec:hook:incoming}
1257 Este gancho es ejecutado luego de que un conjunto de cambios
1258 preexistente ha sido añadido al repositorio, por ejemplo, vía un
1259 \hgcmd{push}. Si un grupo de conjuntos de cambios fue añadido en una
1260 sola operación, este gancho es ejecutado una vez por cada conjunto de
1261 cambios añadido.
1263 Usted puede usar este gancho para los mismos fines que el gancho
1264 \hook{changegroup} (sección~\ref{sec:hook:changegroup}); simplemente
1265 algunas veces es más conveniente ejecutar un gancho una vez por cada
1266 grupo de conjuntos de cambios, mientras que otras es más útil correrlo
1267 por cada conjunto de cambios.
1269 Parámetros para este gancho:
1270 \begin{itemize}
1271 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del conjunto
1272 de cambios recién añadido.
1273 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
1274 sección~\ref{sec:hook:sources} para más detalles.
1275 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1276 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1277 \end{itemize}
1279 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup})
1280 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup}),
1281 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
1283 \subsection{\hook{outgoing}---luego de la propagación de los conjuntos
1284 de cambios}
1285 \label{sec:hook:outgoing}
1287 Este gancho es ejecutado luego de que un grupo de conjuntos de cambios
1288 ha sido propagado fuera de éste repositorio, por ejemplo por un
1289 comando \hgcmd{push} o \hgcmd{bundle}.
1291 Un uso posible para este gancho es notificar a los administradores que
1292 los cambios han sido jalados.
1294 Parámetros para este gancho:
1295 \begin{itemize}
1296 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer conjunto
1297 de cambios del grupo que fue enviado.
1298 \item[\texttt{source}] Una cadena. La fuente de la operación (vea la
1299 sección~\ref{sec:hook:sources}). Si un cliente remoto jaló cambios
1300 de este repositorio, \texttt{source} será \texttt{serve}. Si el
1301 cliente que obtuvo los cambios desde este repositorio era local,
1302 \texttt{source} será \texttt{bundle}, \texttt{pull}, o
1303 \texttt{push}, dependiendo de la operación que llevó a cabo el
1304 cliente.
1305 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1306 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1307 \end{itemize}
1309 Vea también: \hook{preoutgoing} (sección~\ref{sec:hook:preoutgoing})
1311 \subsection{\hook{prechangegroup}---antes de empezar la adición de
1312 conjuntos de cambios remotos}
1313 \label{sec:hook:prechangegroup}
1315 Este gancho de control es ejecutado antes de que Mercurial empiece a
1316 añadir un grupo de conjuntos de cambios de otro repositorio.
1318 Este gancho no tiene ninguna información acerca de los conjuntos de
1319 cambios que van a ser añadidos, porque es ejecutado antes de que se
1320 permita que empiece la transmisión de dichos conjuntos de cambios. Si
1321 este gancho falla, los conjuntos de cambios no serán transmitidos.
1323 Un uso para este gancho es prevenir que se añadan cambios externos a un
1324 repositorio. Por ejemplo, usted podría usarlo para ``congelar''
1325 temporal o permanentemente una rama ubicada en un servidor para que
1326 los usuarios no puedan empujar cambios a ella, y permitiendo al mismo
1327 tiempo modificaciones al repositorio por parte de un administrador
1328 local.
1330 Parámetros para este gancho:
1331 \begin{itemize}
1332 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
1333 sección~\ref{sec:hook:sources} para más detalles.
1334 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1335 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1336 \end{itemize}
1338 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup}),
1339 \hook{incoming} (sección~\ref{sec:hook:incoming}), ,
1340 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
1342 \subsection{\hook{precommit}---antes de iniciar la consignación de un
1343 conjunto de cambios}
1344 \label{sec:hook:precommit}
1346 Este gancho es ejecutado antes de que Mercurial inicie la consignación
1347 de un nuevo conjunto de cambios. Es ejecutado antes de que Mercurial
1348 tenga cualquier de los metadatos para la consignación, como los
1349 ficheros a ser consignados, el mensaje de consignación, o la fecha de
1350 consignación.
1352 Un uso para este gancho es deshabilitar la capacidad de consignar
1353 nuevos conjuntos de cambios, pero permitiendo conjuntos de cambios
1354 entrantes. Otro es ejecutar un proceso de ensamble/compilación o
1355 prueba, y permitir la consignación sólo si el ensamble/compilación o
1356 prueba tiene éxito.
1358 Parámetros para este gancho:
1359 \begin{itemize}
1360 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
1361 conjunto de cambios del primer padre del directorio de trabajo.
1362 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
1363 conjunto de cambios del segundo padre del directorio de trabajo.
1364 \end{itemize}
1365 Si la consignación continúa, los padres del directorio de trabajo se
1366 convertirán en los padres del nuevo conjunto de cambios.
1368 Vea también: \hook{commit} (sección~\ref{sec:hook:commit}),
1369 \hook{pretxncommit} (sección~\ref{sec:hook:pretxncommit})
1371 \subsection{\hook{preoutgoing}---antes de empezar la propagación de
1372 conjuntos de cambios}
1373 \label{sec:hook:preoutgoing}
1375 Este gancho es ejecutado antes de que Mercurial conozca las
1376 identidades de los conjuntos de cambios que deben ser transmitidos.
1378 Un uso para este gancho es evitar que los cambios sean transmitidos a
1379 otro repositorio.
1381 Parámetros para este gancho:
1382 \begin{itemize}
1383 \item[\texttt{source}] Una cadena. La fuente la operación que está
1384 tratando de obtener cambios de éste repositorio (vea
1385 la sección~\ref{sec:hook:sources}). Revise la documentación para
1386 el parámetro \texttt{source} del gancho \hook{outgoing}, en la
1387 sección~\ref{sec:hook:outgoing}, para ver los posibles valores de
1388 este parámetro.
1389 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1390 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1391 \end{itemize}
1393 Vea también: \hook{outgoing} (sección~\ref{sec:hook:outgoing})
1395 \subsection{\hook{pretag}---antes de etiquetar un conjunto de cambios}
1396 \label{sec:hook:pretag}
1398 Este gancho de control es ejecutado antes de la creación de una
1399 etiqueta. Si el gancho termina exitosamente, la creación de la
1400 etiqueta continúa. Si el gancho falla, no se crea la etiqueta.
1402 Parámetros para este gancho:
1403 \begin{itemize}
1404 \item[\texttt{local}] Un booleano. Indica si la etiqueta es local a
1405 ésta instancia del repositorio (p.e.~almacenado en
1406 \sfilename{.hg/localtags}) o administrado por Mercurial (almacenado
1407 en \sfilename{.hgtags}).
1408 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del conjunto
1409 de cambios a etiquetar.
1410 \item[\texttt{tag}] Una cadena. El nombre de la etiqueta por crear.
1411 \end{itemize}
1413 Si la etiqueta que se va a crear se encuentra bajo control de
1414 revisiones, los ganchos \hook{precommit} y \hook{pretxncommit}
1415 (secciones~\ref{sec:hook:commit} y~\ref{sec:hook:pretxncommit})
1416 también serán ejecutados.
1418 Vea también: \hook{tag} (sección~\ref{sec:hook:tag})
1420 \subsection{\hook{pretxnchangegroup}---antes de completar la adición
1421 de conjuntos de cambios remotos}
1422 \label{sec:hook:pretxnchangegroup}
1424 Este gancho de control es ejecutado antes de una transacción---la que
1425 maneja la adición de un grupo de conjuntos de cambios nuevos desde
1426 fuera del repositorio---se complete. Si el gancho tiene éxito, la
1427 transacción se completa, y todos los conjuntos de cambios se vuelven
1428 permanentes dentro de este repositorio. Si el gancho falla, la
1429 transacción es deshecha, y los datos para los conjuntos de cambios son
1430 eliminados.
1432 Este gancho puede acceder a los metadatos asociados con los conjuntos
1433 de cambios casi añadidos, pero no debe hacer nada permanente con estos
1434 datos. Tampoco debe modificar el directorio de trabajo.
1436 Mientras este gancho está corriendo, si otro proceso Mercurial accesa
1437 el repositorio, podrá ver los conjuntos de cambios casi añadidos como
1438 si fueran permanentes. Esto puede llevar a condiciones de carrera si
1439 usted no toma precauciones para evitarlas.
1441 Este gancho puede ser usado para examinar automáticamente un grupo de
1442 conjuntos de cambios. Si el gancho falla, todos los conjuntos de
1443 cambios son ``rechazados'' cuando la transacción se deshace.
1445 Parámetros para este gancho:
1446 \begin{itemize}
1447 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer
1448 conjunto de cambios que fue añadido en el grupo. Todos los
1449 conjuntos de cambios entre éste y el
1450 \index{tags!\texttt{tip}}\texttt{tip}, inclusive, fueron añadidos
1451 por un único \hgcmd{pull}, \hgcmd{push} o \hgcmd{unbundle}.
1452 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
1453 sección~\ref{sec:hook:sources} para más detalles.
1454 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
1455 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
1456 \end{itemize}
1458 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup}),
1459 \hook{incoming} (sección~\ref{sec:hook:incoming}),
1460 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup})
1462 \subsection{\hook{pretxncommit}---antes de completar la consignación
1463 de un nuevo conjunto de cambios}
1464 \label{sec:hook:pretxncommit}
1466 Este gancho de control es ejecutado antes de que una transacción---que
1467 maneja una nueva consignación---se complete. Si el gancho tiene éxito,
1468 la transacción se completa y el conjunto de cambios se hace permanente
1469 dentro de éste repositorio. Si el gancho falla, la transacción es
1470 deshecha, y los datos de consignación son borrados.
1472 Este gancho tiene acceso a los metadatos asociados con el
1473 prácticamente nuevo conjunto de cambios, pero no debería hacer nada
1474 permanente con estos datos. Tampoco debe modificar el directorio de
1475 trabajo.
1477 Mientras este gancho está corriendo, si otro proceso Mercurial accesa
1478 éste repositorio, podrá ver el prácticamente nuevo conjunto de cambios
1479 como si fuera permanente. Esto puede llevar a condiciones de carrera si
1480 usted no toma precauciones para evitarlas.
1482 Parámetros para este gancho:
1483 \begin{itemize}
1484 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del
1485 conjunto de cambios recién consignado.
1486 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
1487 conjunto de cambios del primer padre del conjunto de cambios que
1488 acaba de ser consignado.
1489 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
1490 conjunto de cambios del segundo padre del conjunto de cambios que
1491 acaba de ser consignado.
1492 \end{itemize}
1494 Vea también: \hook{precommit} (sección~\ref{sec:hook:precommit})
1496 \subsection{\hook{preupdate}---antes de actualizar o fusionar el
1497 directorio de trabajo}
1498 \label{sec:hook:preupdate}
1500 Este gancho de control es ejecutado antes de actualizar o fusionar el
1501 directorio de trabajo. Es ejecutado sólo si las revisiones usuales de
1502 Mercurial antes de las actualizaciones determinan que la actualización
1503 o fusión pueden proceder. Si el gancho termina exitosamente, la
1504 actualización o fusión pueden proceder.; si falla, la actualización o
1505 fusión no empiezan.
1507 Parámetros para este gancho:
1508 \begin{itemize}
1509 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID del
1510 padre al que el directorio de trabajo será actualizado. Si se está
1511 fusionando el directorio de trabajo, no cambiará este padre.
1512 \item[\texttt{parent2}] Un ID de conjunto de cambios. Sólo está
1513 definido si se está fusionando el directorio de trabajo. El ID de la
1514 revisión con la cual está siendo fusionado el directorio de trabajo.
1515 \end{itemize}
1517 Vea también: \hook{update} (sección~\ref{sec:hook:update})
1519 \subsection{\hook{tag}---luego de etiquetar un conjunto de cambios}
1520 \label{sec:hook:tag}
1522 Este gancho es ejecutado luego de la creación de una etiqueta.
1524 Parámetros para este gancho:
1525 \begin{itemize}
1526 \item[\texttt{local}] Un booleano. Indica si la etiqueta es local a
1527 ésta instancia del repositorio (p.e.~almacenado en
1528 \sfilename{.hg/localtags}) o administrado por Mercurial (almacenado
1529 en \sfilename{.hgtags}).
1530 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del
1531 conjunto de cambios que fue etiquetado.
1532 \item[\texttt{tag}] Una cadena. El nombre de la etiqueta que fue
1533 creada.
1534 \end{itemize}
1536 Si la etiqueta creada está bajo control de revisiones, el gancho
1537 \hook{commit} (sección~\ref{sec:hook:commit}) es ejecutado antes de
1538 este gancho.
1540 Vea también: \hook{pretag} (sección~\ref{sec:hook:pretag})
1542 \subsection{\hook{update}---luego de actualizar o fusionar el
1543 directorio de trabajo}
1544 \label{sec:hook:update}
1546 Este gancho es ejecutado después de una actualización o fusión en el
1547 directorio de trabajo. Ya que una fusión puede fallar (si el comando
1548 externo \command{hgmerge} no puede resolver los conflictos en un
1549 fichero), este gancho indica si la actualización o fusión fueron
1550 completados adecuadamente.
1552 \begin{itemize}
1553 \item[\texttt{error}] Un booleano. Indica si la actualización o fusión
1554 fue completada exitosamente.
1555 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID del padre
1556 al cual fue actualizado el directorio de trabajo. Si se fusionó el
1557 directorio de trabajo, no se habrá cambiado este padre.
1558 \item[\texttt{parent2}] Un ID de conjunto de cambios. Sólo está
1559 definido si se fusionó el directorio de trabajo. El ID de la
1560 revisión con la que fue fusionado el directorio de trabajo.
1561 \end{itemize}
1563 Vea también: \hook{preupdate} (sección~\ref{sec:hook:preupdate})
1565 %%% Local Variables:
1566 %%% mode: latex
1567 %%% TeX-master: "00book"
1568 %%% End: