hgbook
view es/hook.tex @ 438:22391f67dc26
Translated lighttpd and started web options
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Sat Dec 06 00:14:38 2008 -0500 (2008-12-06) |
| parents | 263a8436d72d |
| children | 4e0684e824e1 |
line source
1 \chapter{Manejo de eventos en repositorios mediante ganchos}
2 \label{chap:hook}
4 Mercurial ofrece un poderoso mecanismo para permitirle a usted
5 automatizar la ejecución de acciones en respuesta a eventos que
6 ocurran en un repositorio. En algunos casos, usted puede controlar
7 incluso la respuesta de Mercurial a dichos eventos.
9 Mercurial usa el término \emph{gancho} para identificar estas
10 acciones. Los ganchos son conocidos como ``disparadores'' en algunos
11 sistemas de control de revisiones, pero los dos nombres se refieren al
12 mismo concepto.
14 \section{Vistazo general de ganchos en Mercurial}
16 A continuación se encuentra una breve lista de los ganchos que
17 Mercurial soporta. Volveremos a cada uno de estos ganchos con más
18 detalle después, en la sección~\ref{sec:hook:ref}.
20 \begin{itemize}
21 \item[\small\hook{changegroup}] Es ejecutado luego de que un grupo de
22 conjuntos de cambios ha sido traído al repositorio desde algún
23 otro sitio.
24 \item[\small\hook{commit}] Es ejecutado después de la creación de
25 un conjunto de cambios en el repositorio local.
26 \item[\small\hook{incoming}] Es ejecutado una vez por cada conjunto de
27 cambios traído al repositorio desde otra ubicación. Note la
28 diferencia respecto al gancho \hook{changegroup}, que es ejecutado
29 una vez por cada \emph{grupo} de conjuntos de cambios que se
30 traiga.
31 \item[\small\hook{outgoing}] Es ejecutado luego de que un grupo de
32 conjuntos de cambios ha sido transmitido desde el repositorio.
33 \item[\small\hook{prechangegroup}] Es ejecutado antes de iniciar la
34 recepción de un grupo de conjuntos de cambios en el repositorio.
35 \item[\small\hook{precommit}] De control. Es ejecutado antes de
36 iniciar una consignación.
37 \item[\small\hook{preoutgoing}] De control. Es ejecutado antes de
38 iniciar la transmisión de un grupo de conjuntos de cambios desde
39 el repositorio.
40 \item[\small\hook{pretag}] De control. Es ejecutado antes de crear una
41 etiqueta.
42 \item[\small\hook{pretxnchangegroup}] De control. Es ejecutado después
43 de haber recibido un grupo de conjuntos de cambios en el
44 repositorio local, pero antes de que la transacción se complete y
45 los cambios sean permanentes dentro del repositorio.
46 \item[\small\hook{pretxncommit}] De control. Es ejecutado luego de la
47 creación de un conjunto de cambios en el repositorio local, pero
48 antes de que la transacción que hace permanente el cambio sea
49 completada.
50 \item[\small\hook{preupdate}] De control. Es ejecutado antes de
51 iniciar una actualización o fusión en el directorio de trabajo.
52 \item[\small\hook{tag}] Es ejecutado después de la creación de una
53 etiqueta.
54 \item[\small\hook{update}] Es ejecutado después de que termina una
55 actualización o una fusión.
56 \end{itemize}
57 Cada uno de los ganchos cuya descripción empieza con la frase
58 ``de control'' tiene la facultad de determinar si una actividad puede
59 continuar. Si el gancho se ejecuta con éxito, la actividad puede
60 continuar; si falla, o bien la actividad no es permitida, o se
61 deshacen los cambios que se puedan haber llevado a cabo, dependiendo
62 del gancho involucrado.
64 \section{Ganchos y seguridad}
66 \subsection{Los ganchos se ejecutan con sus privilegios de usuario}
68 Cuando usted ejecuta un comando de Mercurial en un repositorio, y el
69 comando causa la ejecución de un gancho, dicho gancho se ejecuta en
70 \emph{su} sistema, en \emph{su} cuenta de usuario, con \emph{sus}
71 privilegios. Ya que los ganchos son elementos arbitrarios de código
72 ejecutable, usted debería tratarlos con un nivel adecuado de
73 desconfianza. No instale un gancho a menos en que confíe en quien lo
74 creó y en lo que el gancho hace.
76 En algunos casos, usted puede estar expuesto a ganchos que usted no
77 %TODO acá introduzco algo de texto por mi cuenta, por claridad
78 instaló. Si usted usa Mercurial en un sistema extraño, tenga en cuenta
79 que Mercurial ejecutará los ganchos definidos en el fichero \hgrc.
81 Si está trabajando con un repositorio propiedad de otro usuario,
82 Mercurial podrá ejecutar los ganchos definidos en el repositorio de
83 dicho usuario, pero los ejecutará como ``usted''. Por ejemplo, si
84 usted jala (\hgcmd{pull}) desde ese repositorio, y el
85 \sfilename{.hg/hgrc} define un gancho saliente (\hook{outgoing}),
86 dicho gancho se ejecuta bajo su cuenta de usuario, aun cuando usted no
87 es el propietario del repositorio.
89 \begin{note}
90 Esto sólo aplica si usted está jalando desde un repositorio en un
91 sistema de ficheros local o de red. Si está jalando a través de http
92 o ssh, cualquier gancho saliente (\hook{outgoing}) se ejecutará bajo
93 la cuenta que está ejecutando el proceso servidor, en el servidor.
94 \end{note}
96 XXX Para ver qué ganchos han sido definidos en un repositorio, use el
97 comando \hgcmdargs{config}{hooks}. Si usted está trabajando en un
98 repositorio, pero comunicándose con otro que no le pertenece
99 (por ejemplo, usando \hgcmd{pull} o \hgcmd{incoming}), recuerde que
100 los ganchos que debe considerar son los del otro repositorio, no los
101 del suyo.
103 \subsection{Los ganchos no se propagan}
105 En Mercurial, no se hace control de revisiones de los ganchos, y no se
106 propagan cuando usted clona, o jala de, un repositorio. El motivo para
107 esto es simple: un gancho es código ejecutable arbitrario. Se ejecuta
108 bajo su identidad, con su nivel de privilegios, en su máquina.
110 Sería extremadamente descuidado de parte de cualquier sistema
111 distribuido de control de revisiones el implementar control de
112 revisiones para ganchos, ya que esto ofrecería maneras fácilmente
113 %TODO subvertir
114 aprovechables de subvertir las cuentas de los usuarios del sistema de
115 control de revisiones.
117 Ya que Mercurial no propaga los ganchos, si usted está colaborando con
118 otras personas en un proyecto común, no debería asumir que ellos están
119 usando los mismos ganchos para Mercurial que usted usa, o que los de
120 ellos están configurado correctamente. Usted debería documentar los
121 ganchos que usted espera que la gente use.
123 En una intranet corporativa, esto es algo más fácil de manejar, ya que
124 usted puede, por ejemplo, proveer una instalación ``estándar'' de
125 Mercurial en un sistema de ficheros NFS, y usar un fichero \hgrc\
126 global para definir los ganchos que verán todos los usuarios. Sin
127 embargo, este enfoque tiene sus límites; vea más abajo.
129 \subsection{Hooks can be overridden}
131 Mercurial allows you to override a hook definition by redefining the
132 hook. You can disable it by setting its value to the empty string, or
133 change its behaviour as you wish.
135 If you deploy a system-~or site-wide \hgrc\ file that defines some
136 hooks, you should thus understand that your users can disable or
137 override those hooks.
139 \subsection{Ensuring that critical hooks are run}
141 Sometimes you may want to enforce a policy that you do not want others
142 to be able to work around. For example, you may have a requirement
143 that every changeset must pass a rigorous set of tests. Defining this
144 requirement via a hook in a site-wide \hgrc\ won't work for remote
145 users on laptops, and of course local users can subvert it at will by
146 overriding the hook.
148 Instead, you can set up your policies for use of Mercurial so that
149 people are expected to propagate changes through a well-known
150 ``canonical'' server that you have locked down and configured
151 appropriately.
153 One way to do this is via a combination of social engineering and
154 technology. Set up a restricted-access account; users can push
155 changes over the network to repositories managed by this account, but
156 they cannot log into the account and run normal shell commands. In
157 this scenario, a user can commit a changeset that contains any old
158 garbage they want.
160 When someone pushes a changeset to the server that everyone pulls
161 from, the server will test the changeset before it accepts it as
162 permanent, and reject it if it fails to pass the test suite. If
163 people only pull changes from this filtering server, it will serve to
164 ensure that all changes that people pull have been automatically
165 vetted.
167 \section{Care with \texttt{pretxn} hooks in a shared-access repository}
169 If you want to use hooks to do some automated work in a repository
170 that a number of people have shared access to, you need to be careful
171 in how you do this.
173 Mercurial only locks a repository when it is writing to the
174 repository, and only the parts of Mercurial that write to the
175 repository pay attention to locks. Write locks are necessary to
176 prevent multiple simultaneous writers from scribbling on each other's
177 work, corrupting the repository.
179 Because Mercurial is careful with the order in which it reads and
180 writes data, it does not need to acquire a lock when it wants to read
181 data from the repository. The parts of Mercurial that read from the
182 repository never pay attention to locks. This lockless reading scheme
183 greatly increases performance and concurrency.
185 With great performance comes a trade-off, though, one which has the
186 potential to cause you trouble unless you're aware of it. To describe
187 this requires a little detail about how Mercurial adds changesets to a
188 repository and reads those changes.
190 When Mercurial \emph{writes} metadata, it writes it straight into the
191 destination file. It writes file data first, then manifest data
192 (which contains pointers to the new file data), then changelog data
193 (which contains pointers to the new manifest data). Before the first
194 write to each file, it stores a record of where the end of the file
195 was in its transaction log. If the transaction must be rolled back,
196 Mercurial simply truncates each file back to the size it was before the
197 transaction began.
199 When Mercurial \emph{reads} metadata, it reads the changelog first,
200 then everything else. Since a reader will only access parts of the
201 manifest or file metadata that it can see in the changelog, it can
202 never see partially written data.
204 Some controlling hooks (\hook{pretxncommit} and
205 \hook{pretxnchangegroup}) run when a transaction is almost complete.
206 All of the metadata has been written, but Mercurial can still roll the
207 transaction back and cause the newly-written data to disappear.
209 If one of these hooks runs for long, it opens a window of time during
210 which a reader can see the metadata for changesets that are not yet
211 permanent, and should not be thought of as ``really there''. The
212 longer the hook runs, the longer that window is open.
214 \subsection{The problem illustrated}
216 In principle, a good use for the \hook{pretxnchangegroup} hook would
217 be to automatically build and test incoming changes before they are
218 accepted into a central repository. This could let you guarantee that
219 nobody can push changes to this repository that ``break the build''.
220 But if a client can pull changes while they're being tested, the
221 usefulness of the test is zero; an unsuspecting someone can pull
222 untested changes, potentially breaking their build.
224 The safest technological answer to this challenge is to set up such a
225 ``gatekeeper'' repository as \emph{unidirectional}. Let it take
226 changes pushed in from the outside, but do not allow anyone to pull
227 changes from it (use the \hook{preoutgoing} hook to lock it down).
228 Configure a \hook{changegroup} hook so that if a build or test
229 succeeds, the hook will push the new changes out to another repository
230 that people \emph{can} pull from.
232 In practice, putting a centralised bottleneck like this in place is
233 not often a good idea, and transaction visibility has nothing to do
234 with the problem. As the size of a project---and the time it takes to
235 build and test---grows, you rapidly run into a wall with this ``try
236 before you buy'' approach, where you have more changesets to test than
237 time in which to deal with them. The inevitable result is frustration
238 on the part of all involved.
240 An approach that scales better is to get people to build and test
241 before they push, then run automated builds and tests centrally
242 \emph{after} a push, to be sure all is well. The advantage of this
243 approach is that it does not impose a limit on the rate at which the
244 repository can accept changes.
246 \section{A short tutorial on using hooks}
247 \label{sec:hook:simple}
249 It is easy to write a Mercurial hook. Let's start with a hook that
250 runs when you finish a \hgcmd{commit}, and simply prints the hash of
251 the changeset you just created. The hook is called \hook{commit}.
253 \begin{figure}[ht]
254 \interaction{hook.simple.init}
255 \caption{A simple hook that runs when a changeset is committed}
256 \label{ex:hook:init}
257 \end{figure}
259 All hooks follow the pattern in example~\ref{ex:hook:init}. You add
260 an entry to the \rcsection{hooks} section of your \hgrc. On the left
261 is the name of the event to trigger on; on the right is the action to
262 take. As you can see, you can run an arbitrary shell command in a
263 hook. Mercurial passes extra information to the hook using
264 environment variables (look for \envar{HG\_NODE} in the example).
266 \subsection{Performing multiple actions per event}
268 Quite often, you will want to define more than one hook for a
269 particular kind of event, as shown in example~\ref{ex:hook:ext}.
270 Mercurial lets you do this by adding an \emph{extension} to the end of
271 a hook's name. You extend a hook's name by giving the name of the
272 hook, followed by a full stop (the ``\texttt{.}'' character), followed
273 by some more text of your choosing. For example, Mercurial will run
274 both \texttt{commit.foo} and \texttt{commit.bar} when the
275 \texttt{commit} event occurs.
277 \begin{figure}[ht]
278 \interaction{hook.simple.ext}
279 \caption{Defining a second \hook{commit} hook}
280 \label{ex:hook:ext}
281 \end{figure}
283 To give a well-defined order of execution when there are multiple
284 hooks defined for an event, Mercurial sorts hooks by extension, and
285 executes the hook commands in this sorted order. In the above
286 example, it will execute \texttt{commit.bar} before
287 \texttt{commit.foo}, and \texttt{commit} before both.
289 It is a good idea to use a somewhat descriptive extension when you
290 define a new hook. This will help you to remember what the hook was
291 for. If the hook fails, you'll get an error message that contains the
292 hook name and extension, so using a descriptive extension could give
293 you an immediate hint as to why the hook failed (see
294 section~\ref{sec:hook:perm} for an example).
296 \subsection{Controlling whether an activity can proceed}
297 \label{sec:hook:perm}
299 In our earlier examples, we used the \hook{commit} hook, which is
300 run after a commit has completed. This is one of several Mercurial
301 hooks that run after an activity finishes. Such hooks have no way of
302 influencing the activity itself.
304 Mercurial defines a number of events that occur before an activity
305 starts; or after it starts, but before it finishes. Hooks that
306 trigger on these events have the added ability to choose whether the
307 activity can continue, or will abort.
309 The \hook{pretxncommit} hook runs after a commit has all but
310 completed. In other words, the metadata representing the changeset
311 has been written out to disk, but the transaction has not yet been
312 allowed to complete. The \hook{pretxncommit} hook has the ability to
313 decide whether the transaction can complete, or must be rolled back.
315 If the \hook{pretxncommit} hook exits with a status code of zero, the
316 transaction is allowed to complete; the commit finishes; and the
317 \hook{commit} hook is run. If the \hook{pretxncommit} hook exits with
318 a non-zero status code, the transaction is rolled back; the metadata
319 representing the changeset is erased; and the \hook{commit} hook is
320 not run.
322 \begin{figure}[ht]
323 \interaction{hook.simple.pretxncommit}
324 \caption{Using the \hook{pretxncommit} hook to control commits}
325 \label{ex:hook:pretxncommit}
326 \end{figure}
328 The hook in example~\ref{ex:hook:pretxncommit} checks that a commit
329 comment contains a bug ID. If it does, the commit can complete. If
330 not, the commit is rolled back.
332 \section{Writing your own hooks}
334 When you are writing a hook, you might find it useful to run Mercurial
335 either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
336 item set to ``true''. When you do so, Mercurial will print a message
337 before it calls each hook.
339 \subsection{Choosing how your hook should run}
340 \label{sec:hook:lang}
342 You can write a hook either as a normal program---typically a shell
343 script---or as a Python function that is executed within the Mercurial
344 process.
346 Writing a hook as an external program has the advantage that it
347 requires no knowledge of Mercurial's internals. You can call normal
348 Mercurial commands to get any added information you need. The
349 trade-off is that external hooks are slower than in-process hooks.
351 An in-process Python hook has complete access to the Mercurial API,
352 and does not ``shell out'' to another process, so it is inherently
353 faster than an external hook. It is also easier to obtain much of the
354 information that a hook requires by using the Mercurial API than by
355 running Mercurial commands.
357 If you are comfortable with Python, or require high performance,
358 writing your hooks in Python may be a good choice. However, when you
359 have a straightforward hook to write and you don't need to care about
360 performance (probably the majority of hooks), a shell script is
361 perfectly fine.
363 \subsection{Hook parameters}
364 \label{sec:hook:param}
366 Mercurial calls each hook with a set of well-defined parameters. In
367 Python, a parameter is passed as a keyword argument to your hook
368 function. For an external program, a parameter is passed as an
369 environment variable.
371 Whether your hook is written in Python or as a shell script, the
372 hook-specific parameter names and values will be the same. A boolean
373 parameter will be represented as a boolean value in Python, but as the
374 number 1 (for ``true'') or 0 (for ``false'') as an environment
375 variable for an external hook. If a hook parameter is named
376 \texttt{foo}, the keyword argument for a Python hook will also be
377 named \texttt{foo}, while the environment variable for an external
378 hook will be named \texttt{HG\_FOO}.
380 \subsection{Hook return values and activity control}
382 A hook that executes successfully must exit with a status of zero if
383 external, or return boolean ``false'' if in-process. Failure is
384 indicated with a non-zero exit status from an external hook, or an
385 in-process hook returning boolean ``true''. If an in-process hook
386 raises an exception, the hook is considered to have failed.
388 For a hook that controls whether an activity can proceed, zero/false
389 means ``allow'', while non-zero/true/exception means ``deny''.
391 \subsection{Writing an external hook}
393 When you define an external hook in your \hgrc\ and the hook is run,
394 its value is passed to your shell, which interprets it. This means
395 that you can use normal shell constructs in the body of the hook.
397 An executable hook is always run with its current directory set to a
398 repository's root directory.
400 Each hook parameter is passed in as an environment variable; the name
401 is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
403 With the exception of hook parameters, Mercurial does not set or
404 modify any environment variables when running a hook. This is useful
405 to remember if you are writing a site-wide hook that may be run by a
406 number of different users with differing environment variables set.
407 In multi-user situations, you should not rely on environment variables
408 being set to the values you have in your environment when testing the
409 hook.
411 \subsection{Telling Mercurial to use an in-process hook}
413 The \hgrc\ syntax for defining an in-process hook is slightly
414 different than for an executable hook. The value of the hook must
415 start with the text ``\texttt{python:}'', and continue with the
416 fully-qualified name of a callable object to use as the hook's value.
418 The module in which a hook lives is automatically imported when a hook
419 is run. So long as you have the module name and \envar{PYTHONPATH}
420 right, it should ``just work''.
422 The following \hgrc\ example snippet illustrates the syntax and
423 meaning of the notions we just described.
424 \begin{codesample2}
425 [hooks]
426 commit.example = python:mymodule.submodule.myhook
427 \end{codesample2}
428 When Mercurial runs the \texttt{commit.example} hook, it imports
429 \texttt{mymodule.submodule}, looks for the callable object named
430 \texttt{myhook}, and calls it.
432 \subsection{Writing an in-process hook}
434 The simplest in-process hook does nothing, but illustrates the basic
435 shape of the hook API:
436 \begin{codesample2}
437 def myhook(ui, repo, **kwargs):
438 pass
439 \end{codesample2}
440 The first argument to a Python hook is always a
441 \pymodclass{mercurial.ui}{ui} object. The second is a repository object;
442 at the moment, it is always an instance of
443 \pymodclass{mercurial.localrepo}{localrepository}. Following these two
444 arguments are other keyword arguments. Which ones are passed in
445 depends on the hook being called, but a hook can ignore arguments it
446 doesn't care about by dropping them into a keyword argument dict, as
447 with \texttt{**kwargs} above.
449 \section{Some hook examples}
451 \subsection{Writing meaningful commit messages}
453 It's hard to imagine a useful commit message being very short. The
454 simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go}
455 will prevent you from committing a changeset with a message that is
456 less than ten bytes long.
458 \begin{figure}[ht]
459 \interaction{hook.msglen.go}
460 \caption{A hook that forbids overly short commit messages}
461 \label{ex:hook:msglen.go}
462 \end{figure}
464 \subsection{Checking for trailing whitespace}
466 An interesting use of a commit-related hook is to help you to write
467 cleaner code. A simple example of ``cleaner code'' is the dictum that
468 a change should not add any new lines of text that contain ``trailing
469 whitespace''. Trailing whitespace is a series of space and tab
470 characters at the end of a line of text. In most cases, trailing
471 whitespace is unnecessary, invisible noise, but it is occasionally
472 problematic, and people often prefer to get rid of it.
474 You can use either the \hook{precommit} or \hook{pretxncommit} hook to
475 tell whether you have a trailing whitespace problem. If you use the
476 \hook{precommit} hook, the hook will not know which files you are
477 committing, so it will have to check every modified file in the
478 repository for trailing white space. If you want to commit a change
479 to just the file \filename{foo}, but the file \filename{bar} contains
480 trailing whitespace, doing a check in the \hook{precommit} hook will
481 prevent you from committing \filename{foo} due to the problem with
482 \filename{bar}. This doesn't seem right.
484 Should you choose the \hook{pretxncommit} hook, the check won't occur
485 until just before the transaction for the commit completes. This will
486 allow you to check for problems only the exact files that are being
487 committed. However, if you entered the commit message interactively
488 and the hook fails, the transaction will roll back; you'll have to
489 re-enter the commit message after you fix the trailing whitespace and
490 run \hgcmd{commit} again.
492 \begin{figure}[ht]
493 \interaction{hook.ws.simple}
494 \caption{A simple hook that checks for trailing whitespace}
495 \label{ex:hook:ws.simple}
496 \end{figure}
498 Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
499 hook that checks for trailing whitespace. This hook is short, but not
500 very helpful. It exits with an error status if a change adds a line
501 with trailing whitespace to any file, but does not print any
502 information that might help us to identify the offending file or
503 line. It also has the nice property of not paying attention to
504 unmodified lines; only lines that introduce new trailing whitespace
505 cause problems.
507 \begin{figure}[ht]
508 \interaction{hook.ws.better}
509 \caption{A better trailing whitespace hook}
510 \label{ex:hook:ws.better}
511 \end{figure}
513 The example of figure~\ref{ex:hook:ws.better} is much more complex,
514 but also more useful. It parses a unified diff to see if any lines
515 add trailing whitespace, and prints the name of the file and the line
516 number of each such occurrence. Even better, if the change adds
517 trailing whitespace, this hook saves the commit comment and prints the
518 name of the save file before exiting and telling Mercurial to roll the
519 transaction back, so you can use
520 \hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
521 saved commit message once you've corrected the problem.
523 As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
524 \command{perl}'s in-place editing feature to get rid of trailing
525 whitespace from a file. This is concise and useful enough that I will
526 reproduce it here.
527 \begin{codesample2}
528 perl -pi -e 's,\\s+\$,,' filename
529 \end{codesample2}
531 \section{Bundled hooks}
533 Mercurial ships with several bundled hooks. You can find them in the
534 \dirname{hgext} directory of a Mercurial source tree. If you are
535 using a Mercurial binary package, the hooks will be located in the
536 \dirname{hgext} directory of wherever your package installer put
537 Mercurial.
539 \subsection{\hgext{acl}---access control for parts of a repository}
541 The \hgext{acl} extension lets you control which remote users are
542 allowed to push changesets to a networked server. You can protect any
543 portion of a repository (including the entire repo), so that a
544 specific remote user can push changes that do not affect the protected
545 portion.
547 This extension implements access control based on the identity of the
548 user performing a push, \emph{not} on who committed the changesets
549 they're pushing. It makes sense to use this hook only if you have a
550 locked-down server environment that authenticates remote users, and
551 you want to be sure that only specific users are allowed to push
552 changes to that server.
554 \subsubsection{Configuring the \hook{acl} hook}
556 In order to manage incoming changesets, the \hgext{acl} hook must be
557 used as a \hook{pretxnchangegroup} hook. This lets it see which files
558 are modified by each incoming changeset, and roll back a group of
559 changesets if they modify ``forbidden'' files. Example:
560 \begin{codesample2}
561 [hooks]
562 pretxnchangegroup.acl = python:hgext.acl.hook
563 \end{codesample2}
565 The \hgext{acl} extension is configured using three sections.
567 The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
568 which lists the sources of incoming changesets that the hook should
569 pay attention to. You don't normally need to configure this section.
570 \begin{itemize}
571 \item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
572 from a remote repository over http or ssh. This is the default
573 value of \rcitem{acl}{sources}, and usually the only setting you'll
574 need for this configuration item.
575 \item[\rcitem{acl}{pull}] Control incoming changesets that are
576 arriving via a pull from a local repository.
577 \item[\rcitem{acl}{push}] Control incoming changesets that are
578 arriving via a push from a local repository.
579 \item[\rcitem{acl}{bundle}] Control incoming changesets that are
580 arriving from another repository via a bundle.
581 \end{itemize}
583 The \rcsection{acl.allow} section controls the users that are allowed to
584 add changesets to the repository. If this section is not present, all
585 users that are not explicitly denied are allowed. If this section is
586 present, all users that are not explicitly allowed are denied (so an
587 empty section means that all users are denied).
589 The \rcsection{acl.deny} section determines which users are denied
590 from adding changesets to the repository. If this section is not
591 present or is empty, no users are denied.
593 The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
594 sections are identical. On the left of each entry is a glob pattern
595 that matches files or directories, relative to the root of the
596 repository; on the right, a user name.
598 In the following example, the user \texttt{docwriter} can only push
599 changes to the \dirname{docs} subtree of the repository, while
600 \texttt{intern} can push changes to any file or directory except
601 \dirname{source/sensitive}.
602 \begin{codesample2}
603 [acl.allow]
604 docs/** = docwriter
606 [acl.deny]
607 source/sensitive/** = intern
608 \end{codesample2}
610 \subsubsection{Testing and troubleshooting}
612 If you want to test the \hgext{acl} hook, run it with Mercurial's
613 debugging output enabled. Since you'll probably be running it on a
614 server where it's not convenient (or sometimes possible) to pass in
615 the \hggopt{--debug} option, don't forget that you can enable
616 debugging output in your \hgrc:
617 \begin{codesample2}
618 [ui]
619 debug = true
620 \end{codesample2}
621 With this enabled, the \hgext{acl} hook will print enough information
622 to let you figure out why it is allowing or forbidding pushes from
623 specific users.
625 \subsection{\hgext{bugzilla}---integration with Bugzilla}
627 The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
628 whenever it finds a reference to that bug ID in a commit comment. You
629 can install this hook on a shared server, so that any time a remote
630 user pushes changes to this server, the hook gets run.
632 It adds a comment to the bug that looks like this (you can configure
633 the contents of the comment---see below):
634 \begin{codesample2}
635 Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
636 the frobnitz repository, refers to this bug.
638 For complete details, see
639 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
641 Changeset description:
642 Fix bug 10483 by guarding against some NULL pointers
643 \end{codesample2}
644 The value of this hook is that it automates the process of updating a
645 bug any time a changeset refers to it. If you configure the hook
646 properly, it makes it easy for people to browse straight from a
647 Bugzilla bug to a changeset that refers to that bug.
649 You can use the code in this hook as a starting point for some more
650 exotic Bugzilla integration recipes. Here are a few possibilities:
651 \begin{itemize}
652 \item Require that every changeset pushed to the server have a valid
653 bug~ID in its commit comment. In this case, you'd want to configure
654 the hook as a \hook{pretxncommit} hook. This would allow the hook
655 to reject changes that didn't contain bug IDs.
656 \item Allow incoming changesets to automatically modify the
657 \emph{state} of a bug, as well as simply adding a comment. For
658 example, the hook could recognise the string ``fixed bug 31337'' as
659 indicating that it should update the state of bug 31337 to
660 ``requires testing''.
661 \end{itemize}
663 \subsubsection{Configuring the \hook{bugzilla} hook}
664 \label{sec:hook:bugzilla:config}
666 You should configure this hook in your server's \hgrc\ as an
667 \hook{incoming} hook, for example as follows:
668 \begin{codesample2}
669 [hooks]
670 incoming.bugzilla = python:hgext.bugzilla.hook
671 \end{codesample2}
673 Because of the specialised nature of this hook, and because Bugzilla
674 was not written with this kind of integration in mind, configuring
675 this hook is a somewhat involved process.
677 Before you begin, you must install the MySQL bindings for Python on
678 the host(s) where you'll be running the hook. If this is not
679 available as a binary package for your system, you can download it
680 from~\cite{web:mysql-python}.
682 Configuration information for this hook lives in the
683 \rcsection{bugzilla} section of your \hgrc.
684 \begin{itemize}
685 \item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
686 the server. The database schema that Bugzilla uses changes
687 occasionally, so this hook has to know exactly which schema to use.
688 At the moment, the only version supported is \texttt{2.16}.
689 \item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
690 stores your Bugzilla data. The database must be configured to allow
691 connections from whatever host you are running the \hook{bugzilla}
692 hook on.
693 \item[\rcitem{bugzilla}{user}] The username with which to connect to
694 the MySQL server. The database must be configured to allow this
695 user to connect from whatever host you are running the
696 \hook{bugzilla} hook on. This user must be able to access and
697 modify Bugzilla tables. The default value of this item is
698 \texttt{bugs}, which is the standard name of the Bugzilla user in a
699 MySQL database.
700 \item[\rcitem{bugzilla}{password}] The MySQL password for the user you
701 configured above. This is stored as plain text, so you should make
702 sure that unauthorised users cannot read the \hgrc\ file where you
703 store this information.
704 \item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
705 MySQL server. The default value of this item is \texttt{bugs},
706 which is the standard name of the MySQL database where Bugzilla
707 stores its data.
708 \item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
709 notification email to subscribers after this hook has added a
710 comment to a bug, you will need this hook to run a command whenever
711 it updates the database. The command to run depends on where you
712 have installed Bugzilla, but it will typically look something like
713 this, if you have Bugzilla installed in
714 \dirname{/var/www/html/bugzilla}:
715 \begin{codesample4}
716 cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
717 \end{codesample4}
718 The Bugzilla \texttt{processmail} program expects to be given a
719 bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
720 email address. It also expects to be able to write to some files in
721 the directory that it runs in. If Bugzilla and this hook are not
722 installed on the same machine, you will need to find a way to run
723 \texttt{processmail} on the server where Bugzilla is installed.
724 \end{itemize}
726 \subsubsection{Mapping committer names to Bugzilla user names}
728 By default, the \hgext{bugzilla} hook tries to use the email address
729 of a changeset's committer as the Bugzilla user name with which to
730 update a bug. If this does not suit your needs, you can map committer
731 email addresses to Bugzilla user names using a \rcsection{usermap}
732 section.
734 Each item in the \rcsection{usermap} section contains an email address
735 on the left, and a Bugzilla user name on the right.
736 \begin{codesample2}
737 [usermap]
738 jane.user@example.com = jane
739 \end{codesample2}
740 You can either keep the \rcsection{usermap} data in a normal \hgrc, or
741 tell the \hgext{bugzilla} hook to read the information from an
742 external \filename{usermap} file. In the latter case, you can store
743 \filename{usermap} data by itself in (for example) a user-modifiable
744 repository. This makes it possible to let your users maintain their
745 own \rcitem{bugzilla}{usermap} entries. The main \hgrc\ file might
746 look like this:
747 \begin{codesample2}
748 # regular hgrc file refers to external usermap file
749 [bugzilla]
750 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
751 \end{codesample2}
752 While the \filename{usermap} file that it refers to might look like
753 this:
754 \begin{codesample2}
755 # bugzilla-usermap.conf - inside a hg repository
756 [usermap]
757 stephanie@example.com = steph
758 \end{codesample2}
760 \subsubsection{Configuring the text that gets added to a bug}
762 You can configure the text that this hook adds as a comment; you
763 specify it in the form of a Mercurial template. Several \hgrc\
764 entries (still in the \rcsection{bugzilla} section) control this
765 behaviour.
766 \begin{itemize}
767 \item[\texttt{strip}] The number of leading path elements to strip
768 from a repository's path name to construct a partial path for a URL.
769 For example, if the repositories on your server live under
770 \dirname{/home/hg/repos}, and you have a repository whose path is
771 \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
772 \texttt{4} will give a partial path of \dirname{app/tests}. The
773 hook will make this partial path available when expanding a
774 template, as \texttt{webroot}.
775 \item[\texttt{template}] The text of the template to use. In addition
776 to the usual changeset-related variables, this template can use
777 \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
778 above) and \texttt{webroot} (the path constructed using
779 \texttt{strip} above).
780 \end{itemize}
782 In addition, you can add a \rcitem{web}{baseurl} item to the
783 \rcsection{web} section of your \hgrc. The \hgext{bugzilla} hook will
784 make this available when expanding a template, as the base string to
785 use when constructing a URL that will let users browse from a Bugzilla
786 comment to view a changeset. Example:
787 \begin{codesample2}
788 [web]
789 baseurl = http://hg.domain.com/
790 \end{codesample2}
792 Here is an example set of \hgext{bugzilla} hook config information.
793 \begin{codesample2}
794 [bugzilla]
795 host = bugzilla.example.com
796 password = mypassword
797 version = 2.16
798 # server-side repos live in /home/hg/repos, so strip 4 leading
799 # separators
800 strip = 4
801 hgweb = http://hg.example.com/
802 usermap = /home/hg/repos/notify/bugzilla.conf
803 template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
804 repo, refers to this bug.\\nFor complete details, see
805 \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
806 description:\\n\\t\{desc|tabindent\}
807 \end{codesample2}
809 \subsubsection{Testing and troubleshooting}
811 The most common problems with configuring the \hgext{bugzilla} hook
812 relate to running Bugzilla's \filename{processmail} script and mapping
813 committer names to user names.
815 Recall from section~\ref{sec:hook:bugzilla:config} above that the user
816 that runs the Mercurial process on the server is also the one that
817 will run the \filename{processmail} script. The
818 \filename{processmail} script sometimes causes Bugzilla to write to
819 files in its configuration directory, and Bugzilla's configuration
820 files are usually owned by the user that your web server runs under.
822 You can cause \filename{processmail} to be run with the suitable
823 user's identity using the \command{sudo} command. Here is an example
824 entry for a \filename{sudoers} file.
825 \begin{codesample2}
826 hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
827 \end{codesample2}
828 This allows the \texttt{hg\_user} user to run a
829 \filename{processmail-wrapper} program under the identity of
830 \texttt{httpd\_user}.
832 This indirection through a wrapper script is necessary, because
833 \filename{processmail} expects to be run with its current directory
834 set to wherever you installed Bugzilla; you can't specify that kind of
835 constraint in a \filename{sudoers} file. The contents of the wrapper
836 script are simple:
837 \begin{codesample2}
838 #!/bin/sh
839 cd `dirname $0` && ./processmail "$1" nobody@example.com
840 \end{codesample2}
841 It doesn't seem to matter what email address you pass to
842 \filename{processmail}.
844 If your \rcsection{usermap} is not set up correctly, users will see an
845 error message from the \hgext{bugzilla} hook when they push changes
846 to the server. The error message will look like this:
847 \begin{codesample2}
848 cannot find bugzilla user id for john.q.public@example.com
849 \end{codesample2}
850 What this means is that the committer's address,
851 \texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
852 nor does it have an entry in your \rcsection{usermap} that maps it to
853 a valid Bugzilla user name.
855 \subsection{\hgext{notify}---send email notifications}
857 Although Mercurial's built-in web server provides RSS feeds of changes
858 in every repository, many people prefer to receive change
859 notifications via email. The \hgext{notify} hook lets you send out
860 notifications to a set of email addresses whenever changesets arrive
861 that those subscribers are interested in.
863 As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
864 template-driven, so you can customise the contents of the notification
865 messages that it sends.
867 By default, the \hgext{notify} hook includes a diff of every changeset
868 that it sends out; you can limit the size of the diff, or turn this
869 feature off entirely. It is useful for letting subscribers review
870 changes immediately, rather than clicking to follow a URL.
872 \subsubsection{Configuring the \hgext{notify} hook}
874 You can set up the \hgext{notify} hook to send one email message per
875 incoming changeset, or one per incoming group of changesets (all those
876 that arrived in a single pull or push).
877 \begin{codesample2}
878 [hooks]
879 # send one email per group of changes
880 changegroup.notify = python:hgext.notify.hook
881 # send one email per change
882 incoming.notify = python:hgext.notify.hook
883 \end{codesample2}
885 Configuration information for this hook lives in the
886 \rcsection{notify} section of a \hgrc\ file.
887 \begin{itemize}
888 \item[\rcitem{notify}{test}] By default, this hook does not send out
889 email at all; instead, it prints the message that it \emph{would}
890 send. Set this item to \texttt{false} to allow email to be sent.
891 The reason that sending of email is turned off by default is that it
892 takes several tries to configure this extension exactly as you would
893 like, and it would be bad form to spam subscribers with a number of
894 ``broken'' notifications while you debug your configuration.
895 \item[\rcitem{notify}{config}] The path to a configuration file that
896 contains subscription information. This is kept separate from the
897 main \hgrc\ so that you can maintain it in a repository of its own.
898 People can then clone that repository, update their subscriptions,
899 and push the changes back to your server.
900 \item[\rcitem{notify}{strip}] The number of leading path separator
901 characters to strip from a repository's path, when deciding whether
902 a repository has subscribers. For example, if the repositories on
903 your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
904 considering a repository named \dirname{/home/hg/repos/shared/test},
905 setting \rcitem{notify}{strip} to \texttt{4} will cause
906 \hgext{notify} to trim the path it considers down to
907 \dirname{shared/test}, and it will match subscribers against that.
908 \item[\rcitem{notify}{template}] The template text to use when sending
909 messages. This specifies both the contents of the message header
910 and its body.
911 \item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
912 data to append to the end of a message. If a diff is longer than
913 this, it is truncated. By default, this is set to 300. Set this to
914 \texttt{0} to omit diffs from notification emails.
915 \item[\rcitem{notify}{sources}] A list of sources of changesets to
916 consider. This lets you limit \hgext{notify} to only sending out
917 email about changes that remote users pushed into this repository
918 via a server, for example. See section~\ref{sec:hook:sources} for
919 the sources you can specify here.
920 \end{itemize}
922 If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
923 section, you can use it in a template; it will be available as
924 \texttt{webroot}.
926 Here is an example set of \hgext{notify} configuration information.
927 \begin{codesample2}
928 [notify]
929 # really send email
930 test = false
931 # subscriber data lives in the notify repo
932 config = /home/hg/repos/notify/notify.conf
933 # repos live in /home/hg/repos on server, so strip 4 "/" chars
934 strip = 4
935 template = X-Hg-Repo: \{webroot\}
936 Subject: \{webroot\}: \{desc|firstline|strip\}
937 From: \{author\}
939 changeset \{node|short\} in \{root\}
940 details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
941 description:
942 \{desc|tabindent|strip\}
944 [web]
945 baseurl = http://hg.example.com/
946 \end{codesample2}
948 This will produce a message that looks like the following:
949 \begin{codesample2}
950 X-Hg-Repo: tests/slave
951 Subject: tests/slave: Handle error case when slave has no buffers
952 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
954 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
955 details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
956 description:
957 Handle error case when slave has no buffers
958 diffs (54 lines):
960 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
961 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
962 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
963 @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
964 [...snip...]
965 \end{codesample2}
967 \subsubsection{Testing and troubleshooting}
969 Do not forget that by default, the \hgext{notify} extension \emph{will
970 not send any mail} until you explicitly configure it to do so, by
971 setting \rcitem{notify}{test} to \texttt{false}. Until you do that,
972 it simply prints the message it \emph{would} send.
974 \section{Information for writers of hooks}
975 \label{sec:hook:ref}
977 \subsection{In-process hook execution}
979 An in-process hook is called with arguments of the following form:
980 \begin{codesample2}
981 def myhook(ui, repo, **kwargs):
982 pass
983 \end{codesample2}
984 The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
985 The \texttt{repo} parameter is a
986 \pymodclass{mercurial.localrepo}{localrepository} object. The
987 names and values of the \texttt{**kwargs} parameters depend on the
988 hook being invoked, with the following common features:
989 \begin{itemize}
990 \item If a parameter is named \texttt{node} or
991 \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
992 The empty string is used to represent ``null changeset ID'' instead
993 of a string of zeroes.
994 \item If a parameter is named \texttt{url}, it will contain the URL of
995 a remote repository, if that can be determined.
996 \item Boolean-valued parameters are represented as Python
997 \texttt{bool} objects.
998 \end{itemize}
1000 An in-process hook is called without a change to the process's working
1001 directory (unlike external hooks, which are run in the root of the
1002 repository). It must not change the process's working directory, or
1003 it will cause any calls it makes into the Mercurial API to fail.
1005 If a hook returns a boolean ``false'' value, it is considered to have
1006 succeeded. If it returns a boolean ``true'' value or raises an
1007 exception, it is considered to have failed. A useful way to think of
1008 the calling convention is ``tell me if you fail''.
1010 Note that changeset IDs are passed into Python hooks as hexadecimal
1011 strings, not the binary hashes that Mercurial's APIs normally use. To
1012 convert a hash from hex to binary, use the
1013 \pymodfunc{mercurial.node}{bin} function.
1015 \subsection{External hook execution}
1017 An external hook is passed to the shell of the user running Mercurial.
1018 Features of that shell, such as variable substitution and command
1019 redirection, are available. The hook is run in the root directory of
1020 the repository (unlike in-process hooks, which are run in the same
1021 directory that Mercurial was run in).
1023 Hook parameters are passed to the hook as environment variables. Each
1024 environment variable's name is converted in upper case and prefixed
1025 with the string ``\texttt{HG\_}''. For example, if the name of a
1026 parameter is ``\texttt{node}'', the name of the environment variable
1027 representing that parameter will be ``\texttt{HG\_NODE}''.
1029 A boolean parameter is represented as the string ``\texttt{1}'' for
1030 ``true'', ``\texttt{0}'' for ``false''. If an environment variable is
1031 named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
1032 contains a changeset ID represented as a hexadecimal string. The
1033 empty string is used to represent ``null changeset ID'' instead of a
1034 string of zeroes. If an environment variable is named
1035 \envar{HG\_URL}, it will contain the URL of a remote repository, if
1036 that can be determined.
1038 If a hook exits with a status of zero, it is considered to have
1039 succeeded. If it exits with a non-zero status, it is considered to
1040 have failed.
1042 \subsection{Finding out where changesets come from}
1044 A hook that involves the transfer of changesets between a local
1045 repository and another may be able to find out information about the
1046 ``far side''. Mercurial knows \emph{how} changes are being
1047 transferred, and in many cases \emph{where} they are being transferred
1048 to or from.
1050 \subsubsection{Sources of changesets}
1051 \label{sec:hook:sources}
1053 Mercurial will tell a hook what means are, or were, used to transfer
1054 changesets between repositories. This is provided by Mercurial in a
1055 Python parameter named \texttt{source}, or an environment variable named
1056 \envar{HG\_SOURCE}.
1058 \begin{itemize}
1059 \item[\texttt{serve}] Changesets are transferred to or from a remote
1060 repository over http or ssh.
1061 \item[\texttt{pull}] Changesets are being transferred via a pull from
1062 one repository into another.
1063 \item[\texttt{push}] Changesets are being transferred via a push from
1064 one repository into another.
1065 \item[\texttt{bundle}] Changesets are being transferred to or from a
1066 bundle.
1067 \end{itemize}
1069 \subsubsection{Where changes are going---remote repository URLs}
1070 \label{sec:hook:url}
1072 When possible, Mercurial will tell a hook the location of the ``far
1073 side'' of an activity that transfers changeset data between
1074 repositories. This is provided by Mercurial in a Python parameter
1075 named \texttt{url}, or an environment variable named \envar{HG\_URL}.
1077 This information is not always known. If a hook is invoked in a
1078 repository that is being served via http or ssh, Mercurial cannot tell
1079 where the remote repository is, but it may know where the client is
1080 connecting from. In such cases, the URL will take one of the
1081 following forms:
1082 \begin{itemize}
1083 \item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
1084 the given IP address.
1085 \item \texttt{remote:http:\emph{ip-address}}---remote http client, at
1086 the given IP address. If the client is using SSL, this will be of
1087 the form \texttt{remote:https:\emph{ip-address}}.
1088 \item Empty---no information could be discovered about the remote
1089 client.
1090 \end{itemize}
1092 \section{Hook reference}
1094 \subsection{\hook{changegroup}---after remote changesets added}
1095 \label{sec:hook:changegroup}
1097 This hook is run after a group of pre-existing changesets has been
1098 added to the repository, for example via a \hgcmd{pull} or
1099 \hgcmd{unbundle}. This hook is run once per operation that added one
1100 or more changesets. This is in contrast to the \hook{incoming} hook,
1101 which is run once per changeset, regardless of whether the changesets
1102 arrive in a group.
1104 Some possible uses for this hook include kicking off an automated
1105 build or test of the added changesets, updating a bug database, or
1106 notifying subscribers that a repository contains new changes.
1108 Parameters to this hook:
1109 \begin{itemize}
1110 \item[\texttt{node}] A changeset ID. The changeset ID of the first
1111 changeset in the group that was added. All changesets between this
1112 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
1113 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
1114 \item[\texttt{source}] A string. The source of these changes. See
1115 section~\ref{sec:hook:sources} for details.
1116 \item[\texttt{url}] A URL. The location of the remote repository, if
1117 known. See section~\ref{sec:hook:url} for more information.
1118 \end{itemize}
1120 See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
1121 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
1122 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
1124 \subsection{\hook{commit}---after a new changeset is created}
1125 \label{sec:hook:commit}
1127 This hook is run after a new changeset has been created.
1129 Parameters to this hook:
1130 \begin{itemize}
1131 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
1132 committed changeset.
1133 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
1134 parent of the newly committed changeset.
1135 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
1136 parent of the newly committed changeset.
1137 \end{itemize}
1139 See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
1140 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
1142 \subsection{\hook{incoming}---after one remote changeset is added}
1143 \label{sec:hook:incoming}
1145 This hook is run after a pre-existing changeset has been added to the
1146 repository, for example via a \hgcmd{push}. If a group of changesets
1147 was added in a single operation, this hook is called once for each
1148 added changeset.
1150 You can use this hook for the same purposes as the \hook{changegroup}
1151 hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
1152 sometimes to run a hook once per group of changesets, while other
1153 times it's handier once per changeset.
1155 Parameters to this hook:
1156 \begin{itemize}
1157 \item[\texttt{node}] A changeset ID. The ID of the newly added
1158 changeset.
1159 \item[\texttt{source}] A string. The source of these changes. See
1160 section~\ref{sec:hook:sources} for details.
1161 \item[\texttt{url}] A URL. The location of the remote repository, if
1162 known. See section~\ref{sec:hook:url} for more information.
1163 \end{itemize}
1165 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
1167 \subsection{\hook{outgoing}---after changesets are propagated}
1168 \label{sec:hook:outgoing}
1170 This hook is run after a group of changesets has been propagated out
1171 of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
1172 command.
1174 One possible use for this hook is to notify administrators that
1175 changes have been pulled.
1177 Parameters to this hook:
1178 \begin{itemize}
1179 \item[\texttt{node}] A changeset ID. The changeset ID of the first
1180 changeset of the group that was sent.
1181 \item[\texttt{source}] A string. The source of the of the operation
1182 (see section~\ref{sec:hook:sources}). If a remote client pulled
1183 changes from this repository, \texttt{source} will be
1184 \texttt{serve}. If the client that obtained changes from this
1185 repository was local, \texttt{source} will be \texttt{bundle},
1186 \texttt{pull}, or \texttt{push}, depending on the operation the
1187 client performed.
1188 \item[\texttt{url}] A URL. The location of the remote repository, if
1189 known. See section~\ref{sec:hook:url} for more information.
1190 \end{itemize}
1192 See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
1194 \subsection{\hook{prechangegroup}---before starting to add remote changesets}
1195 \label{sec:hook:prechangegroup}
1197 This controlling hook is run before Mercurial begins to add a group of
1198 changesets from another repository.
1200 This hook does not have any information about the changesets to be
1201 added, because it is run before transmission of those changesets is
1202 allowed to begin. If this hook fails, the changesets will not be
1203 transmitted.
1205 One use for this hook is to prevent external changes from being added
1206 to a repository. For example, you could use this to ``freeze'' a
1207 server-hosted branch temporarily or permanently so that users cannot
1208 push to it, while still allowing a local administrator to modify the
1209 repository.
1211 Parameters to this hook:
1212 \begin{itemize}
1213 \item[\texttt{source}] A string. The source of these changes. See
1214 section~\ref{sec:hook:sources} for details.
1215 \item[\texttt{url}] A URL. The location of the remote repository, if
1216 known. See section~\ref{sec:hook:url} for more information.
1217 \end{itemize}
1219 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
1220 \hook{incoming} (section~\ref{sec:hook:incoming}), ,
1221 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
1223 \subsection{\hook{precommit}---before starting to commit a changeset}
1224 \label{sec:hook:precommit}
1226 This hook is run before Mercurial begins to commit a new changeset.
1227 It is run before Mercurial has any of the metadata for the commit,
1228 such as the files to be committed, the commit message, or the commit
1229 date.
1231 One use for this hook is to disable the ability to commit new
1232 changesets, while still allowing incoming changesets. Another is to
1233 run a build or test, and only allow the commit to begin if the build
1234 or test succeeds.
1236 Parameters to this hook:
1237 \begin{itemize}
1238 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
1239 parent of the working directory.
1240 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
1241 parent of the working directory.
1242 \end{itemize}
1243 If the commit proceeds, the parents of the working directory will
1244 become the parents of the new changeset.
1246 See also: \hook{commit} (section~\ref{sec:hook:commit}),
1247 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
1249 \subsection{\hook{preoutgoing}---before starting to propagate changesets}
1250 \label{sec:hook:preoutgoing}
1252 This hook is invoked before Mercurial knows the identities of the
1253 changesets to be transmitted.
1255 One use for this hook is to prevent changes from being transmitted to
1256 another repository.
1258 Parameters to this hook:
1259 \begin{itemize}
1260 \item[\texttt{source}] A string. The source of the operation that is
1261 attempting to obtain changes from this repository (see
1262 section~\ref{sec:hook:sources}). See the documentation for the
1263 \texttt{source} parameter to the \hook{outgoing} hook, in
1264 section~\ref{sec:hook:outgoing}, for possible values of this
1265 parameter.
1266 \item[\texttt{url}] A URL. The location of the remote repository, if
1267 known. See section~\ref{sec:hook:url} for more information.
1268 \end{itemize}
1270 See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
1272 \subsection{\hook{pretag}---before tagging a changeset}
1273 \label{sec:hook:pretag}
1275 This controlling hook is run before a tag is created. If the hook
1276 succeeds, creation of the tag proceeds. If the hook fails, the tag is
1277 not created.
1279 Parameters to this hook:
1280 \begin{itemize}
1281 \item[\texttt{local}] A boolean. Whether the tag is local to this
1282 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
1283 managed by Mercurial (stored in \sfilename{.hgtags}).
1284 \item[\texttt{node}] A changeset ID. The ID of the changeset to be tagged.
1285 \item[\texttt{tag}] A string. The name of the tag to be created.
1286 \end{itemize}
1288 If the tag to be created is revision-controlled, the \hook{precommit}
1289 and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
1290 and~\ref{sec:hook:pretxncommit}) will also be run.
1292 See also: \hook{tag} (section~\ref{sec:hook:tag})
1294 \subsection{\hook{pretxnchangegroup}---before completing addition of
1295 remote changesets}
1296 \label{sec:hook:pretxnchangegroup}
1298 This controlling hook is run before a transaction---that manages the
1299 addition of a group of new changesets from outside the
1300 repository---completes. If the hook succeeds, the transaction
1301 completes, and all of the changesets become permanent within this
1302 repository. If the hook fails, the transaction is rolled back, and
1303 the data for the changesets is erased.
1305 This hook can access the metadata associated with the almost-added
1306 changesets, but it should not do anything permanent with this data.
1307 It must also not modify the working directory.
1309 While this hook is running, if other Mercurial processes access this
1310 repository, they will be able to see the almost-added changesets as if
1311 they are permanent. This may lead to race conditions if you do not
1312 take steps to avoid them.
1314 This hook can be used to automatically vet a group of changesets. If
1315 the hook fails, all of the changesets are ``rejected'' when the
1316 transaction rolls back.
1318 Parameters to this hook:
1319 \begin{itemize}
1320 \item[\texttt{node}] A changeset ID. The changeset ID of the first
1321 changeset in the group that was added. All changesets between this
1322 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
1323 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
1324 \item[\texttt{source}] A string. The source of these changes. See
1325 section~\ref{sec:hook:sources} for details.
1326 \item[\texttt{url}] A URL. The location of the remote repository, if
1327 known. See section~\ref{sec:hook:url} for more information.
1328 \end{itemize}
1330 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
1331 \hook{incoming} (section~\ref{sec:hook:incoming}),
1332 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
1334 \subsection{\hook{pretxncommit}---before completing commit of new changeset}
1335 \label{sec:hook:pretxncommit}
1337 This controlling hook is run before a transaction---that manages a new
1338 commit---completes. If the hook succeeds, the transaction completes
1339 and the changeset becomes permanent within this repository. If the
1340 hook fails, the transaction is rolled back, and the commit data is
1341 erased.
1343 This hook can access the metadata associated with the almost-new
1344 changeset, but it should not do anything permanent with this data. It
1345 must also not modify the working directory.
1347 While this hook is running, if other Mercurial processes access this
1348 repository, they will be able to see the almost-new changeset as if it
1349 is permanent. This may lead to race conditions if you do not take
1350 steps to avoid them.
1352 Parameters to this hook:
1353 \begin{itemize}
1354 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
1355 committed changeset.
1356 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
1357 parent of the newly committed changeset.
1358 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
1359 parent of the newly committed changeset.
1360 \end{itemize}
1362 See also: \hook{precommit} (section~\ref{sec:hook:precommit})
1364 \subsection{\hook{preupdate}---before updating or merging working directory}
1365 \label{sec:hook:preupdate}
1367 This controlling hook is run before an update or merge of the working
1368 directory begins. It is run only if Mercurial's normal pre-update
1369 checks determine that the update or merge can proceed. If the hook
1370 succeeds, the update or merge may proceed; if it fails, the update or
1371 merge does not start.
1373 Parameters to this hook:
1374 \begin{itemize}
1375 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
1376 working directory is to be updated to. If the working directory is
1377 being merged, it will not change this parent.
1378 \item[\texttt{parent2}] A changeset ID. Only set if the working
1379 directory is being merged. The ID of the revision that the working
1380 directory is being merged with.
1381 \end{itemize}
1383 See also: \hook{update} (section~\ref{sec:hook:update})
1385 \subsection{\hook{tag}---after tagging a changeset}
1386 \label{sec:hook:tag}
1388 This hook is run after a tag has been created.
1390 Parameters to this hook:
1391 \begin{itemize}
1392 \item[\texttt{local}] A boolean. Whether the new tag is local to this
1393 repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
1394 managed by Mercurial (stored in \sfilename{.hgtags}).
1395 \item[\texttt{node}] A changeset ID. The ID of the changeset that was
1396 tagged.
1397 \item[\texttt{tag}] A string. The name of the tag that was created.
1398 \end{itemize}
1400 If the created tag is revision-controlled, the \hook{commit} hook
1401 (section~\ref{sec:hook:commit}) is run before this hook.
1403 See also: \hook{pretag} (section~\ref{sec:hook:pretag})
1405 \subsection{\hook{update}---after updating or merging working directory}
1406 \label{sec:hook:update}
1408 This hook is run after an update or merge of the working directory
1409 completes. Since a merge can fail (if the external \command{hgmerge}
1410 command fails to resolve conflicts in a file), this hook communicates
1411 whether the update or merge completed cleanly.
1413 \begin{itemize}
1414 \item[\texttt{error}] A boolean. Indicates whether the update or
1415 merge completed successfully.
1416 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
1417 working directory was updated to. If the working directory was
1418 merged, it will not have changed this parent.
1419 \item[\texttt{parent2}] A changeset ID. Only set if the working
1420 directory was merged. The ID of the revision that the working
1421 directory was merged with.
1422 \end{itemize}
1424 See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
1426 %%% Local Variables:
1427 %%% mode: latex
1428 %%% TeX-master: "00book"
1429 %%% End: