hgbook

annotate es/hook.tex @ 964:6b680d569bb4

find changesets by author, revision, files, or words in the commit message
deleting a bunch of files not longer necessary to build the documentation.
Adding missing newly files needed to build the documentation
author Romain PELISSE <belaran@gmail.com>
date Sun Aug 16 04:58:01 2009 +0200 (2009-08-16)
parents e0e65bfe7776
children
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@529 156 social 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@537 343 \caption{Uso del gancho \hook{pretxncommit} para controlar consignaciones}
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@484 467 estructura básica de la API\ndt{\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@505 554 \caption{Un mejor gancho para espacios en blanco finales}
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@505 583 \section{Ganchos adicionales}
jerojasro@505 584
jerojasro@505 585 Mercurial se instala con varios ganchos adicionales. Usted puede
jerojasro@464 586 encontrarlos en el directorio \dirname{hgext} del árbol de ficheros
jerojasro@464 587 fuente de Mercurial. Si usted está usando un paquete binario de
jerojasro@464 588 Mercurial, los ganchos estarán ubicados en el directorio
jerojasro@464 589 \dirname{hgext} en donde su instalador de paquetes haya puesto a
jerojasro@336 590 Mercurial.
jerojasro@336 591
jerojasro@464 592 \subsection{\hgext{acl}---control de acceso a partes de un repositorio}
jerojasro@464 593
jerojasro@464 594 La extensión \hgext{acl} le permite controlar a qué usuarios remotos
jerojasro@464 595 les está permitido empujar conjuntos de cambios a un servidor en red.
jerojasro@464 596 Usted puede proteger cualquier porción de un repositorio (incluyendo
jerojasro@464 597 el repositorio completo), de tal manera que un usuario remoto
jerojasro@464 598 específico pueda empujar cambios que no afecten la porción protegida.
jerojasro@464 599
jerojasro@464 600 Esta extensión implementa control de acceso basado en la identidad del
jerojasro@464 601 usuario que empuja los conjuntos de cambios, \emph{no} en la identidad
jerojasro@464 602 de quien hizo la consignación de los mismos. Usar este gancho tiene
jerojasro@464 603 sentido sólo si se tiene un servidor adecuadamente asegurado que
jerojasro@464 604 autentique a los usuarios remotos, y si usted desea segurarse de que
jerojasro@464 605 sólo se le permita a ciertos usuarios empujar cambios a dicho
jerojasro@464 606 servidor.
jerojasro@464 607
jerojasro@474 608 \subsubsection{Configuración del gancho \hook{acl}}
jerojasro@464 609
jerojasro@464 610 Para administrar los conjuntos de cambios entrantes, se debe usar el
jerojasro@464 611 gancho \hgext{acl} como un gancho de tipo \hook{pretxnchangegroup}.
jerojasro@464 612 Esto le permite ver qué ficheros son modificados por cada conjunto de
jerojasro@464 613 %TODO rollback => "deshacer el efecto"
jerojasro@464 614 cambios entrante, y deshacer el efecto de un grupo de conjuntos de
jerojasro@464 615 cambios si alguno de ellos modifica algún fichero ``prohibido''.
jerojasro@464 616 Ejemplo:
jerojasro@336 617 \begin{codesample2}
jerojasro@336 618 [hooks]
jerojasro@336 619 pretxnchangegroup.acl = python:hgext.acl.hook
jerojasro@336 620 \end{codesample2}
jerojasro@336 621
jerojasro@464 622 La extensión \hgext{acl} es configurada mediante tres secciones.
jerojasro@464 623
jerojasro@464 624 La sección \rcsection{acl} sólo tiene una entrada,
jerojasro@484 625 \rcitem{acl}{sources}\ndt{Fuentes.}, que lista las fuentes de los
jerojasro@464 626 conjuntos de cambios entrantes a las que el gancho debe prestar
jerojasro@464 627 atención. Usualmente usted no necesita configurar esta sección.
jerojasro@464 628 \begin{itemize}
jerojasro@464 629 \item[\rcitem{acl}{serve}] Controlar conjuntos de
jerojasro@464 630 cambios entrantes que están llegando desde un repositorio a
jerojasro@464 631 través de http o ssh. Este es el valor por defecto de
jerojasro@464 632 \rcitem{acl}{sources}, y usualmente es el único valor de
jerojasro@464 633 configuración que necesitará para este ítem.
jerojasro@464 634 \item[\rcitem{acl}{pull}] Controlar conjuntos de cambios entrantes que
jerojasro@464 635 lleguen vía un pull (jalado) desde un repositorio local.
jerojasro@464 636 \item[\rcitem{acl}{push}] Controlar conjuntos de cambios entrantes que
jerojasro@464 637 lleguen vía un push (empuje) desde un repositorio local.
jerojasro@464 638 \item[\rcitem{acl}{bundle}] Controlar conjuntos de cambios entrantes
jerojasro@464 639 %TODO bundle
jerojasro@505 640 que lleguen desde otro repositorio a través de un paquete.
jerojasro@464 641 \end{itemize}
jerojasro@464 642
jerojasro@464 643 La sección \rcsection{acl.allow} controla los usuarios a los que les
jerojasro@464 644 está permitido añadir conjuntos de cambios al repositorio. Si esta
jerojasro@464 645 sección no está presente, se le permite acceso a todos los usuarios
jerojasro@464 646 excepto a los que se les haya negado explícitamente el acceso. Si
jerojasro@464 647 esta sección no está presente, se niega el acceso a todos los usuarios
jerojasro@464 648 excepto a todos a los que se les haya permitido de manera explícita
jerojasro@464 649 (así que una sección vacía implica que se niega el acceso a todos los
jerojasro@464 650 usuarios).
jerojasro@464 651
jerojasro@464 652 La sección \rcsection{acl.deny} determina a qué usuarios no se les
jerojasro@464 653 permite añadir conjuntos de cambios al repositorio. Si esta sección no
jerojasro@464 654 está presente o está vacía, no se niega el acceso a ningún usuario.
jerojasro@464 655
jerojasro@464 656 La sintaxis para los ficheros \rcsection{acl.allow} y
jerojasro@464 657 \rcsection{acl.deny} es idéntica. A la izquierda de cada entrada se
jerojasro@464 658 encuentra un patrón glob que asocia ficheros o directorios, respecto a
jerojasro@464 659 la raíz del repositorio; a la derecha, un nombre usuario.
jerojasro@464 660
jerojasro@464 661 En el siguiente ejemplo, el usuario \texttt{escritordoc} sólo puede
jerojasro@464 662 empujar cambios al directorio \dirname{docs} del repositorio, mientras
jerojasro@464 663 que \texttt{practicante} puede enviar cambios a cualquier fichero o
jerojasro@464 664 directorio excepto \dirname{fuentes/sensitivo}.
jerojasro@336 665 \begin{codesample2}
jerojasro@336 666 [acl.allow]
jerojasro@464 667 docs/** = escritordoc
jerojasro@336 668
jerojasro@336 669 [acl.deny]
jerojasro@464 670 fuentes/sensitivo/** = practicante
jerojasro@336 671 \end{codesample2}
jerojasro@336 672
jerojasro@465 673 \subsubsection{Pruebas y resolución de problemas}
jerojasro@465 674
jerojasro@465 675 Si usted desea probar el gancho \hgext{acl}, ejecútelo habilitando la
jerojasro@465 676 opción de salida de depuración habilitada. Ya que usted probablemente
jerojasro@465 677 lo estará ejecutando en un servidor donde no es conveniente (o incluso
jerojasro@465 678 posible) pasar la opción \hggopt{--debug}, no olvide que usted puede
jerojasro@465 679 habilitar la salida de depuración en su \hgrc:
jerojasro@336 680 \begin{codesample2}
jerojasro@336 681 [ui]
jerojasro@336 682 debug = true
jerojasro@336 683 \end{codesample2}
jerojasro@465 684 Con esto habilitado, el gancho \hgext{acl} imprimirá suficiente
jerojasro@465 685 información para permitirle saber porqué está permitiendo o denegando
jerojasro@465 686 la operación de empujar a usuarios específicos.
jerojasro@465 687
jerojasro@465 688 \subsection{\hgext{bugzilla}---integración con Bugzilla}
jerojasro@465 689
jerojasro@465 690 La extensión \hgext{bugzilla} añade un comentario a un fallo Bugzilla
jerojasro@465 691 siempre que encuentre una referencia al ID de dicho fallo en un
jerojasro@465 692 mensaje de consignación. Usted puede instalar este gancho en un
jerojasro@465 693 servidor compartido, para que cada vez que un usuario remoto empuje
jerojasro@465 694 cambios al servidor, el gancho sea ejecutado.
jerojasro@465 695
jerojasro@465 696 Se añade un comentario al fallo que se ve así (usted puede configurar
jerojasro@465 697 los contenidos del comentario---vea más abajo):
jerojasro@465 698 %TODO traducir?
jerojasro@336 699 \begin{codesample2}
jerojasro@336 700 Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
jerojasro@336 701 the frobnitz repository, refers to this bug.
jerojasro@336 702
jerojasro@336 703 For complete details, see
jerojasro@336 704 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
jerojasro@336 705
jerojasro@336 706 Changeset description:
jerojasro@336 707 Fix bug 10483 by guarding against some NULL pointers
jerojasro@336 708 \end{codesample2}
jerojasro@465 709 El valor de este gancho se encuentra en que automatiza el proceso de
jerojasro@465 710 actualizar un fallo cuando un conjunto de cambios se refiera a él. Si
jerojasro@465 711 usted configura este gancho adecuadamente, hará fácil para la gente
jerojasro@465 712 navegar directamente desde un fallo Bugzilla a un conjunto de cambios
jerojasro@465 713 que se refiere a ese fallo.
jerojasro@465 714
jerojasro@465 715 Usted puede usar el código de este gancho como un punto de partida
jerojasro@465 716 para otras recetas de integración con Bugzilla aún más exóticas. Acá
jerojasro@465 717 hay algunas posibilidades:
jerojasro@465 718 \begin{itemize}
jerojasro@465 719 \item Requerir que cada conjunto de cambios tenga un ID de fallo en su
jerojasro@465 720 mensaje de consignación. En este caso, usted querrá configurar el
jerojasro@465 721 gancho como uno de tipo \hook{pretxncommit}. Esto le permitirá al
jerojasro@465 722 gancho rechazar cambios que no contiene IDs de fallos.
jerojasro@465 723 \item Permitir a los conjuntos de cambios entrantes modificar
jerojasro@465 724 automáticamente el \emph{estado} de un fallo, así como simplemente
jerojasro@465 725 añadir un comentario. Por ejemplo, el gancho podría reconocer la
jerojasro@465 726 cadena ``corregido fallo 31337'' como la señal de que debería
jerojasro@465 727 actualizar el estado del fallo 31337 a ``requiere pruebas''.
jerojasro@336 728 \end{itemize}
jerojasro@336 729
jerojasro@466 730 \subsubsection{Configuración del gancho \hook{bugzilla}}
jerojasro@336 731 \label{sec:hook:bugzilla:config}
jerojasro@336 732
jerojasro@466 733 Usted debería configurar este gancho en el \hgrc\ de su servidor como
jerojasro@484 734 un gancho \hook{incoming}\ndt{Entrante.}, por ejemplo como sigue:
jerojasro@336 735 \begin{codesample2}
jerojasro@336 736 [hooks]
jerojasro@336 737 incoming.bugzilla = python:hgext.bugzilla.hook
jerojasro@336 738 \end{codesample2}
jerojasro@336 739
jerojasro@466 740 Debido a la naturaleza especializada de este gancho, y porque Bugzilla
jerojasro@466 741 no fue escrito con este tipo de integración en mente, configurar este
jerojasro@466 742 % TODO involved => complejo ? no intarwebs here :(
jerojasro@466 743 gancho es un proceso algo complejo.
jerojasro@466 744
jerojasro@466 745 Antes de empezar, usted debe instalar la interfaz de Python para MySQL
jerojasro@466 746 en los sistemas en los que se vaya a ejecutar el gancho. Si no está
jerojasro@466 747 disponible como paquete binario para su sistema, usted puede descargar
jerojasro@466 748 el paquete desde~\cite{web:mysql-python}.
jerojasro@466 749
jerojasro@466 750 La información para configurar este gancho se ubica en la sección
jerojasro@466 751 \rcsection{bugzilla} de su \hgrc.
jerojasro@466 752 \begin{itemize}
jerojasro@466 753 \item[\rcitem{bugzilla}{version}] La versión de Bugzilla instalada en
jerojasro@466 754 el servidor. El esquema de base de datos que Bugzilla usa cambia
jerojasro@466 755 ocasionalmente, así que este gancho debe saber exactamente qué
jerojasro@466 756 esquema usar. A la fecha, la única versión soportada es la
jerojasro@466 757 \texttt{2.16}.
jerojasro@466 758 \item[\rcitem{bugzilla}{host}] El nombre de máquina (\emph{hostname})
jerojasro@466 759 del servidor MySQL que almacena sus datos Bugzilla. La base de datos
jerojasro@466 760 debe ser configurada para permitir conexiones desde las máquinas en
jerojasro@466 761 las que usted ejecute el gancho \hook{bugzilla}.
jerojasro@466 762 \item[\rcitem{bugzilla}{user}] El nombre de usuario que se usará para
jerojasro@466 763 conectarse al servidor MySQL. La base de datos debe ser configurada
jerojasro@466 764 para permitir a dicho usuario conectarse desde cualquiera de las
jerojasro@466 765 máquinas en las que se ejecute el gancho \hook{bugzilla}. Este
jerojasro@466 766 usuario debe tener acceso y poder modificar las tablas de Bugzilla.
jerojasro@466 767 El valor por defecto para este ítem es \texttt{bugs}, que es el
jerojasro@466 768 nombre estándar del usuario para Bugzilla en una base de datos
jerojasro@466 769 MySQL.
jerojasro@466 770 \item[\rcitem{bugzilla}{password}] La contraseña MySQL para el usuario
jerojasro@466 771 configurado anteriormente. Ésta es almacenada como texto plano, así
jerojasro@466 772 que usted deberá asegurarse de que los usuarios no autorizados no
jerojasro@466 773 puedan leer el fichero \hgrc\ en donde usted guarda esta
jerojasro@466 774 información.
jerojasro@466 775 \item[\rcitem{bugzilla}{db}] El nombre de la base de datos Bugzilla en
jerojasro@466 776 el servidor MySQL. El nombre por defecto para este ítem es
jerojasro@466 777 \texttt{bugs}, que es el nombre estándar de la base de datos MySQL
jerojasro@466 778 en donde Bugzilla almacena sus datos.
jerojasro@466 779 \item[\rcitem{bugzilla}{notify}] Si usted desea que Bugzilla envíe un
jerojasro@466 780 %TODO suBscriptores?
jerojasro@466 781 correo de notificación a los suscriptores después de que el gancho
jerojasro@466 782 haya añadido un comentario a un fallo, necesitará que este gancho
jerojasro@466 783 ejecute un comando siempre que actualice la base de datos. El
jerojasro@466 784 comando que se ejecute depende de en dónde haya sido instalado
jerojasro@466 785 Bugzilla, pero típicamente se verá así, si usted ha instalado
jerojasro@466 786 Bugzilla en \dirname{/var/www/html/bugzilla}:
jerojasro@336 787 \begin{codesample4}
jerojasro@336 788 cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
jerojasro@336 789 \end{codesample4}
jerojasro@466 790 El programa \texttt{processmail} de Bugzilla espera recibir un ID de
jerojasro@466 791 fallo (el gancho reemplaza ``\texttt{\%s}'' por el ID del fallo) y
jerojasro@466 792 una dirección de correo. También espera poder escribir a ciertos
jerojasro@466 793 ficheros en el directorio en que se ejecuta. Si Bugzilla y éste
jerojasro@466 794 gancho no están instalados en la misma máquina, usted deberá
jerojasro@466 795 encontrar una manera de ejecutar \texttt{processmail} en el servidor
jerojasro@466 796 donde está instalado Bugzilla.
jerojasro@336 797 \end{itemize}
jerojasro@336 798
jerojasro@467 799 \subsubsection{Asociar nombres de consignadores a nombres de usuario
jerojasro@467 800 Bugzilla}
jerojasro@336 801
jerojasro@468 802 Por defecto, el gancho \hgext{bugzilla} trata de usar la dirección de
jerojasro@468 803 correo electrónico de la persona que hizo la consignación del conjunto
jerojasro@468 804 de cambios como el nombre de usuario Bugzilla con el cual debe
jerojasro@468 805 actualizar el fallo. Si esto no se ajusta a sus necesidades, es
jerojasro@468 806 posible asociar direcciones de correo a nombres de usuario Bugzilla
jerojasro@468 807 usando una sección \rcsection{usermap}.
jerojasro@468 808
jerojasro@468 809 Cada ítem en la sección \rcsection{usermap} contiene una dirección de
jerojasro@468 810 correo electrónico a la izquierda, y un nombre de usuario Bugzilla a
jerojasro@468 811 la derecha.
jerojasro@336 812 \begin{codesample2}
jerojasro@336 813 [usermap]
jerojasro@336 814 jane.user@example.com = jane
jerojasro@336 815 \end{codesample2}
jerojasro@468 816 Usted puede mantener los datos de \rcsection{usermap} en un fichero
jerojasro@468 817 \hgrc, o decirle al gancho \hgext{bugzilla} que lea la información
jerojasro@468 818 desde un fichero \filename{usermap} externo. En este caso, usted
jerojasro@468 819 puede almacenar los datos de \filename{usermap} en (por ejemplo) un
jerojasro@468 820 repositorio modificable por los usuarios. Esto hace posible para sus
jerojasro@468 821 usuarios mantener sus propias entradas \rcitem{bugzilla}{usermap}. El
jerojasro@468 822 fichero \hgrc\ principal se vería así:
jerojasro@468 823 \begin{codesample2}
jerojasro@468 824 # fichero hgrc normal se refiere a un fichero usermap externo
jerojasro@336 825 [bugzilla]
jerojasro@336 826 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
jerojasro@336 827 \end{codesample2}
jerojasro@468 828 Mientras que el fichero \filename{usermap} al que se hace referencia
jerojasro@468 829 se vería así:
jerojasro@468 830 \begin{codesample2}
jerojasro@468 831 # bugzilla-usermap.conf - dentro de un repositorio hg
jerojasro@336 832 [usermap]
jerojasro@336 833 stephanie@example.com = steph
jerojasro@336 834 \end{codesample2}
jerojasro@336 835
jerojasro@468 836 \subsubsection{Configurar el texto que se añade a un fallo}
jerojasro@468 837
jerojasro@468 838 Usted puede configurar el texto que este gancho añade como comentario;
jerojasro@468 839 usted los especifica como una plantilla Mercurial. Varias entradas
jerojasro@468 840 \hgrc\ (aún en la sección \rcsection{bugzilla}) controlan este
jerojasro@468 841 comportamiento.
jerojasro@468 842 \begin{itemize}
jerojasro@468 843 \item[\texttt{strip}] La cantidad de elementos iniciales de ruta a
jerojasro@468 844 remover de un nombre de ruta del repositorio para construir una ruta
jerojasro@468 845 parcial para una URL. Por ejemplo, si los repositorios en su
jerojasro@468 846 servidor se ubican en \dirname{/home/hg/repos}, y usted tiene un
jerojasro@468 847 repositorio cuya ruta es \dirname{/home/hg/repos/app/tests},
jerojasro@468 848 entonces fijar \texttt{strip} a \texttt{4} resultará en una ruta
jerojasro@468 849 parcial de \dirname{app/tests}. El gancho hará disponible esta ruta
jerojasro@468 850 parcial cuando expanda una plantilla, como \texttt{webroot}.
jerojasro@468 851 \item[\texttt{template}] El texto de la plantilla a usar. En adición a
jerojasro@468 852 las variables usuales relacionadas con conjuntos de cambios, esta
jerojasro@468 853 plantilla puede usar \texttt{hgweb} (el valor del ítem de
jerojasro@468 854 configuración \texttt{hgweb} de arriba) y \texttt{webroot} (la ruta
jerojasro@468 855 construida usando \texttt{strip} arriba).
jerojasro@468 856 \end{itemize}
jerojasro@468 857
jerojasro@468 858 Adicionalmente, usted puede añadir un ítem \rcitem{web}{baseurl} a la
jerojasro@468 859 sección \rcsection{web} de su \hgrc. El gancho \hgext{bugzilla}
jerojasro@468 860 publicará esto cuando expanda una plantilla, como la cadena base a
jerojasro@468 861 usar cuando se construya una URL que le permita a los usuarios navegar
jerojasro@468 862 desde un comentario de Bugzilla a la vista de un conjunto de cambios.
jerojasro@468 863 Ejemplo:
jerojasro@336 864 \begin{codesample2}
jerojasro@336 865 [web]
jerojasro@336 866 baseurl = http://hg.domain.com/
jerojasro@336 867 \end{codesample2}
jerojasro@336 868
jerojasro@468 869 A continuación se presenta un ejemplo completo de configuración para
jerojasro@468 870 el gancho \hgext{bugzilla}.
jerojasro@468 871 %TODO traducir?
jerojasro@336 872 \begin{codesample2}
jerojasro@336 873 [bugzilla]
jerojasro@336 874 host = bugzilla.example.com
jerojasro@336 875 password = mypassword
jerojasro@336 876 version = 2.16
jerojasro@336 877 # server-side repos live in /home/hg/repos, so strip 4 leading
jerojasro@336 878 # separators
jerojasro@336 879 strip = 4
jerojasro@336 880 hgweb = http://hg.example.com/
jerojasro@336 881 usermap = /home/hg/repos/notify/bugzilla.conf
jerojasro@336 882 template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
jerojasro@336 883 repo, refers to this bug.\\nFor complete details, see
jerojasro@336 884 \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
jerojasro@336 885 description:\\n\\t\{desc|tabindent\}
jerojasro@336 886 \end{codesample2}
jerojasro@336 887
jerojasro@468 888 \subsubsection{Pruebas y resolución de problemas}
jerojasro@468 889
jerojasro@468 890 Los problemas más comunes que aparecen en la configuración del gancho
jerojasro@468 891 \hgext{bugzilla} suelen estar relacionados con la ejecución del guión
jerojasro@468 892 de Bugzilla \filename{processmail} y la asociación de nombres de
jerojasro@468 893 consignadores a nombres de usuario.
jerojasro@468 894
jerojasro@474 895 Recuerde que en la sección~\ref{sec:hook:bugzilla:config} arriba el
jerojasro@474 896 usuario que ejecuta el proceso Mercurial en el servidor es también
jerojasro@474 897 el usuario que ejecutará el guión \filename{processmail}. El guión
jerojasro@474 898 \filename{processmail} algunas veces hace que Bugzilla escriba en
jerojasro@474 899 ficheros en su directorio de configuración, y los ficheros de
jerojasro@474 900 configuración de Bugzilla usualmente son propiedad del usuario bajo el
jerojasro@474 901 cual se ejecuta el servidor web.
jerojasro@474 902
jerojasro@474 903 Usted puede hacer que \filename{processmail} sea ejecutado con la
jerojasro@474 904 identidad del usuario adecuado usando el comando \command{sudo}. A
jerojasro@474 905 continuación se presenta una entrada de ejemplo para un fichero
jerojasro@474 906 \filename{sudoers}.
jerojasro@336 907 \begin{codesample2}
jerojasro@336 908 hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
jerojasro@336 909 \end{codesample2}
jerojasro@474 910 Esto permite que el usuario \texttt{hg\_user} ejecute el programa
jerojasro@474 911 \filename{processmail-wrapper} con la identidad del usuario
jerojasro@336 912 \texttt{httpd\_user}.
jerojasro@336 913
jerojasro@474 914 Esta indirección a través de un guión envoltorio es necesaria, porque
jerojasro@474 915 \filename{processmail} espera que al ser ejecutado su directorio
jerojasro@474 916 actual sea aquel en el cual se instaló Bugzilla; usted no puede
jerojasro@474 917 especificar ese tipo de condición en un fichero \filename{sudoers}.
jerojasro@474 918 Los contenidos del giuón envoltorio son simples:
jerojasro@336 919 \begin{codesample2}
jerojasro@336 920 #!/bin/sh
jerojasro@336 921 cd `dirname $0` && ./processmail "$1" nobody@example.com
jerojasro@336 922 \end{codesample2}
jerojasro@474 923 No parece importar qué dirección de correo se le pase a
jerojasro@336 924 \filename{processmail}.
jerojasro@336 925
jerojasro@474 926 Si su \rcsection{usermap} no es configurada correctamente, los
jerojasro@474 927 usuarios verán un mensaje de error del gancho \hgext{bugzilla} cuando
jerojasro@474 928 empujen cambios al servidor. El mensaje de error se verá así:
jerojasro@336 929 \begin{codesample2}
jerojasro@336 930 cannot find bugzilla user id for john.q.public@example.com
jerojasro@336 931 \end{codesample2}
jerojasro@474 932 Lo que esto quiere decir es que la dirección del consignador,
jerojasro@474 933 \texttt{john.q.public@example.com}, no es un nombre de usuario
jerojasro@474 934 Bugzilla válido, ni tiene una entrada en su \rcsection{usermap} que lo
jerojasro@474 935 asocie con un nombre de usuario válido Bugzilla.
jerojasro@474 936
jerojasro@474 937 \subsection{\hgext{notify}---enviar notificaciones de correo
jerojasro@474 938 electrónico}
jerojasro@474 939
jerojasro@474 940 %TODO feeds => notificaciones: lo más fácil es mirar en wikipedia
jerojasro@474 941 Aunque el servidor web embebido de Mercurial provee notificaciones de
jerojasro@474 942 cambios en cada repositorio, muchas personas prefieren recibir las
jerojasro@474 943 notificaciones de cambios vía correo electrónico. El gancho
jerojasro@484 944 \hgext{notify}\ndt{Notificación.} le permite a usted enviar
jerojasro@474 945 notificaciones a un conjunto de direcciones de correo cuando lleguen
jerojasro@474 946 conjuntos de cambios en los que los subscriptores estén interesados.
jerojasro@474 947
jerojasro@474 948 De la misma forma que con el gancho \hgext{bugzilla}, el gancho
jerojasro@474 949 \hgext{notify} está orientado a plantillas, así que usted puede
jerojasro@474 950 personalizar los contenidos del mensaje de notificación que se envía.
jerojasro@474 951
jerojasro@474 952 Por defecto, el gancho \hgext{notify} incluye un diff de cada conjunto
jerojasro@474 953 %TODO que se envía? revisar, pienso que es ``que se recibe''
jerojasro@474 954 de cambios que se envía; usted puede limitar el tamaño del diff, o
jerojasro@474 955 desactivar completamente esta característica. Es útil para permitir a
jerojasro@474 956 los subscriptores revisar los cambios inmediatamente, en vez de tener
jerojasro@474 957 que hacer clic para visitar una URL.
jerojasro@474 958
jerojasro@474 959 \subsubsection{Configuración del gancho \hgext{notify}}
jerojasro@474 960
jerojasro@474 961 Usted puede configurar el gancho \hgext{notify} para enviar un mensaje
jerojasro@474 962 de correo por conjunto de cambios entrante, o uno por grupo entrante
jerojasro@474 963 de conjuntos de cambios (todos los que llegaron en un único empuje o
jerojasro@474 964 jalado).
jerojasro@336 965 \begin{codesample2}
jerojasro@336 966 [hooks]
jerojasro@474 967 # enviar un correo por grupo de cambios
jerojasro@336 968 changegroup.notify = python:hgext.notify.hook
jerojasro@474 969 # enviar un correo por cambio
jerojasro@336 970 incoming.notify = python:hgext.notify.hook
jerojasro@336 971 \end{codesample2}
jerojasro@336 972
jerojasro@474 973 La información para configurar este gancho se ubica en la sección
jerojasro@474 974 \rcsection{notify} de un fichero \hgrc.
jerojasro@474 975 \begin{itemize}
jerojasro@474 976 \item[\rcitem{notify}{test}] Por defecto, este gancho no envía correos
jerojasro@474 977 en absoluto; en vez de eso, imprime el mensaje que se
jerojasro@474 978 \emph{enviaría}. Fije este ítem en \texttt{false} para permitir el
jerojasro@474 979 envío de correos. El motivo por el que el envío de correos está
jerojasro@474 980 desactivado es que hacen falta varios intentos para configurar esta
jerojasro@474 981 extensión exactamente como usted desea, y sería maleducado enviar a
jerojasro@474 982 los subscriptores una cantidad de notificaciones ``rotas'' mientras
jerojasro@474 983 usted depura su configuración.
jerojasro@474 984 \item[\rcitem{notify}{config}] La ruta a un fichero de configuración
jerojasro@474 985 que contiene información de subscripción. Esto se mantiene separado
jerojasro@474 986 del \hgrc\ principal para que usted pueda mantenerlo en un
jerojasro@474 987 repositorio. La gente puede clonar ese repositorio, actualizar sus
jerojasro@474 988 subscripciones, y empujar los cambios de vuelta a su servidor.
jerojasro@474 989 \item[\rcitem{notify}{strip}] La cantidad de caracteres iniciales de
jerojasro@474 990 separación de ruta a remover de la ruta del repositorio, al decidir
jerojasro@474 991 si un repositorio tiene subscriptores. Por ejemplo, si los
jerojasro@474 992 repositorios en su servidor están en \dirname{/home/hg/repos}, y
jerojasro@474 993 \hgext{notify} está trabajando con un repositorio llamado
jerojasro@474 994 \dirname{/home/hg/repos/shared/test}, fijar \rcitem{notify}{strip} a
jerojasro@474 995 \texttt{4} hará que \hgext{notify} elimine las partes iniciales de
jerojasro@474 996 la ruta hasta \dirname{shared/test}, y asociará los subscriptores
jerojasro@474 997 frente a dicha ruta.
jerojasro@474 998 \item[\rcitem{notify}{template}] El texto de plantilla a usar cuando
jerojasro@474 999 se envíen mensajes. Especifica los contenidos de la cabecera del
jerojasro@474 1000 mensaje y el cuerpo del mismo.
jerojasro@474 1001 \item[\rcitem{notify}{maxdiff}] El número máximo de líneas de datos de
jerojasro@474 1002 diff a añadir al final de un mensaje. Si la longitud de un diff es
jerojasro@474 1003 mayor a eso, se trunca. Por defecto, está fijado en 300. Fije esto a
jerojasro@474 1004 \texttt{0} para omitir los diffs en los correos de notificación.
jerojasro@474 1005 \item[\rcitem{notify}{sources}] Una lista de fuentes de conjuntos de
jerojasro@474 1006 cambios a considerar. Esto le permite a usted indicar a
jerojasro@474 1007 \hgext{notify} para que sólo envíe correos acerca de cambios que
jerojasro@474 1008 usuarios remotos hayan empujado al repositorio vía un servidor, por
jerojasro@474 1009 ejemplo. Vea la sección~\ref{sec:hook:sources} para las fuentes que
jerojasro@474 1010 usted puede especificar aquí.
jerojasro@474 1011 \end{itemize}
jerojasro@474 1012
jerojasro@474 1013 Si usted fija el ítem \rcitem{web}{baseurl} en la sección
jerojasro@474 1014 \rcsection{web}, usted lo puede usar en una plantilla; estará
jerojasro@474 1015 disponible como \texttt{webroot}.
jerojasro@474 1016
jerojasro@474 1017 A continuación se presenta un ejemplo completo de configuración para
jerojasro@474 1018 el gancho \hgext{notify}.
jerojasro@336 1019 \begin{codesample2}
jerojasro@336 1020 [notify]
jerojasro@474 1021 # enviar correo
jerojasro@336 1022 test = false
jerojasro@474 1023 # datos de subscriptores están en el repositorio notify
jerojasro@336 1024 config = /home/hg/repos/notify/notify.conf
jerojasro@474 1025 # repos están en /home/hg/repos on server, así que elimine 4
jerojasro@474 1026 # caracteres"/"
jerojasro@336 1027 strip = 4
jerojasro@336 1028 template = X-Hg-Repo: \{webroot\}
jerojasro@336 1029 Subject: \{webroot\}: \{desc|firstline|strip\}
jerojasro@336 1030 From: \{author\}
jerojasro@336 1031
jerojasro@336 1032 changeset \{node|short\} in \{root\}
jerojasro@336 1033 details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
jerojasro@336 1034 description:
jerojasro@336 1035 \{desc|tabindent|strip\}
jerojasro@336 1036
jerojasro@336 1037 [web]
jerojasro@336 1038 baseurl = http://hg.example.com/
jerojasro@336 1039 \end{codesample2}
jerojasro@336 1040
jerojasro@474 1041 Esto producirá un mensaje que se verá como el siguiente:
jerojasro@336 1042 \begin{codesample2}
jerojasro@336 1043 X-Hg-Repo: tests/slave
jerojasro@336 1044 Subject: tests/slave: Handle error case when slave has no buffers
jerojasro@336 1045 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
jerojasro@336 1046
jerojasro@336 1047 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
jerojasro@336 1048 details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
jerojasro@336 1049 description:
jerojasro@336 1050 Handle error case when slave has no buffers
jerojasro@336 1051 diffs (54 lines):
jerojasro@336 1052
jerojasro@336 1053 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
jerojasro@336 1054 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
jerojasro@336 1055 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
jerojasro@336 1056 @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
jerojasro@336 1057 [...snip...]
jerojasro@336 1058 \end{codesample2}
jerojasro@336 1059
jerojasro@468 1060 \subsubsection{Pruebas y resolución de problemas}
jerojasro@468 1061
jerojasro@468 1062 No olvide que por defecto, la extensión \hgext{notify} \emph{no
jerojasro@468 1063 enviará ningún correo electrónico} hasta que usted la configure
jerojasro@468 1064 explícitamente para hacerlo, fijando el valor de \rcitem{notify}{test}
jerojasro@468 1065 a \texttt{false}. Hasta que usted haga eso, simplemente se imprimirá
jerojasro@468 1066 el mensaje que se \emph{enviaría}.
jerojasro@336 1067
jerojasro@475 1068 \section{Información para escritores de ganchos}
jerojasro@336 1069 \label{sec:hook:ref}
jerojasro@336 1070
jerojasro@475 1071 \subsection{Ejecución de ganchos internos}
jerojasro@475 1072
jerojasro@475 1073 Un gancho interno es llamado con argumentos de la siguiente forma:
jerojasro@336 1074 \begin{codesample2}
jerojasro@336 1075 def myhook(ui, repo, **kwargs):
jerojasro@336 1076 pass
jerojasro@336 1077 \end{codesample2}
jerojasro@475 1078 El parámetro \texttt{ui} es un objeto \pymodclass{mercurial.ui}{ui}.
jerojasro@475 1079 El parámetro \texttt{repo} es un objeto
jerojasro@475 1080 \pymodclass{mercurial.localrepo}{localrepository}. Los nombres y
jerojasro@475 1081 valores de los parámetros en \texttt{**kwargs} dependen del gancho que
jerojasro@475 1082 se invoque, con las siguientes características en común:
jerojasro@475 1083 \begin{itemize}
jerojasro@475 1084 \item Si hay un parámetro llamado \texttt{node} o
jerojasro@475 1085 \texttt{parent\emph{N}}, contendrá un ID hexadecimal de un conjunto
jerojasro@475 1086 de cambios. La cadena vacía es usada para representar un
jerojasro@475 1087 ``ID de conjunto de cambios nulo'' en vez de una cadena de ceros.
jerojasro@475 1088 \item Si hay un parámetro llamado \texttt{url}, contendrá la URL de un
jerojasro@475 1089 repositorio remoto, si puede ser determinada.
jerojasro@475 1090 \item Los parámetros booleanos son representados como objetos
jerojasro@475 1091 \texttt{bool} de Python.
jerojasro@475 1092 \end{itemize}
jerojasro@475 1093
jerojasro@475 1094 Un gancho interno es ejecutado sin cambiar el directorio de trabajo
jerojasro@475 1095 del proceso (a diferencia de los ganchos externos, que son ejecutados
jerojasro@475 1096 desde la raíz del repositorio). El gancho no debe cambiar el
jerojasro@475 1097 directorio de trabajo del proceso, porque esto haría que falle
jerojasro@475 1098 cualquier llamada que se haga a la API de Mercurial.
jerojasro@475 1099
jerojasro@484 1100 Si un gancho retorna el valor booleano ``false''\ndt{Falso.}, se
jerojasro@475 1101 considera que éste tuvo éxito. Si retorna
jerojasro@484 1102 ``true''\ndt{Verdadero.} o genera una excepción, se considera que
jerojasro@475 1103 ha fallado. Una manera útil de pensar en esta convención de llamado es
jerojasro@475 1104 ``dígame si usted falló''.
jerojasro@475 1105
jerojasro@475 1106 Note que los IDs de conjuntos de cambios son pasados a los ganchos de
jerojasro@475 1107 Python como cadenas hexadecimales, no como los hashes binarios que la
jerojasro@475 1108 API de Mercurial usa normalmente. Para convertir un hash de
jerojasro@475 1109 hexadecimal a binario, use la función \pymodfunc{mercurial.node}{bin}.
jerojasro@475 1110
jerojasro@475 1111 \subsection{Ejecución de ganchos externos}
jerojasro@475 1112
jerojasro@475 1113 Un gancho externo es pasado al intérprete de comandos del usuario bajo
jerojasro@475 1114 el cual se ejecuta Mercurial. Las características del intérprete, como
jerojasro@475 1115 sustitución de variables y redirección de comandos, están disponibles.
jerojasro@475 1116 El gancho es ejecutado desde el directorio raíz del repositorio
jerojasro@475 1117 (a diferencia de los ganchos internos, que se ejecutan desde el mismo
jerojasro@475 1118 directorio en que Mercurial fue ejecutado).
jerojasro@475 1119
jerojasro@475 1120 Los parámetros para el gancho se pasan como variables de entorno. El
jerojasro@475 1121 nombre de cada variable de entorno se pasa a mayúsculas y se le añade
jerojasro@475 1122 el prefijo ``\texttt{HG\_}''. Por ejemplo, si el nombre de un
jerojasro@475 1123 parámetro es ``\texttt{node}'', el nombre de la variable de entorno
jerojasro@475 1124 que almacena el parámetro se llamará ``\texttt{HG\_NODE}''.
jerojasro@475 1125
jerojasro@475 1126 Un parámetro booleano se representa con la cadena ``\texttt{1}'' para
jerojasro@475 1127 ``true'', ``\texttt{0}'' para ``false''. Si una variable se llama
jerojasro@475 1128 \envar{HG\_NODE}, \envar{HG\_PARENT1} o \envar{HG\_PARENT2},
jerojasro@475 1129 contendrá un ID de conjunto de cambios representado como una cadena
jerojasro@475 1130 hexadecimal. La cadena vacía es usada para representar un ``ID de
jerojasro@475 1131 conjunto de cambios nulo'' en vez de una cadena de ceros. Si una
jerojasro@475 1132 variable de entorno se llama \envar{HG\_URL}, contendrá la URL de un
jerojasro@475 1133 repositorio remoto, si puede ser determinada.
jerojasro@475 1134
jerojasro@475 1135 Si un gancho termina con un código de salida de cero, se considera que
jerojasro@475 1136 tuvo éxito. Si termina con un código de salida diferente de cero, se
jerojasro@475 1137 considera que falló.
jerojasro@475 1138
jerojasro@475 1139 \subsection{Averiguar de dónde vienen los conjuntos de cambios}
jerojasro@475 1140 %TODO los trae la cigüeña. De París. Y quedan debajo de una col.
jerojasro@475 1141
jerojasro@475 1142 Un gancho que involucra la transferencia de conjuntos de cambios entre
jerojasro@475 1143 un repositorio local y otro puede ser capaz de averiguar información
jerojasro@475 1144 acerca de ``el otro lado''. Mercurial sabe \emph{cómo} son
jerojasro@475 1145 transferidos los conjuntos de cambios, y en muchos casos también desde
jerojasro@475 1146 o hacia donde están siendo transferidos.
jerojasro@475 1147
jerojasro@475 1148 \subsubsection{Fuentes de conjuntos de cambios}
jerojasro@336 1149 \label{sec:hook:sources}
jerojasro@336 1150
jerojasro@475 1151 Mercurial le indicará a un gancho cuáles son, o fueron, los medios
jerojasro@475 1152 usados para transferir los conjuntos de cambios entre repositorios.
jerojasro@475 1153 Esta información es provista por Mercurial en un parámetro Python
jerojasro@484 1154 llamado \texttt{source}\ndt{Fuente.}, o una variable de entorno
jerojasro@475 1155 llamada \envar{HG\_SOURCE}.
jerojasro@475 1156
jerojasro@475 1157 \begin{itemize}
jerojasro@475 1158 \item[\texttt{serve}] Los conjuntos de cambios son transferidos desde
jerojasro@475 1159 o hacia un repositorio remoto a través de http o ssh.
jerojasro@475 1160 \item[\texttt{pull}] Los conjuntos de cambios son transferidos vía una
jerojasro@475 1161 operación de jalado de un repositorio a otro.
jerojasro@475 1162 \item[\texttt{push}] Los conjuntos de cambios son transferidos vía un
jerojasro@475 1163 empuje de un repositorio a otro.
jerojasro@475 1164 \item[\texttt{bundle}] Los conjuntos de cambios son transferidos desde
jerojasro@475 1165 %TODO bundle
jerojasro@505 1166 o hacia un paquete.
jerojasro@475 1167 \end{itemize}
jerojasro@475 1168
jerojasro@475 1169 \subsubsection{A dónde van los cambios---URLs de repositorios remotos}
jerojasro@336 1170 \label{sec:hook:url}
jerojasro@475 1171 %TODO al cielo? no, ésos son los perros
jerojasro@475 1172
jerojasro@475 1173 Cuando es posible, Mercurial le indicará a los ganchos la ubicación de
jerojasro@475 1174 ``el otro lado'' de una actividad que transfiera datos de conjuntos de
jerojasro@475 1175 cambios entre repositorios. Esto es provisto por Mercurial en un
jerojasro@475 1176 parámetro Python llamado \texttt{url}, o en una variable de entorno
jerojasro@475 1177 llamada \envar{HG\_URL}.
jerojasro@475 1178
jerojasro@475 1179 No siempre esta información está disponible. Si un gancho es invocado
jerojasro@475 1180 un repositorio que es servido a través de http o ssh, Mercurial no
jerojasro@475 1181 puede averiguar dónde está el repositorio remoto, pero puede saber
jerojasro@475 1182 desde dónde se conecta el cliente. En esos casos, la URL tendrá una de
jerojasro@475 1183 las siguientes formas:
jerojasro@475 1184 \begin{itemize}
jerojasro@475 1185 \item \texttt{remote:ssh:\emph{ip-address}}---cliente ssh remoto, en
jerojasro@475 1186 la dirección IP dada.
jerojasro@475 1187 \item \texttt{remote:http:\emph{ip-address}}---cliente remoto http, en
jerojasro@475 1188 la dirección IP dada. Si el cliente está usando SSL, tendrá la forma
jerojasro@475 1189 \texttt{remote:https:\emph{ip-address}}.
jerojasro@475 1190 \item Vacío---no se pudo descubrir información acerca del cliente
jerojasro@475 1191 remoto.
jerojasro@336 1192 \end{itemize}
jerojasro@336 1193
jerojasro@477 1194 \section{Referencia de ganchos}
jerojasro@477 1195
jerojasro@477 1196 \subsection{\hook{changegroup}---luego de añadir conjuntos de cambios
jerojasro@477 1197 remotos}
jerojasro@336 1198 \label{sec:hook:changegroup}
jerojasro@336 1199
jerojasro@477 1200 Este gancho es ejecutado luego de que un grupo de conjuntos de cambios
jerojasro@477 1201 preexistentes ha sido añadido al repositorio, por ejemplo vía un
jerojasro@477 1202 \hgcmd{pull} o \hgcmd{unbundle}. Este gancho es ejecutado una vez por
jerojasro@477 1203 cada operación que añade uno o más conjuntos de cambios. Este gancho
jerojasro@477 1204 se diferencia del gancho \hook{incoming}, que es ejecutado una vez por
jerojasro@477 1205 cada conjunto de cambios, sin importar si los cambios llegan en grupo.
jerojasro@477 1206
jerojasro@477 1207 Algunos usos posibles para este gancho includen el probar o ensamblar
jerojasro@477 1208 los conjuntos de cambios añadidos, actualizar una base de datos de
jerojasro@477 1209 fallos, o notificar a subscriptores de que el repositorio contiene
jerojasro@477 1210 nuevos cambios.
jerojasro@477 1211
jerojasro@477 1212 Parámetros para este gancho:
jerojasro@477 1213 \begin{itemize}
jerojasro@477 1214 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer conjunto
jerojasro@477 1215 de cambios que fue añadido en el grupo. Todos los conjuntos de
jerojasro@477 1216 cambios entre éste y la punta
jerojasro@477 1217 %TODO mirar qué hacer con el índice
jerojasro@477 1218 \index{tags!\texttt{tip}}(\texttt{tip}), inclusive, fueron añadidos
jerojasro@477 1219 %TODO unbundle
jerojasro@477 1220 por un único jalado (\hgcmd{pull}), empuje (\hgcmd{push}) o \hgcmd{unbundle}.
jerojasro@477 1221 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
jerojasro@477 1222 sección~\ref{sec:hook:sources} para más detalles.
jerojasro@477 1223 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@477 1224 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@477 1225 \end{itemize}
jerojasro@477 1226
jerojasro@477 1227 Veta también: \hook{incoming} (sección~\ref{sec:hook:incoming}),
jerojasro@477 1228 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup}),
jerojasro@477 1229 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
jerojasro@477 1230
jerojasro@477 1231 \subsection{\hook{commit}---luego de la creación de un nuevo conjunto
jerojasro@477 1232 de cambios}
jerojasro@477 1233 \label{sec:hook:commit}
jerojasro@477 1234
jerojasro@477 1235 Este gancho es ejecutado luego de la creación de un nuevo conjunto de
jerojasro@477 1236 cambios.
jerojasro@477 1237
jerojasro@477 1238 Parámetros para este gancho:
jerojasro@477 1239 \begin{itemize}
jerojasro@477 1240 \item[\texttt{node}] Un ID de conjunto de cambios. El ID de conjunto
jerojasro@477 1241 de cambios del conjunto de cambios que acabó de ser consignado.
jerojasro@477 1242 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
jerojasro@477 1243 conjunto de cambios del primer padre del conjunto de cambios que
jerojasro@477 1244 acaba de ser consignado.
jerojasro@477 1245 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
jerojasro@477 1246 conjunto de cambios del segundo padre del conjunto de cambios que
jerojasro@477 1247 acaba de ser consignado.
jerojasro@477 1248 \end{itemize}
jerojasro@477 1249
jerojasro@477 1250 Vea también: \hook{precommit} (sección~\ref{sec:hook:precommit}),
jerojasro@477 1251 \hook{pretxncommit} (sección~\ref{sec:hook:pretxncommit})
jerojasro@477 1252
jerojasro@477 1253 \subsection{\hook{incoming}---luego de que un conjunto de cambios
jerojasro@477 1254 remoto es añadido}
jerojasro@477 1255 \label{sec:hook:incoming}
jerojasro@477 1256
jerojasro@477 1257 Este gancho es ejecutado luego de que un conjunto de cambios
jerojasro@477 1258 preexistente ha sido añadido al repositorio, por ejemplo, vía un
jerojasro@477 1259 \hgcmd{push}. Si un grupo de conjuntos de cambios fue añadido en una
jerojasro@477 1260 sola operación, este gancho es ejecutado una vez por cada conjunto de
jerojasro@477 1261 cambios añadido.
jerojasro@477 1262
jerojasro@477 1263 Usted puede usar este gancho para los mismos fines que el gancho
jerojasro@477 1264 \hook{changegroup} (sección~\ref{sec:hook:changegroup}); simplemente
jerojasro@477 1265 algunas veces es más conveniente ejecutar un gancho una vez por cada
jerojasro@477 1266 grupo de conjuntos de cambios, mientras que otras es más útil correrlo
jerojasro@477 1267 por cada conjunto de cambios.
jerojasro@477 1268
jerojasro@479 1269 Parámetros para este gancho:
jerojasro@477 1270 \begin{itemize}
jerojasro@477 1271 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del conjunto
jerojasro@477 1272 de cambios recién añadido.
jerojasro@477 1273 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
jerojasro@477 1274 sección~\ref{sec:hook:sources} para más detalles.
jerojasro@477 1275 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@477 1276 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@477 1277 \end{itemize}
jerojasro@477 1278
jerojasro@477 1279 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup})
jerojasro@477 1280 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup}),
jerojasro@477 1281 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
jerojasro@477 1282
jerojasro@477 1283 \subsection{\hook{outgoing}---luego de la propagación de los conjuntos
jerojasro@477 1284 de cambios}
jerojasro@477 1285 \label{sec:hook:outgoing}
jerojasro@477 1286
jerojasro@477 1287 Este gancho es ejecutado luego de que un grupo de conjuntos de cambios
jerojasro@477 1288 ha sido propagado fuera de éste repositorio, por ejemplo por un
jerojasro@477 1289 comando \hgcmd{push} o \hgcmd{bundle}.
jerojasro@477 1290
jerojasro@477 1291 Un uso posible para este gancho es notificar a los administradores que
jerojasro@477 1292 los cambios han sido jalados.
jerojasro@477 1293
jerojasro@477 1294 Parámetros para este gancho:
jerojasro@477 1295 \begin{itemize}
jerojasro@477 1296 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer conjunto
jerojasro@477 1297 de cambios del grupo que fue enviado.
jerojasro@477 1298 \item[\texttt{source}] Una cadena. La fuente de la operación (vea la
jerojasro@477 1299 sección~\ref{sec:hook:sources}). Si un cliente remoto jaló cambios
jerojasro@477 1300 de este repositorio, \texttt{source} será \texttt{serve}. Si el
jerojasro@477 1301 cliente que obtuvo los cambios desde este repositorio era local,
jerojasro@477 1302 \texttt{source} será \texttt{bundle}, \texttt{pull}, o
jerojasro@477 1303 \texttt{push}, dependiendo de la operación que llevó a cabo el
jerojasro@477 1304 cliente.
jerojasro@477 1305 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@477 1306 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@477 1307 \end{itemize}
jerojasro@477 1308
jerojasro@477 1309 Vea también: \hook{preoutgoing} (sección~\ref{sec:hook:preoutgoing})
jerojasro@477 1310
jerojasro@479 1311 \subsection{\hook{prechangegroup}---antes de empezar la adición de
jerojasro@479 1312 conjuntos de cambios remotos}
jerojasro@477 1313 \label{sec:hook:prechangegroup}
jerojasro@477 1314
jerojasro@479 1315 Este gancho de control es ejecutado antes de que Mercurial empiece a
jerojasro@479 1316 añadir un grupo de conjuntos de cambios de otro repositorio.
jerojasro@479 1317
jerojasro@479 1318 Este gancho no tiene ninguna información acerca de los conjuntos de
jerojasro@479 1319 cambios que van a ser añadidos, porque es ejecutado antes de que se
jerojasro@479 1320 permita que empiece la transmisión de dichos conjuntos de cambios. Si
jerojasro@479 1321 este gancho falla, los conjuntos de cambios no serán transmitidos.
jerojasro@479 1322
jerojasro@479 1323 Un uso para este gancho es prevenir que se añadan cambios externos a un
jerojasro@479 1324 repositorio. Por ejemplo, usted podría usarlo para ``congelar''
jerojasro@479 1325 temporal o permanentemente una rama ubicada en un servidor para que
jerojasro@479 1326 los usuarios no puedan empujar cambios a ella, y permitiendo al mismo
jerojasro@479 1327 tiempo modificaciones al repositorio por parte de un administrador
jerojasro@479 1328 local.
jerojasro@479 1329
jerojasro@479 1330 Parámetros para este gancho:
jerojasro@479 1331 \begin{itemize}
jerojasro@479 1332 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
jerojasro@479 1333 sección~\ref{sec:hook:sources} para más detalles.
jerojasro@479 1334 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@479 1335 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@479 1336 \end{itemize}
jerojasro@479 1337
jerojasro@479 1338 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup}),
jerojasro@479 1339 \hook{incoming} (sección~\ref{sec:hook:incoming}), ,
jerojasro@479 1340 \hook{pretxnchangegroup} (sección~\ref{sec:hook:pretxnchangegroup})
jerojasro@479 1341
jerojasro@479 1342 \subsection{\hook{precommit}---antes de iniciar la consignación de un
jerojasro@479 1343 conjunto de cambios}
jerojasro@477 1344 \label{sec:hook:precommit}
jerojasro@477 1345
jerojasro@479 1346 Este gancho es ejecutado antes de que Mercurial inicie la consignación
jerojasro@479 1347 de un nuevo conjunto de cambios. Es ejecutado antes de que Mercurial
jerojasro@479 1348 tenga cualquier de los metadatos para la consignación, como los
jerojasro@479 1349 ficheros a ser consignados, el mensaje de consignación, o la fecha de
jerojasro@479 1350 consignación.
jerojasro@479 1351
jerojasro@479 1352 Un uso para este gancho es deshabilitar la capacidad de consignar
jerojasro@479 1353 nuevos conjuntos de cambios, pero permitiendo conjuntos de cambios
jerojasro@479 1354 entrantes. Otro es ejecutar un proceso de ensamble/compilación o
jerojasro@479 1355 prueba, y permitir la consignación sólo si el ensamble/compilación o
jerojasro@479 1356 prueba tiene éxito.
jerojasro@479 1357
jerojasro@479 1358 Parámetros para este gancho:
jerojasro@479 1359 \begin{itemize}
jerojasro@479 1360 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
jerojasro@479 1361 conjunto de cambios del primer padre del directorio de trabajo.
jerojasro@479 1362 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
jerojasro@479 1363 conjunto de cambios del segundo padre del directorio de trabajo.
jerojasro@479 1364 \end{itemize}
jerojasro@479 1365 Si la consignación continúa, los padres del directorio de trabajo se
jerojasro@479 1366 convertirán en los padres del nuevo conjunto de cambios.
jerojasro@479 1367
jerojasro@479 1368 Vea también: \hook{commit} (sección~\ref{sec:hook:commit}),
jerojasro@479 1369 \hook{pretxncommit} (sección~\ref{sec:hook:pretxncommit})
jerojasro@479 1370
jerojasro@479 1371 \subsection{\hook{preoutgoing}---antes de empezar la propagación de
jerojasro@479 1372 conjuntos de cambios}
jerojasro@477 1373 \label{sec:hook:preoutgoing}
jerojasro@477 1374
jerojasro@479 1375 Este gancho es ejecutado antes de que Mercurial conozca las
jerojasro@479 1376 identidades de los conjuntos de cambios que deben ser transmitidos.
jerojasro@479 1377
jerojasro@479 1378 Un uso para este gancho es evitar que los cambios sean transmitidos a
jerojasro@479 1379 otro repositorio.
jerojasro@479 1380
jerojasro@479 1381 Parámetros para este gancho:
jerojasro@479 1382 \begin{itemize}
jerojasro@479 1383 \item[\texttt{source}] Una cadena. La fuente la operación que está
jerojasro@479 1384 tratando de obtener cambios de éste repositorio (vea
jerojasro@479 1385 la sección~\ref{sec:hook:sources}). Revise la documentación para
jerojasro@479 1386 el parámetro \texttt{source} del gancho \hook{outgoing}, en la
jerojasro@479 1387 sección~\ref{sec:hook:outgoing}, para ver los posibles valores de
jerojasro@479 1388 este parámetro.
jerojasro@479 1389 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@479 1390 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@479 1391 \end{itemize}
jerojasro@479 1392
jerojasro@479 1393 Vea también: \hook{outgoing} (sección~\ref{sec:hook:outgoing})
jerojasro@479 1394
jerojasro@479 1395 \subsection{\hook{pretag}---antes de etiquetar un conjunto de cambios}
jerojasro@477 1396 \label{sec:hook:pretag}
jerojasro@477 1397
jerojasro@479 1398 Este gancho de control es ejecutado antes de la creación de una
jerojasro@479 1399 etiqueta. Si el gancho termina exitosamente, la creación de la
jerojasro@479 1400 etiqueta continúa. Si el gancho falla, no se crea la etiqueta.
jerojasro@479 1401
jerojasro@479 1402 Parámetros para este gancho:
jerojasro@479 1403 \begin{itemize}
jerojasro@479 1404 \item[\texttt{local}] Un booleano. Indica si la etiqueta es local a
jerojasro@479 1405 ésta instancia del repositorio (p.e.~almacenado en
jerojasro@479 1406 \sfilename{.hg/localtags}) o administrado por Mercurial (almacenado
jerojasro@479 1407 en \sfilename{.hgtags}).
jerojasro@479 1408 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del conjunto
jerojasro@479 1409 de cambios a etiquetar.
jerojasro@479 1410 \item[\texttt{tag}] Una cadena. El nombre de la etiqueta por crear.
jerojasro@479 1411 \end{itemize}
jerojasro@479 1412
jerojasro@479 1413 Si la etiqueta que se va a crear se encuentra bajo control de
jerojasro@479 1414 revisiones, los ganchos \hook{precommit} y \hook{pretxncommit}
jerojasro@479 1415 (secciones~\ref{sec:hook:commit} y~\ref{sec:hook:pretxncommit})
jerojasro@479 1416 también serán ejecutados.
jerojasro@479 1417
jerojasro@479 1418 Vea también: \hook{tag} (sección~\ref{sec:hook:tag})
jerojasro@479 1419
jerojasro@479 1420 \subsection{\hook{pretxnchangegroup}---antes de completar la adición
jerojasro@479 1421 de conjuntos de cambios remotos}
jerojasro@477 1422 \label{sec:hook:pretxnchangegroup}
jerojasro@477 1423
jerojasro@479 1424 Este gancho de control es ejecutado antes de una transacción---la que
jerojasro@479 1425 maneja la adición de un grupo de conjuntos de cambios nuevos desde
jerojasro@479 1426 fuera del repositorio---se complete. Si el gancho tiene éxito, la
jerojasro@479 1427 transacción se completa, y todos los conjuntos de cambios se vuelven
jerojasro@479 1428 permanentes dentro de este repositorio. Si el gancho falla, la
jerojasro@479 1429 transacción es deshecha, y los datos para los conjuntos de cambios son
jerojasro@479 1430 eliminados.
jerojasro@479 1431
jerojasro@479 1432 Este gancho puede acceder a los metadatos asociados con los conjuntos
jerojasro@479 1433 de cambios casi añadidos, pero no debe hacer nada permanente con estos
jerojasro@479 1434 datos. Tampoco debe modificar el directorio de trabajo.
jerojasro@479 1435
jerojasro@479 1436 Mientras este gancho está corriendo, si otro proceso Mercurial accesa
jerojasro@479 1437 el repositorio, podrá ver los conjuntos de cambios casi añadidos como
jerojasro@479 1438 si fueran permanentes. Esto puede llevar a condiciones de carrera si
jerojasro@479 1439 usted no toma precauciones para evitarlas.
jerojasro@479 1440
jerojasro@479 1441 Este gancho puede ser usado para examinar automáticamente un grupo de
jerojasro@479 1442 conjuntos de cambios. Si el gancho falla, todos los conjuntos de
jerojasro@479 1443 cambios son ``rechazados'' cuando la transacción se deshace.
jerojasro@479 1444
jerojasro@479 1445 Parámetros para este gancho:
jerojasro@479 1446 \begin{itemize}
jerojasro@479 1447 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del primer
jerojasro@479 1448 conjunto de cambios que fue añadido en el grupo. Todos los
jerojasro@479 1449 conjuntos de cambios entre éste y el
jerojasro@479 1450 \index{tags!\texttt{tip}}\texttt{tip}, inclusive, fueron añadidos
jerojasro@479 1451 por un único \hgcmd{pull}, \hgcmd{push} o \hgcmd{unbundle}.
jerojasro@479 1452 \item[\texttt{source}] Una cadena. La fuente de estos cambios. Vea la
jerojasro@479 1453 sección~\ref{sec:hook:sources} para más detalles.
jerojasro@479 1454 \item[\texttt{url}] Una URL. La ubicación del repositorio remoto, si
jerojasro@479 1455 es conocida. Vea la sección~\ref{sec:hook:url} para más información.
jerojasro@479 1456 \end{itemize}
jerojasro@479 1457
jerojasro@479 1458 Vea también: \hook{changegroup} (sección~\ref{sec:hook:changegroup}),
jerojasro@479 1459 \hook{incoming} (sección~\ref{sec:hook:incoming}),
jerojasro@479 1460 \hook{prechangegroup} (sección~\ref{sec:hook:prechangegroup})
jerojasro@479 1461
jerojasro@479 1462 \subsection{\hook{pretxncommit}---antes de completar la consignación
jerojasro@479 1463 de un nuevo conjunto de cambios}
jerojasro@336 1464 \label{sec:hook:pretxncommit}
jerojasro@336 1465
jerojasro@479 1466 Este gancho de control es ejecutado antes de que una transacción---que
jerojasro@479 1467 maneja una nueva consignación---se complete. Si el gancho tiene éxito,
jerojasro@479 1468 la transacción se completa y el conjunto de cambios se hace permanente
jerojasro@479 1469 dentro de éste repositorio. Si el gancho falla, la transacción es
jerojasro@479 1470 deshecha, y los datos de consignación son borrados.
jerojasro@479 1471
jerojasro@479 1472 Este gancho tiene acceso a los metadatos asociados con el
jerojasro@479 1473 prácticamente nuevo conjunto de cambios, pero no debería hacer nada
jerojasro@479 1474 permanente con estos datos. Tampoco debe modificar el directorio de
jerojasro@479 1475 trabajo.
jerojasro@479 1476
jerojasro@479 1477 Mientras este gancho está corriendo, si otro proceso Mercurial accesa
jerojasro@479 1478 éste repositorio, podrá ver el prácticamente nuevo conjunto de cambios
jerojasro@479 1479 como si fuera permanente. Esto puede llevar a condiciones de carrera si
jerojasro@479 1480 usted no toma precauciones para evitarlas.
jerojasro@479 1481
jerojasro@479 1482 Parámetros para este gancho:
jerojasro@479 1483 \begin{itemize}
jerojasro@479 1484 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del
jerojasro@479 1485 conjunto de cambios recién consignado.
jerojasro@479 1486 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID de
jerojasro@479 1487 conjunto de cambios del primer padre del conjunto de cambios que
jerojasro@479 1488 acaba de ser consignado.
jerojasro@479 1489 \item[\texttt{parent2}] Un ID de conjunto de cambios. El ID de
jerojasro@479 1490 conjunto de cambios del segundo padre del conjunto de cambios que
jerojasro@479 1491 acaba de ser consignado.
jerojasro@479 1492 \end{itemize}
jerojasro@479 1493
jerojasro@479 1494 Vea también: \hook{precommit} (sección~\ref{sec:hook:precommit})
jerojasro@479 1495
jerojasro@479 1496 \subsection{\hook{preupdate}---antes de actualizar o fusionar el
jerojasro@479 1497 directorio de trabajo}
jerojasro@336 1498 \label{sec:hook:preupdate}
jerojasro@336 1499
jerojasro@479 1500 Este gancho de control es ejecutado antes de actualizar o fusionar el
jerojasro@479 1501 directorio de trabajo. Es ejecutado sólo si las revisiones usuales de
jerojasro@479 1502 Mercurial antes de las actualizaciones determinan que la actualización
jerojasro@479 1503 o fusión pueden proceder. Si el gancho termina exitosamente, la
jerojasro@479 1504 actualización o fusión pueden proceder.; si falla, la actualización o
jerojasro@479 1505 fusión no empiezan.
jerojasro@479 1506
jerojasro@479 1507 Parámetros para este gancho:
jerojasro@479 1508 \begin{itemize}
jerojasro@479 1509 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID del
jerojasro@479 1510 padre al que el directorio de trabajo será actualizado. Si se está
jerojasro@479 1511 fusionando el directorio de trabajo, no cambiará este padre.
jerojasro@479 1512 \item[\texttt{parent2}] Un ID de conjunto de cambios. Sólo está
jerojasro@479 1513 definido si se está fusionando el directorio de trabajo. El ID de la
jerojasro@479 1514 revisión con la cual está siendo fusionado el directorio de trabajo.
jerojasro@479 1515 \end{itemize}
jerojasro@479 1516
jerojasro@479 1517 Vea también: \hook{update} (sección~\ref{sec:hook:update})
jerojasro@479 1518
jerojasro@479 1519 \subsection{\hook{tag}---luego de etiquetar un conjunto de cambios}
jerojasro@336 1520 \label{sec:hook:tag}
jerojasro@336 1521
jerojasro@479 1522 Este gancho es ejecutado luego de la creación de una etiqueta.
jerojasro@479 1523
jerojasro@479 1524 Parámetros para este gancho:
jerojasro@479 1525 \begin{itemize}
jerojasro@479 1526 \item[\texttt{local}] Un booleano. Indica si la etiqueta es local a
jerojasro@479 1527 ésta instancia del repositorio (p.e.~almacenado en
jerojasro@479 1528 \sfilename{.hg/localtags}) o administrado por Mercurial (almacenado
jerojasro@479 1529 en \sfilename{.hgtags}).
jerojasro@479 1530 \item[\texttt{node}] Un ID de conjunto de cambios. El ID del
jerojasro@479 1531 conjunto de cambios que fue etiquetado.
jerojasro@479 1532 \item[\texttt{tag}] Una cadena. El nombre de la etiqueta que fue
jerojasro@479 1533 creada.
jerojasro@479 1534 \end{itemize}
jerojasro@479 1535
jerojasro@479 1536 Si la etiqueta creada está bajo control de revisiones, el gancho
jerojasro@479 1537 \hook{commit} (sección~\ref{sec:hook:commit}) es ejecutado antes de
jerojasro@479 1538 este gancho.
jerojasro@479 1539
jerojasro@479 1540 Vea también: \hook{pretag} (sección~\ref{sec:hook:pretag})
jerojasro@479 1541
jerojasro@479 1542 \subsection{\hook{update}---luego de actualizar o fusionar el
jerojasro@479 1543 directorio de trabajo}
jerojasro@336 1544 \label{sec:hook:update}
jerojasro@336 1545
jerojasro@479 1546 Este gancho es ejecutado después de una actualización o fusión en el
jerojasro@479 1547 directorio de trabajo. Ya que una fusión puede fallar (si el comando
jerojasro@479 1548 externo \command{hgmerge} no puede resolver los conflictos en un
jerojasro@479 1549 fichero), este gancho indica si la actualización o fusión fueron
jerojasro@479 1550 completados adecuadamente.
jerojasro@479 1551
jerojasro@479 1552 \begin{itemize}
jerojasro@479 1553 \item[\texttt{error}] Un booleano. Indica si la actualización o fusión
jerojasro@479 1554 fue completada exitosamente.
jerojasro@479 1555 \item[\texttt{parent1}] Un ID de conjunto de cambios. El ID del padre
jerojasro@479 1556 al cual fue actualizado el directorio de trabajo. Si se fusionó el
jerojasro@479 1557 directorio de trabajo, no se habrá cambiado este padre.
jerojasro@479 1558 \item[\texttt{parent2}] Un ID de conjunto de cambios. Sólo está
jerojasro@479 1559 definido si se fusionó el directorio de trabajo. El ID de la
jerojasro@479 1560 revisión con la que fue fusionado el directorio de trabajo.
jerojasro@479 1561 \end{itemize}
jerojasro@479 1562
jerojasro@479 1563 Vea también: \hook{preupdate} (sección~\ref{sec:hook:preupdate})
jerojasro@336 1564
jerojasro@336 1565 %%% Local Variables:
jerojasro@336 1566 %%% mode: latex
jerojasro@336 1567 %%% TeX-master: "00book"
jerojasro@336 1568 %%% End: