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