hgbook: es/hook.tex annotate

hgbook

annotate es/hook.tex @ 475:22184eb4c965

finished the translation of the section "information for writers of hooks"

updated project status

author	Javier Rojas <jerojasro@devnull.li>
date	Wed Dec 31 11:31:04 2008 -0500 (2008-12-31)
parents	9438521abfc4
children	1f9ef8b3ab79

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