hgbook
view en/ch09-hook.xml @ 601:c3c5b964901e
Update Google Analytics info
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Fri Mar 27 11:54:22 2009 -0500 (2009-03-27) |
| parents | c838b3975bc6 |
| children | 1c13ed2130a7 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="chap:hook">
4 <?dbhtml filename="handling-repository-events-with-hooks.html"?>
5 <title>Handling repository events with hooks</title>
7 <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
8 automated actions in response to events that occur in a
9 repository. In some cases, you can even control Mercurial's
10 response to those events.</para>
12 <para id="x_1e7">The name Mercurial uses for one of these actions is a
13 <emphasis>hook</emphasis>. Hooks are called
14 <quote>triggers</quote> in some revision control systems, but the
15 two names refer to the same idea.</para>
17 <sect1>
18 <title>An overview of hooks in Mercurial</title>
20 <para id="x_1e8">Here is a brief list of the hooks that Mercurial
21 supports. We will revisit each of these hooks in more detail
22 later, in <xref linkend="sec:hook:ref"/>.</para>
24 <itemizedlist>
25 <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This
26 is run after a group of changesets has been brought into the
27 repository from elsewhere.</para>
28 </listitem>
29 <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is
30 run after a new changeset has been created in the local
31 repository.</para>
32 </listitem>
33 <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is
34 run once for each new changeset that is brought into the
35 repository from elsewhere. Notice the difference from
36 <literal role="hook">changegroup</literal>, which is run
37 once per <emphasis>group</emphasis> of changesets brought
38 in.</para>
39 </listitem>
40 <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is
41 run after a group of changesets has been transmitted from
42 this repository.</para>
43 </listitem>
44 <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>:
45 This is run before starting to bring a group of changesets
46 into the repository.
47 </para>
48 </listitem>
49 <listitem><para id="x_1ee"><literal role="hook">precommit</literal>:
50 Controlling. This is run before starting a commit.
51 </para>
52 </listitem>
53 <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>:
54 Controlling. This is run before starting to transmit a group
55 of changesets from this repository.
56 </para>
57 </listitem>
58 <listitem><para id="x_1f0"><literal role="hook">pretag</literal>:
59 Controlling. This is run before creating a tag.
60 </para>
61 </listitem>
62 <listitem><para id="x_1f1"><literal
63 role="hook">pretxnchangegroup</literal>: Controlling. This
64 is run after a group of changesets has been brought into the
65 local repository from another, but before the transaction
66 completes that will make the changes permanent in the
67 repository.
68 </para>
69 </listitem>
70 <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>:
71 Controlling. This is run after a new changeset has been
72 created in the local repository, but before the transaction
73 completes that will make it permanent.
74 </para>
75 </listitem>
76 <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>:
77 Controlling. This is run before starting an update or merge
78 of the working directory.
79 </para>
80 </listitem>
81 <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run
82 after a tag is created.
83 </para>
84 </listitem>
85 <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is
86 run after an update or merge of the working directory has
87 finished.
88 </para>
89 </listitem></itemizedlist>
90 <para id="x_1f6">Each of the hooks whose description begins with the word
91 <quote>Controlling</quote> has the ability to determine whether
92 an activity can proceed. If the hook succeeds, the activity may
93 proceed; if it fails, the activity is either not permitted or
94 undone, depending on the hook.
95 </para>
97 </sect1>
98 <sect1>
99 <title>Hooks and security</title>
101 <sect2>
102 <title>Hooks are run with your privileges</title>
104 <para id="x_1f7">When you run a Mercurial command in a repository, and the
105 command causes a hook to run, that hook runs on
106 <emphasis>your</emphasis> system, under
107 <emphasis>your</emphasis> user account, with
108 <emphasis>your</emphasis> privilege level. Since hooks are
109 arbitrary pieces of executable code, you should treat them
110 with an appropriate level of suspicion. Do not install a hook
111 unless you are confident that you know who created it and what
112 it does.
113 </para>
115 <para id="x_1f8">In some cases, you may be exposed to hooks that you did
116 not install yourself. If you work with Mercurial on an
117 unfamiliar system, Mercurial will run hooks defined in that
118 system's global <filename role="special">~/.hgrc</filename>
119 file.
120 </para>
122 <para id="x_1f9">If you are working with a repository owned by another
123 user, Mercurial can run hooks defined in that user's
124 repository, but it will still run them as <quote>you</quote>.
125 For example, if you <command role="hg-cmd">hg pull</command>
126 from that repository, and its <filename
127 role="special">.hg/hgrc</filename> defines a local <literal
128 role="hook">outgoing</literal> hook, that hook will run
129 under your user account, even though you don't own that
130 repository.
131 </para>
133 <note>
134 <para id="x_1fa"> This only applies if you are pulling from a repository
135 on a local or network filesystem. If you're pulling over
136 http or ssh, any <literal role="hook">outgoing</literal>
137 hook will run under whatever account is executing the server
138 process, on the server.
139 </para>
140 </note>
142 <para id="x_1fb">XXX To see what hooks are defined in a repository, use the
143 <command role="hg-cmd">hg config hooks</command> command. If
144 you are working in one repository, but talking to another that
145 you do not own (e.g. using <command role="hg-cmd">hg
146 pull</command> or <command role="hg-cmd">hg
147 incoming</command>), remember that it is the other
148 repository's hooks you should be checking, not your own.
149 </para>
151 </sect2>
152 <sect2>
153 <title>Hooks do not propagate</title>
155 <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
156 not propagate when you clone, or pull from, a repository. The
157 reason for this is simple: a hook is a completely arbitrary
158 piece of executable code. It runs under your user identity,
159 with your privilege level, on your machine.
160 </para>
162 <para id="x_1fd">It would be extremely reckless for any distributed
163 revision control system to implement revision-controlled
164 hooks, as this would offer an easily exploitable way to
165 subvert the accounts of users of the revision control system.
166 </para>
168 <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
169 collaborating with other people on a common project, you
170 should not assume that they are using the same Mercurial hooks
171 as you are, or that theirs are correctly configured. You
172 should document the hooks you expect people to use.
173 </para>
175 <para id="x_1ff">In a corporate intranet, this is somewhat easier to
176 control, as you can for example provide a
177 <quote>standard</quote> installation of Mercurial on an NFS
178 filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
179 see. However, this too has its limits; see below.
180 </para>
182 </sect2>
183 <sect2>
184 <title>Hooks can be overridden</title>
186 <para id="x_200">Mercurial allows you to override a hook definition by
187 redefining the hook. You can disable it by setting its value
188 to the empty string, or change its behaviour as you wish.
189 </para>
191 <para id="x_201">If you deploy a system- or site-wide <filename
192 role="special">~/.hgrc</filename> file that defines some
193 hooks, you should thus understand that your users can disable
194 or override those hooks.
195 </para>
197 </sect2>
198 <sect2>
199 <title>Ensuring that critical hooks are run</title>
201 <para id="x_202">Sometimes you may want to enforce a policy that you do not
202 want others to be able to work around. For example, you may
203 have a requirement that every changeset must pass a rigorous
204 set of tests. Defining this requirement via a hook in a
205 site-wide <filename role="special">~/.hgrc</filename> won't
206 work for remote users on laptops, and of course local users
207 can subvert it at will by overriding the hook.
208 </para>
210 <para id="x_203">Instead, you can set up your policies for use of Mercurial
211 so that people are expected to propagate changes through a
212 well-known <quote>canonical</quote> server that you have
213 locked down and configured appropriately.
214 </para>
216 <para id="x_204">One way to do this is via a combination of social
217 engineering and technology. Set up a restricted-access
218 account; users can push changes over the network to
219 repositories managed by this account, but they cannot log into
220 the account and run normal shell commands. In this scenario,
221 a user can commit a changeset that contains any old garbage
222 they want.
223 </para>
225 <para id="x_205">When someone pushes a changeset to the server that
226 everyone pulls from, the server will test the changeset before
227 it accepts it as permanent, and reject it if it fails to pass
228 the test suite. If people only pull changes from this
229 filtering server, it will serve to ensure that all changes
230 that people pull have been automatically vetted.
231 </para>
233 </sect2>
234 </sect1>
235 <sect1>
236 <title>Care with <literal>pretxn</literal> hooks in a
237 shared-access repository</title>
239 <para id="x_206">If you want to use hooks to do some automated work in a
240 repository that a number of people have shared access to, you
241 need to be careful in how you do this.
242 </para>
244 <para id="x_207">Mercurial only locks a repository when it is writing to the
245 repository, and only the parts of Mercurial that write to the
246 repository pay attention to locks. Write locks are necessary to
247 prevent multiple simultaneous writers from scribbling on each
248 other's work, corrupting the repository.
249 </para>
251 <para id="x_208">Because Mercurial is careful with the order in which it
252 reads and writes data, it does not need to acquire a lock when
253 it wants to read data from the repository. The parts of
254 Mercurial that read from the repository never pay attention to
255 locks. This lockless reading scheme greatly increases
256 performance and concurrency.
257 </para>
259 <para id="x_209">With great performance comes a trade-off, though, one which
260 has the potential to cause you trouble unless you're aware of
261 it. To describe this requires a little detail about how
262 Mercurial adds changesets to a repository and reads those
263 changes.
264 </para>
266 <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it
267 writes it straight into the destination file. It writes file
268 data first, then manifest data (which contains pointers to the
269 new file data), then changelog data (which contains pointers to
270 the new manifest data). Before the first write to each file, it
271 stores a record of where the end of the file was in its
272 transaction log. If the transaction must be rolled back,
273 Mercurial simply truncates each file back to the size it was
274 before the transaction began.
275 </para>
277 <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads
278 the changelog first, then everything else. Since a reader will
279 only access parts of the manifest or file metadata that it can
280 see in the changelog, it can never see partially written data.
281 </para>
283 <para id="x_20c">Some controlling hooks (<literal
284 role="hook">pretxncommit</literal> and <literal
285 role="hook">pretxnchangegroup</literal>) run when a
286 transaction is almost complete. All of the metadata has been
287 written, but Mercurial can still roll the transaction back and
288 cause the newly-written data to disappear.
289 </para>
291 <para id="x_20d">If one of these hooks runs for long, it opens a window of
292 time during which a reader can see the metadata for changesets
293 that are not yet permanent, and should not be thought of as
294 <quote>really there</quote>. The longer the hook runs, the
295 longer that window is open.
296 </para>
298 <sect2>
299 <title>The problem illustrated</title>
301 <para id="x_20e">In principle, a good use for the <literal
302 role="hook">pretxnchangegroup</literal> hook would be to
303 automatically build and test incoming changes before they are
304 accepted into a central repository. This could let you
305 guarantee that nobody can push changes to this repository that
306 <quote>break the build</quote>. But if a client can pull
307 changes while they're being tested, the usefulness of the test
308 is zero; an unsuspecting someone can pull untested changes,
309 potentially breaking their build.
310 </para>
312 <para id="x_20f">The safest technological answer to this challenge is to
313 set up such a <quote>gatekeeper</quote> repository as
314 <emphasis>unidirectional</emphasis>. Let it take changes
315 pushed in from the outside, but do not allow anyone to pull
316 changes from it (use the <literal
317 role="hook">preoutgoing</literal> hook to lock it down).
318 Configure a <literal role="hook">changegroup</literal> hook so
319 that if a build or test succeeds, the hook will push the new
320 changes out to another repository that people
321 <emphasis>can</emphasis> pull from.
322 </para>
324 <para id="x_210">In practice, putting a centralised bottleneck like this in
325 place is not often a good idea, and transaction visibility has
326 nothing to do with the problem. As the size of a
327 project&emdash;and the time it takes to build and
328 test&emdash;grows, you rapidly run into a wall with this
329 <quote>try before you buy</quote> approach, where you have
330 more changesets to test than time in which to deal with them.
331 The inevitable result is frustration on the part of all
332 involved.
333 </para>
335 <para id="x_211">An approach that scales better is to get people to build
336 and test before they push, then run automated builds and tests
337 centrally <emphasis>after</emphasis> a push, to be sure all is
338 well. The advantage of this approach is that it does not
339 impose a limit on the rate at which the repository can accept
340 changes.
341 </para>
343 </sect2>
344 </sect1>
345 <sect1 id="sec:hook:simple">
346 <title>A short tutorial on using hooks</title>
348 <para id="x_212">It is easy to write a Mercurial hook. Let's start with a
349 hook that runs when you finish a <command role="hg-cmd">hg
350 commit</command>, and simply prints the hash of the changeset
351 you just created. The hook is called <literal
352 role="hook">commit</literal>.
353 </para>
355 <para id="x_213">All hooks follow the pattern in this example.</para>
357 &interaction.hook.simple.init;
359 <para id="x_214">You add an entry to the <literal
360 role="rc-hooks">hooks</literal> section of your <filename
361 role="special">~/.hgrc</filename>. On the left is the name of
362 the event to trigger on; on the right is the action to take. As
363 you can see, you can run an arbitrary shell command in a hook.
364 Mercurial passes extra information to the hook using environment
365 variables (look for <envar>HG_NODE</envar> in the example).
366 </para>
368 <sect2>
369 <title>Performing multiple actions per event</title>
371 <para id="x_215">Quite often, you will want to define more than one hook
372 for a particular kind of event, as shown below.</para>
374 &interaction.hook.simple.ext;
376 <para id="x_216">Mercurial lets you do this by adding an
377 <emphasis>extension</emphasis> to the end of a hook's name.
378 You extend a hook's name by giving the name of the hook,
379 followed by a full stop (the
380 <quote><literal>.</literal></quote> character), followed by
381 some more text of your choosing. For example, Mercurial will
382 run both <literal>commit.foo</literal> and
383 <literal>commit.bar</literal> when the
384 <literal>commit</literal> event occurs.
385 </para>
387 <para id="x_217">To give a well-defined order of execution when there are
388 multiple hooks defined for an event, Mercurial sorts hooks by
389 extension, and executes the hook commands in this sorted
390 order. In the above example, it will execute
391 <literal>commit.bar</literal> before
392 <literal>commit.foo</literal>, and <literal>commit</literal>
393 before both.
394 </para>
396 <para id="x_218">It is a good idea to use a somewhat descriptive
397 extension when you define a new hook. This will help you to
398 remember what the hook was for. If the hook fails, you'll get
399 an error message that contains the hook name and extension, so
400 using a descriptive extension could give you an immediate hint
401 as to why the hook failed (see <xref
402 linkend="sec:hook:perm"/> for an example).
403 </para>
405 </sect2>
406 <sect2 id="sec:hook:perm">
407 <title>Controlling whether an activity can proceed</title>
409 <para id="x_219">In our earlier examples, we used the <literal
410 role="hook">commit</literal> hook, which is run after a
411 commit has completed. This is one of several Mercurial hooks
412 that run after an activity finishes. Such hooks have no way
413 of influencing the activity itself.
414 </para>
416 <para id="x_21a">Mercurial defines a number of events that occur before an
417 activity starts; or after it starts, but before it finishes.
418 Hooks that trigger on these events have the added ability to
419 choose whether the activity can continue, or will abort.
420 </para>
422 <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs
423 after a commit has all but completed. In other words, the
424 metadata representing the changeset has been written out to
425 disk, but the transaction has not yet been allowed to
426 complete. The <literal role="hook">pretxncommit</literal>
427 hook has the ability to decide whether the transaction can
428 complete, or must be rolled back.
429 </para>
431 <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook
432 exits with a status code of zero, the transaction is allowed
433 to complete; the commit finishes; and the <literal
434 role="hook">commit</literal> hook is run. If the <literal
435 role="hook">pretxncommit</literal> hook exits with a
436 non-zero status code, the transaction is rolled back; the
437 metadata representing the changeset is erased; and the
438 <literal role="hook">commit</literal> hook is not run.
439 </para>
441 &interaction.hook.simple.pretxncommit;
443 <para id="x_21d">The hook in the example above checks that a commit comment
444 contains a bug ID. If it does, the commit can complete. If
445 not, the commit is rolled back.
446 </para>
448 </sect2>
449 </sect1>
450 <sect1>
451 <title>Writing your own hooks</title>
453 <para id="x_21e">When you are writing a hook, you might find it useful to run
454 Mercurial either with the <option
455 role="hg-opt-global">-v</option> option, or the <envar
456 role="rc-item-ui">verbose</envar> config item set to
457 <quote>true</quote>. When you do so, Mercurial will print a
458 message before it calls each hook.
459 </para>
461 <sect2 id="sec:hook:lang">
462 <title>Choosing how your hook should run</title>
464 <para id="x_21f">You can write a hook either as a normal
465 program&emdash;typically a shell script&emdash;or as a Python
466 function that is executed within the Mercurial process.
467 </para>
469 <para id="x_220">Writing a hook as an external program has the advantage
470 that it requires no knowledge of Mercurial's internals. You
471 can call normal Mercurial commands to get any added
472 information you need. The trade-off is that external hooks
473 are slower than in-process hooks.
474 </para>
476 <para id="x_221">An in-process Python hook has complete access to the
477 Mercurial API, and does not <quote>shell out</quote> to
478 another process, so it is inherently faster than an external
479 hook. It is also easier to obtain much of the information
480 that a hook requires by using the Mercurial API than by
481 running Mercurial commands.
482 </para>
484 <para id="x_222">If you are comfortable with Python, or require high
485 performance, writing your hooks in Python may be a good
486 choice. However, when you have a straightforward hook to
487 write and you don't need to care about performance (probably
488 the majority of hooks), a shell script is perfectly fine.
489 </para>
491 </sect2>
492 <sect2 id="sec:hook:param">
493 <title>Hook parameters</title>
495 <para id="x_223">Mercurial calls each hook with a set of well-defined
496 parameters. In Python, a parameter is passed as a keyword
497 argument to your hook function. For an external program, a
498 parameter is passed as an environment variable.
499 </para>
501 <para id="x_224">Whether your hook is written in Python or as a shell
502 script, the hook-specific parameter names and values will be
503 the same. A boolean parameter will be represented as a
504 boolean value in Python, but as the number 1 (for
505 <quote>true</quote>) or 0 (for <quote>false</quote>) as an
506 environment variable for an external hook. If a hook
507 parameter is named <literal>foo</literal>, the keyword
508 argument for a Python hook will also be named
509 <literal>foo</literal>, while the environment variable for an
510 external hook will be named <literal>HG_FOO</literal>.
511 </para>
513 </sect2>
514 <sect2>
515 <title>Hook return values and activity control</title>
517 <para id="x_225">A hook that executes successfully must exit with a status
518 of zero if external, or return boolean <quote>false</quote> if
519 in-process. Failure is indicated with a non-zero exit status
520 from an external hook, or an in-process hook returning boolean
521 <quote>true</quote>. If an in-process hook raises an
522 exception, the hook is considered to have failed.
523 </para>
525 <para id="x_226">For a hook that controls whether an activity can proceed,
526 zero/false means <quote>allow</quote>, while
527 non-zero/true/exception means <quote>deny</quote>.
528 </para>
530 </sect2>
531 <sect2>
532 <title>Writing an external hook</title>
534 <para id="x_227">When you define an external hook in your <filename
535 role="special">~/.hgrc</filename> and the hook is run, its
536 value is passed to your shell, which interprets it. This
537 means that you can use normal shell constructs in the body of
538 the hook.
539 </para>
541 <para id="x_228">An executable hook is always run with its current
542 directory set to a repository's root directory.
543 </para>
545 <para id="x_229">Each hook parameter is passed in as an environment
546 variable; the name is upper-cased, and prefixed with the
547 string <quote><literal>HG_</literal></quote>.
548 </para>
550 <para id="x_22a">With the exception of hook parameters, Mercurial does not
551 set or modify any environment variables when running a hook.
552 This is useful to remember if you are writing a site-wide hook
553 that may be run by a number of different users with differing
554 environment variables set. In multi-user situations, you
555 should not rely on environment variables being set to the
556 values you have in your environment when testing the hook.
557 </para>
559 </sect2>
560 <sect2>
561 <title>Telling Mercurial to use an in-process hook</title>
563 <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax
564 for defining an in-process hook is slightly different than for
565 an executable hook. The value of the hook must start with the
566 text <quote><literal>python:</literal></quote>, and continue
567 with the fully-qualified name of a callable object to use as
568 the hook's value.
569 </para>
571 <para id="x_22c">The module in which a hook lives is automatically imported
572 when a hook is run. So long as you have the module name and
573 <envar>PYTHONPATH</envar> right, it should <quote>just
574 work</quote>.
575 </para>
577 <para id="x_22d">The following <filename role="special">~/.hgrc</filename>
578 example snippet illustrates the syntax and meaning of the
579 notions we just described.
580 </para>
581 <programlisting>[hooks]
582 commit.example = python:mymodule.submodule.myhook</programlisting>
583 <para id="x_22e">When Mercurial runs the <literal>commit.example</literal>
584 hook, it imports <literal>mymodule.submodule</literal>, looks
585 for the callable object named <literal>myhook</literal>, and
586 calls it.
587 </para>
589 </sect2>
590 <sect2>
591 <title>Writing an in-process hook</title>
593 <para id="x_22f">The simplest in-process hook does nothing, but illustrates
594 the basic shape of the hook API:
595 </para>
596 <programlisting>def myhook(ui, repo, **kwargs):
597 pass</programlisting>
598 <para id="x_230">The first argument to a Python hook is always a <literal
599 role="py-mod-mercurial.ui">ui</literal> object. The second
600 is a repository object; at the moment, it is always an
601 instance of <literal
602 role="py-mod-mercurial.localrepo">localrepository</literal>.
603 Following these two arguments are other keyword arguments.
604 Which ones are passed in depends on the hook being called, but
605 a hook can ignore arguments it doesn't care about by dropping
606 them into a keyword argument dict, as with
607 <literal>**kwargs</literal> above.
608 </para>
610 </sect2>
611 </sect1>
612 <sect1>
613 <title>Some hook examples</title>
615 <sect2>
616 <title>Writing meaningful commit messages</title>
618 <para id="x_231">It's hard to imagine a useful commit message being very
619 short. The simple <literal role="hook">pretxncommit</literal>
620 hook of the example below will prevent you from committing a
621 changeset with a message that is less than ten bytes long.
622 </para>
624 &interaction.hook.msglen.go;
626 </sect2>
627 <sect2>
628 <title>Checking for trailing whitespace</title>
630 <para id="x_232">An interesting use of a commit-related hook is to help you
631 to write cleaner code. A simple example of <quote>cleaner
632 code</quote> is the dictum that a change should not add any
633 new lines of text that contain <quote>trailing
634 whitespace</quote>. Trailing whitespace is a series of
635 space and tab characters at the end of a line of text. In
636 most cases, trailing whitespace is unnecessary, invisible
637 noise, but it is occasionally problematic, and people often
638 prefer to get rid of it.
639 </para>
641 <para id="x_233">You can use either the <literal
642 role="hook">precommit</literal> or <literal
643 role="hook">pretxncommit</literal> hook to tell whether you
644 have a trailing whitespace problem. If you use the <literal
645 role="hook">precommit</literal> hook, the hook will not know
646 which files you are committing, so it will have to check every
647 modified file in the repository for trailing white space. If
648 you want to commit a change to just the file
649 <filename>foo</filename>, but the file
650 <filename>bar</filename> contains trailing whitespace, doing a
651 check in the <literal role="hook">precommit</literal> hook
652 will prevent you from committing <filename>foo</filename> due
653 to the problem with <filename>bar</filename>. This doesn't
654 seem right.
655 </para>
657 <para id="x_234">Should you choose the <literal
658 role="hook">pretxncommit</literal> hook, the check won't
659 occur until just before the transaction for the commit
660 completes. This will allow you to check for problems only the
661 exact files that are being committed. However, if you entered
662 the commit message interactively and the hook fails, the
663 transaction will roll back; you'll have to re-enter the commit
664 message after you fix the trailing whitespace and run <command
665 role="hg-cmd">hg commit</command> again.
666 </para>
668 &interaction.hook.ws.simple;
670 <para id="x_235">In this example, we introduce a simple <literal
671 role="hook">pretxncommit</literal> hook that checks for
672 trailing whitespace. This hook is short, but not very
673 helpful. It exits with an error status if a change adds a
674 line with trailing whitespace to any file, but does not print
675 any information that might help us to identify the offending
676 file or line. It also has the nice property of not paying
677 attention to unmodified lines; only lines that introduce new
678 trailing whitespace cause problems.
679 </para>
681 <para id="x_236">The above version is much more complex, but also more
682 useful. It parses a unified diff to see if any lines add
683 trailing whitespace, and prints the name of the file and the
684 line number of each such occurrence. Even better, if the
685 change adds trailing whitespace, this hook saves the commit
686 comment and prints the name of the save file before exiting
687 and telling Mercurial to roll the transaction back, so you can
688 use the <option role="hg-opt-commit">-l filename</option>
689 option to <command role="hg-cmd">hg commit</command> to reuse
690 the saved commit message once you've corrected the problem.
691 </para>
693 &interaction.hook.ws.better;
695 <para id="x_237">As a final aside, note in the example above the use of
696 <command>perl</command>'s in-place editing feature to get rid
697 of trailing whitespace from a file. This is concise and
698 useful enough that I will reproduce it here.
699 </para>
700 <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting>
702 </sect2>
703 </sect1>
704 <sect1>
705 <title>Bundled hooks</title>
707 <para id="x_238">Mercurial ships with several bundled hooks. You can find
708 them in the <filename class="directory">hgext</filename>
709 directory of a Mercurial source tree. If you are using a
710 Mercurial binary package, the hooks will be located in the
711 <filename class="directory">hgext</filename> directory of
712 wherever your package installer put Mercurial.
713 </para>
715 <sect2>
716 <title><literal role="hg-ext">acl</literal>&emdash;access
717 control for parts of a repository</title>
719 <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets
720 you control which remote users are allowed to push changesets
721 to a networked server. You can protect any portion of a
722 repository (including the entire repo), so that a specific
723 remote user can push changes that do not affect the protected
724 portion.
725 </para>
727 <para id="x_23a">This extension implements access control based on the
728 identity of the user performing a push,
729 <emphasis>not</emphasis> on who committed the changesets
730 they're pushing. It makes sense to use this hook only if you
731 have a locked-down server environment that authenticates
732 remote users, and you want to be sure that only specific users
733 are allowed to push changes to that server.
734 </para>
736 <sect3>
737 <title>Configuring the <literal role="hook">acl</literal>
738 hook</title>
740 <para id="x_23b">In order to manage incoming changesets, the <literal
741 role="hg-ext">acl</literal> hook must be used as a
742 <literal role="hook">pretxnchangegroup</literal> hook. This
743 lets it see which files are modified by each incoming
744 changeset, and roll back a group of changesets if they
745 modify <quote>forbidden</quote> files. Example:
746 </para>
747 <programlisting>[hooks]
748 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
750 <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is
751 configured using three sections.
752 </para>
754 <para id="x_23d">The <literal role="rc-acl">acl</literal> section has
755 only one entry, <envar role="rc-item-acl">sources</envar>,
756 which lists the sources of incoming changesets that the hook
757 should pay attention to. You don't normally need to
758 configure this section.
759 </para>
760 <itemizedlist>
761 <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
762 Control incoming changesets that are arriving from a
763 remote repository over http or ssh. This is the default
764 value of <envar role="rc-item-acl">sources</envar>, and
765 usually the only setting you'll need for this
766 configuration item.
767 </para>
768 </listitem>
769 <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
770 Control incoming changesets that are arriving via a pull
771 from a local repository.
772 </para>
773 </listitem>
774 <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
775 Control incoming changesets that are arriving via a push
776 from a local repository.
777 </para>
778 </listitem>
779 <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
780 Control incoming changesets that are arriving from
781 another repository via a bundle.
782 </para>
783 </listitem></itemizedlist>
785 <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal>
786 section controls the users that are allowed to add
787 changesets to the repository. If this section is not
788 present, all users that are not explicitly denied are
789 allowed. If this section is present, all users that are not
790 explicitly allowed are denied (so an empty section means
791 that all users are denied).
792 </para>
794 <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal>
795 section determines which users are denied from adding
796 changesets to the repository. If this section is not
797 present or is empty, no users are denied.
798 </para>
800 <para id="x_244">The syntaxes for the <literal
801 role="rc-acl.allow">acl.allow</literal> and <literal
802 role="rc-acl.deny">acl.deny</literal> sections are
803 identical. On the left of each entry is a glob pattern that
804 matches files or directories, relative to the root of the
805 repository; on the right, a user name.
806 </para>
808 <para id="x_245">In the following example, the user
809 <literal>docwriter</literal> can only push changes to the
810 <filename class="directory">docs</filename> subtree of the
811 repository, while <literal>intern</literal> can push changes
812 to any file or directory except <filename
813 class="directory">source/sensitive</filename>.
814 </para>
815 <programlisting>[acl.allow]
816 docs/** = docwriter
817 [acl.deny]
818 source/sensitive/** = intern</programlisting>
820 </sect3>
821 <sect3>
822 <title>Testing and troubleshooting</title>
824 <para id="x_246">If you want to test the <literal
825 role="hg-ext">acl</literal> hook, run it with Mercurial's
826 debugging output enabled. Since you'll probably be running
827 it on a server where it's not convenient (or sometimes
828 possible) to pass in the <option
829 role="hg-opt-global">--debug</option> option, don't forget
830 that you can enable debugging output in your <filename
831 role="special">~/.hgrc</filename>:
832 </para>
833 <programlisting>[ui]
834 debug = true</programlisting>
835 <para id="x_247">With this enabled, the <literal
836 role="hg-ext">acl</literal> hook will print enough
837 information to let you figure out why it is allowing or
838 forbidding pushes from specific users.
839 </para>
841 </sect3>
842 </sect2>
843 <sect2>
844 <title><literal
845 role="hg-ext">bugzilla</literal>&emdash;integration with
846 Bugzilla</title>
848 <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension
849 adds a comment to a Bugzilla bug whenever it finds a reference
850 to that bug ID in a commit comment. You can install this hook
851 on a shared server, so that any time a remote user pushes
852 changes to this server, the hook gets run.
853 </para>
855 <para id="x_249">It adds a comment to the bug that looks like this (you can
856 configure the contents of the comment&emdash;see below):
857 </para>
858 <programlisting>Changeset aad8b264143a, made by Joe User
859 <joe.user@domain.com> in the frobnitz repository, refers
860 to this bug. For complete details, see
861 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
862 Changeset description: Fix bug 10483 by guarding against some
863 NULL pointers</programlisting>
864 <para id="x_24a">The value of this hook is that it automates the process of
865 updating a bug any time a changeset refers to it. If you
866 configure the hook properly, it makes it easy for people to
867 browse straight from a Bugzilla bug to a changeset that refers
868 to that bug.
869 </para>
871 <para id="x_24b">You can use the code in this hook as a starting point for
872 some more exotic Bugzilla integration recipes. Here are a few
873 possibilities:
874 </para>
875 <itemizedlist>
876 <listitem><para id="x_24c">Require that every changeset pushed to the
877 server have a valid bug ID in its commit comment. In this
878 case, you'd want to configure the hook as a <literal
879 role="hook">pretxncommit</literal> hook. This would
880 allow the hook to reject changes that didn't contain bug
881 IDs.
882 </para>
883 </listitem>
884 <listitem><para id="x_24d">Allow incoming changesets to automatically
885 modify the <emphasis>state</emphasis> of a bug, as well as
886 simply adding a comment. For example, the hook could
887 recognise the string <quote>fixed bug 31337</quote> as
888 indicating that it should update the state of bug 31337 to
889 <quote>requires testing</quote>.
890 </para>
891 </listitem></itemizedlist>
893 <sect3 id="sec:hook:bugzilla:config">
894 <title>Configuring the <literal role="hook">bugzilla</literal>
895 hook</title>
897 <para id="x_24e">You should configure this hook in your server's
898 <filename role="special">~/.hgrc</filename> as an <literal
899 role="hook">incoming</literal> hook, for example as
900 follows:
901 </para>
902 <programlisting>[hooks]
903 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
905 <para id="x_24f">Because of the specialised nature of this hook, and
906 because Bugzilla was not written with this kind of
907 integration in mind, configuring this hook is a somewhat
908 involved process.
909 </para>
911 <para id="x_250">Before you begin, you must install the MySQL bindings
912 for Python on the host(s) where you'll be running the hook.
913 If this is not available as a binary package for your
914 system, you can download it from
915 <citation>web:mysql-python</citation>.
916 </para>
918 <para id="x_251">Configuration information for this hook lives in the
919 <literal role="rc-bugzilla">bugzilla</literal> section of
920 your <filename role="special">~/.hgrc</filename>.
921 </para>
922 <itemizedlist>
923 <listitem><para id="x_252"><envar
924 role="rc-item-bugzilla">version</envar>: The version
925 of Bugzilla installed on the server. The database
926 schema that Bugzilla uses changes occasionally, so this
927 hook has to know exactly which schema to use. At the
928 moment, the only version supported is
929 <literal>2.16</literal>.
930 </para>
931 </listitem>
932 <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
933 The hostname of the MySQL server that stores your
934 Bugzilla data. The database must be configured to allow
935 connections from whatever host you are running the
936 <literal role="hook">bugzilla</literal> hook on.
937 </para>
938 </listitem>
939 <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
940 The username with which to connect to the MySQL server.
941 The database must be configured to allow this user to
942 connect from whatever host you are running the <literal
943 role="hook">bugzilla</literal> hook on. This user
944 must be able to access and modify Bugzilla tables. The
945 default value of this item is <literal>bugs</literal>,
946 which is the standard name of the Bugzilla user in a
947 MySQL database.
948 </para>
949 </listitem>
950 <listitem><para id="x_255"><envar
951 role="rc-item-bugzilla">password</envar>: The MySQL
952 password for the user you configured above. This is
953 stored as plain text, so you should make sure that
954 unauthorised users cannot read the <filename
955 role="special">~/.hgrc</filename> file where you
956 store this information.
957 </para>
958 </listitem>
959 <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
960 The name of the Bugzilla database on the MySQL server.
961 The default value of this item is
962 <literal>bugs</literal>, which is the standard name of
963 the MySQL database where Bugzilla stores its data.
964 </para>
965 </listitem>
966 <listitem><para id="x_257"><envar
967 role="rc-item-bugzilla">notify</envar>: If you want
968 Bugzilla to send out a notification email to subscribers
969 after this hook has added a comment to a bug, you will
970 need this hook to run a command whenever it updates the
971 database. The command to run depends on where you have
972 installed Bugzilla, but it will typically look something
973 like this, if you have Bugzilla installed in <filename
974 class="directory">/var/www/html/bugzilla</filename>:
975 </para>
976 <programlisting>cd /var/www/html/bugzilla &&
977 ./processmail %s nobody@nowhere.com</programlisting>
978 </listitem>
979 <listitem><para id="x_258"> The Bugzilla
980 <literal>processmail</literal> program expects to be
981 given a bug ID (the hook replaces
982 <quote><literal>%s</literal></quote> with the bug ID)
983 and an email address. It also expects to be able to
984 write to some files in the directory that it runs in.
985 If Bugzilla and this hook are not installed on the same
986 machine, you will need to find a way to run
987 <literal>processmail</literal> on the server where
988 Bugzilla is installed.
989 </para>
990 </listitem></itemizedlist>
992 </sect3>
993 <sect3>
994 <title>Mapping committer names to Bugzilla user names</title>
996 <para id="x_259">By default, the <literal
997 role="hg-ext">bugzilla</literal> hook tries to use the
998 email address of a changeset's committer as the Bugzilla
999 user name with which to update a bug. If this does not suit
1000 your needs, you can map committer email addresses to
1001 Bugzilla user names using a <literal
1002 role="rc-usermap">usermap</literal> section.
1003 </para>
1005 <para id="x_25a">Each item in the <literal
1006 role="rc-usermap">usermap</literal> section contains an
1007 email address on the left, and a Bugzilla user name on the
1008 right.
1009 </para>
1010 <programlisting>[usermap]
1011 jane.user@example.com = jane</programlisting>
1012 <para id="x_25b">You can either keep the <literal
1013 role="rc-usermap">usermap</literal> data in a normal
1014 <filename role="special">~/.hgrc</filename>, or tell the
1015 <literal role="hg-ext">bugzilla</literal> hook to read the
1016 information from an external <filename>usermap</filename>
1017 file. In the latter case, you can store
1018 <filename>usermap</filename> data by itself in (for example)
1019 a user-modifiable repository. This makes it possible to let
1020 your users maintain their own <envar
1021 role="rc-item-bugzilla">usermap</envar> entries. The main
1022 <filename role="special">~/.hgrc</filename> file might look
1023 like this:
1024 </para>
1025 <programlisting># regular hgrc file refers to external usermap file
1026 [bugzilla]
1027 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
1028 <para id="x_25c">While the <filename>usermap</filename> file that it
1029 refers to might look like this:
1030 </para>
1031 <programlisting># bugzilla-usermap.conf - inside a hg repository
1032 [usermap] stephanie@example.com = steph</programlisting>
1034 </sect3>
1035 <sect3>
1036 <title>Configuring the text that gets added to a bug</title>
1038 <para id="x_25d">You can configure the text that this hook adds as a
1039 comment; you specify it in the form of a Mercurial template.
1040 Several <filename role="special">~/.hgrc</filename> entries
1041 (still in the <literal role="rc-bugzilla">bugzilla</literal>
1042 section) control this behaviour.
1043 </para>
1044 <itemizedlist>
1045 <listitem><para id="x_25e"><literal>strip</literal>: The number of
1046 leading path elements to strip from a repository's path
1047 name to construct a partial path for a URL. For example,
1048 if the repositories on your server live under <filename
1049 class="directory">/home/hg/repos</filename>, and you
1050 have a repository whose path is <filename
1051 class="directory">/home/hg/repos/app/tests</filename>,
1052 then setting <literal>strip</literal> to
1053 <literal>4</literal> will give a partial path of
1054 <filename class="directory">app/tests</filename>. The
1055 hook will make this partial path available when
1056 expanding a template, as <literal>webroot</literal>.
1057 </para>
1058 </listitem>
1059 <listitem><para id="x_25f"><literal>template</literal>: The text of the
1060 template to use. In addition to the usual
1061 changeset-related variables, this template can use
1062 <literal>hgweb</literal> (the value of the
1063 <literal>hgweb</literal> configuration item above) and
1064 <literal>webroot</literal> (the path constructed using
1065 <literal>strip</literal> above).
1066 </para>
1067 </listitem></itemizedlist>
1069 <para id="x_260">In addition, you can add a <envar
1070 role="rc-item-web">baseurl</envar> item to the <literal
1071 role="rc-web">web</literal> section of your <filename
1072 role="special">~/.hgrc</filename>. The <literal
1073 role="hg-ext">bugzilla</literal> hook will make this
1074 available when expanding a template, as the base string to
1075 use when constructing a URL that will let users browse from
1076 a Bugzilla comment to view a changeset. Example:
1077 </para>
1078 <programlisting>[web]
1079 baseurl = http://hg.domain.com/</programlisting>
1081 <para id="x_261">Here is an example set of <literal
1082 role="hg-ext">bugzilla</literal> hook config information.
1083 </para>
1085 &ch10-bugzilla-config.lst;
1087 </sect3>
1088 <sect3>
1089 <title>Testing and troubleshooting</title>
1091 <para id="x_262">The most common problems with configuring the <literal
1092 role="hg-ext">bugzilla</literal> hook relate to running
1093 Bugzilla's <filename>processmail</filename> script and
1094 mapping committer names to user names.
1095 </para>
1097 <para id="x_263">Recall from <xref
1098 linkend="sec:hook:bugzilla:config"/> above that the user
1099 that runs the Mercurial process on the server is also the
1100 one that will run the <filename>processmail</filename>
1101 script. The <filename>processmail</filename> script
1102 sometimes causes Bugzilla to write to files in its
1103 configuration directory, and Bugzilla's configuration files
1104 are usually owned by the user that your web server runs
1105 under.
1106 </para>
1108 <para id="x_264">You can cause <filename>processmail</filename> to be run
1109 with the suitable user's identity using the
1110 <command>sudo</command> command. Here is an example entry
1111 for a <filename>sudoers</filename> file.
1112 </para>
1113 <programlisting>hg_user = (httpd_user)
1114 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
1115 <para id="x_265">This allows the <literal>hg_user</literal> user to run a
1116 <filename>processmail-wrapper</filename> program under the
1117 identity of <literal>httpd_user</literal>.
1118 </para>
1120 <para id="x_266">This indirection through a wrapper script is necessary,
1121 because <filename>processmail</filename> expects to be run
1122 with its current directory set to wherever you installed
1123 Bugzilla; you can't specify that kind of constraint in a
1124 <filename>sudoers</filename> file. The contents of the
1125 wrapper script are simple:
1126 </para>
1127 <programlisting>#!/bin/sh
1128 cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting>
1129 <para id="x_267">It doesn't seem to matter what email address you pass to
1130 <filename>processmail</filename>.
1131 </para>
1133 <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is
1134 not set up correctly, users will see an error message from
1135 the <literal role="hg-ext">bugzilla</literal> hook when they
1136 push changes to the server. The error message will look
1137 like this:
1138 </para>
1139 <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
1140 <para id="x_269">What this means is that the committer's address,
1141 <literal>john.q.public@example.com</literal>, is not a valid
1142 Bugzilla user name, nor does it have an entry in your
1143 <literal role="rc-usermap">usermap</literal> that maps it to
1144 a valid Bugzilla user name.
1145 </para>
1147 </sect3>
1148 </sect2>
1149 <sect2>
1150 <title><literal role="hg-ext">notify</literal>&emdash;send email
1151 notifications</title>
1153 <para id="x_26a">Although Mercurial's built-in web server provides RSS
1154 feeds of changes in every repository, many people prefer to
1155 receive change notifications via email. The <literal
1156 role="hg-ext">notify</literal> hook lets you send out
1157 notifications to a set of email addresses whenever changesets
1158 arrive that those subscribers are interested in.
1159 </para>
1161 <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal>
1162 hook, the <literal role="hg-ext">notify</literal> hook is
1163 template-driven, so you can customise the contents of the
1164 notification messages that it sends.
1165 </para>
1167 <para id="x_26c">By default, the <literal role="hg-ext">notify</literal>
1168 hook includes a diff of every changeset that it sends out; you
1169 can limit the size of the diff, or turn this feature off
1170 entirely. It is useful for letting subscribers review changes
1171 immediately, rather than clicking to follow a URL.
1172 </para>
1174 <sect3>
1175 <title>Configuring the <literal role="hg-ext">notify</literal>
1176 hook</title>
1178 <para id="x_26d">You can set up the <literal
1179 role="hg-ext">notify</literal> hook to send one email
1180 message per incoming changeset, or one per incoming group of
1181 changesets (all those that arrived in a single pull or
1182 push).
1183 </para>
1184 <programlisting>[hooks]
1185 # send one email per group of changes
1186 changegroup.notify = python:hgext.notify.hook
1187 # send one email per change
1188 incoming.notify = python:hgext.notify.hook</programlisting>
1190 <para id="x_26e">Configuration information for this hook lives in the
1191 <literal role="rc-notify">notify</literal> section of a
1192 <filename role="special">~/.hgrc</filename> file.
1193 </para>
1194 <itemizedlist>
1195 <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
1196 By default, this hook does not send out email at all;
1197 instead, it prints the message that it
1198 <emphasis>would</emphasis> send. Set this item to
1199 <literal>false</literal> to allow email to be sent. The
1200 reason that sending of email is turned off by default is
1201 that it takes several tries to configure this extension
1202 exactly as you would like, and it would be bad form to
1203 spam subscribers with a number of <quote>broken</quote>
1204 notifications while you debug your configuration.
1205 </para>
1206 </listitem>
1207 <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
1208 The path to a configuration file that contains
1209 subscription information. This is kept separate from
1210 the main <filename role="special">~/.hgrc</filename> so
1211 that you can maintain it in a repository of its own.
1212 People can then clone that repository, update their
1213 subscriptions, and push the changes back to your server.
1214 </para>
1215 </listitem>
1216 <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
1217 The number of leading path separator characters to strip
1218 from a repository's path, when deciding whether a
1219 repository has subscribers. For example, if the
1220 repositories on your server live in <filename
1221 class="directory">/home/hg/repos</filename>, and
1222 <literal role="hg-ext">notify</literal> is considering a
1223 repository named <filename
1224 class="directory">/home/hg/repos/shared/test</filename>,
1225 setting <envar role="rc-item-notify">strip</envar> to
1226 <literal>4</literal> will cause <literal
1227 role="hg-ext">notify</literal> to trim the path it
1228 considers down to <filename
1229 class="directory">shared/test</filename>, and it will
1230 match subscribers against that.
1231 </para>
1232 </listitem>
1233 <listitem><para id="x_272"><envar
1234 role="rc-item-notify">template</envar>: The template
1235 text to use when sending messages. This specifies both
1236 the contents of the message header and its body.
1237 </para>
1238 </listitem>
1239 <listitem><para id="x_273"><envar
1240 role="rc-item-notify">maxdiff</envar>: The maximum
1241 number of lines of diff data to append to the end of a
1242 message. If a diff is longer than this, it is
1243 truncated. By default, this is set to 300. Set this to
1244 <literal>0</literal> to omit diffs from notification
1245 emails.
1246 </para>
1247 </listitem>
1248 <listitem><para id="x_274"><envar
1249 role="rc-item-notify">sources</envar>: A list of
1250 sources of changesets to consider. This lets you limit
1251 <literal role="hg-ext">notify</literal> to only sending
1252 out email about changes that remote users pushed into
1253 this repository via a server, for example. See
1254 <xref linkend="sec:hook:sources"/> for the sources you
1255 can specify here.
1256 </para>
1257 </listitem></itemizedlist>
1259 <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
1260 item in the <literal role="rc-web">web</literal> section,
1261 you can use it in a template; it will be available as
1262 <literal>webroot</literal>.
1263 </para>
1265 <para id="x_276">Here is an example set of <literal
1266 role="hg-ext">notify</literal> configuration information.
1267 </para>
1269 &ch10-notify-config.lst;
1271 <para id="x_277">This will produce a message that looks like the
1272 following:
1273 </para>
1275 &ch10-notify-config-mail.lst;
1277 </sect3>
1278 <sect3>
1279 <title>Testing and troubleshooting</title>
1281 <para id="x_278">Do not forget that by default, the <literal
1282 role="hg-ext">notify</literal> extension <emphasis>will not
1283 send any mail</emphasis> until you explicitly configure it to do so,
1284 by setting <envar role="rc-item-notify">test</envar> to
1285 <literal>false</literal>. Until you do that, it simply
1286 prints the message it <emphasis>would</emphasis> send.
1287 </para>
1289 </sect3>
1290 </sect2>
1291 </sect1>
1292 <sect1 id="sec:hook:ref">
1293 <title>Information for writers of hooks</title>
1295 <sect2>
1296 <title>In-process hook execution</title>
1298 <para id="x_279">An in-process hook is called with arguments of the
1299 following form:
1300 </para>
1301 <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
1302 <para id="x_27a">The <literal>ui</literal> parameter is a <literal
1303 role="py-mod-mercurial.ui">ui</literal> object. The
1304 <literal>repo</literal> parameter is a <literal
1305 role="py-mod-mercurial.localrepo">localrepository</literal>
1306 object. The names and values of the
1307 <literal>**kwargs</literal> parameters depend on the hook
1308 being invoked, with the following common features:
1309 </para>
1310 <itemizedlist>
1311 <listitem><para id="x_27b">If a parameter is named
1312 <literal>node</literal> or <literal>parentN</literal>, it
1313 will contain a hexadecimal changeset ID. The empty string
1314 is used to represent <quote>null changeset ID</quote>
1315 instead of a string of zeroes.
1316 </para>
1317 </listitem>
1318 <listitem><para id="x_27c">If a parameter is named
1319 <literal>url</literal>, it will contain the URL of a
1320 remote repository, if that can be determined.
1321 </para>
1322 </listitem>
1323 <listitem><para id="x_27d">Boolean-valued parameters are represented as
1324 Python <literal>bool</literal> objects.
1325 </para>
1326 </listitem></itemizedlist>
1328 <para id="x_27e">An in-process hook is called without a change to the
1329 process's working directory (unlike external hooks, which are
1330 run in the root of the repository). It must not change the
1331 process's working directory, or it will cause any calls it
1332 makes into the Mercurial API to fail.
1333 </para>
1335 <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
1336 is considered to have succeeded. If it returns a boolean
1337 <quote>true</quote> value or raises an exception, it is
1338 considered to have failed. A useful way to think of the
1339 calling convention is <quote>tell me if you fail</quote>.
1340 </para>
1342 <para id="x_280">Note that changeset IDs are passed into Python hooks as
1343 hexadecimal strings, not the binary hashes that Mercurial's
1344 APIs normally use. To convert a hash from hex to binary, use
1345 the <literal>bin</literal> function.
1346 </para>
1348 </sect2>
1349 <sect2>
1350 <title>External hook execution</title>
1352 <para id="x_281">An external hook is passed to the shell of the user
1353 running Mercurial. Features of that shell, such as variable
1354 substitution and command redirection, are available. The hook
1355 is run in the root directory of the repository (unlike
1356 in-process hooks, which are run in the same directory that
1357 Mercurial was run in).
1358 </para>
1360 <para id="x_282">Hook parameters are passed to the hook as environment
1361 variables. Each environment variable's name is converted in
1362 upper case and prefixed with the string
1363 <quote><literal>HG_</literal></quote>. For example, if the
1364 name of a parameter is <quote><literal>node</literal></quote>,
1365 the name of the environment variable representing that
1366 parameter will be <quote><literal>HG_NODE</literal></quote>.
1367 </para>
1369 <para id="x_283">A boolean parameter is represented as the string
1370 <quote><literal>1</literal></quote> for <quote>true</quote>,
1371 <quote><literal>0</literal></quote> for <quote>false</quote>.
1372 If an environment variable is named <envar>HG_NODE</envar>,
1373 <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
1374 contains a changeset ID represented as a hexadecimal string.
1375 The empty string is used to represent <quote>null changeset
1376 ID</quote> instead of a string of zeroes. If an environment
1377 variable is named <envar>HG_URL</envar>, it will contain the
1378 URL of a remote repository, if that can be determined.
1379 </para>
1381 <para id="x_284">If a hook exits with a status of zero, it is considered to
1382 have succeeded. If it exits with a non-zero status, it is
1383 considered to have failed.
1384 </para>
1386 </sect2>
1387 <sect2>
1388 <title>Finding out where changesets come from</title>
1390 <para id="x_285">A hook that involves the transfer of changesets between a
1391 local repository and another may be able to find out
1392 information about the <quote>far side</quote>. Mercurial
1393 knows <emphasis>how</emphasis> changes are being transferred,
1394 and in many cases <emphasis>where</emphasis> they are being
1395 transferred to or from.
1396 </para>
1398 <sect3 id="sec:hook:sources">
1399 <title>Sources of changesets</title>
1401 <para id="x_286">Mercurial will tell a hook what means are, or were, used
1402 to transfer changesets between repositories. This is
1403 provided by Mercurial in a Python parameter named
1404 <literal>source</literal>, or an environment variable named
1405 <envar>HG_SOURCE</envar>.
1406 </para>
1408 <itemizedlist>
1409 <listitem><para id="x_287"><literal>serve</literal>: Changesets are
1410 transferred to or from a remote repository over http or
1411 ssh.
1412 </para>
1413 </listitem>
1414 <listitem><para id="x_288"><literal>pull</literal>: Changesets are
1415 being transferred via a pull from one repository into
1416 another.
1417 </para>
1418 </listitem>
1419 <listitem><para id="x_289"><literal>push</literal>: Changesets are
1420 being transferred via a push from one repository into
1421 another.
1422 </para>
1423 </listitem>
1424 <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are
1425 being transferred to or from a bundle.
1426 </para>
1427 </listitem></itemizedlist>
1429 </sect3>
1430 <sect3 id="sec:hook:url">
1431 <title>Where changes are going&emdash;remote repository
1432 URLs</title>
1434 <para id="x_28b">When possible, Mercurial will tell a hook the location
1435 of the <quote>far side</quote> of an activity that transfers
1436 changeset data between repositories. This is provided by
1437 Mercurial in a Python parameter named
1438 <literal>url</literal>, or an environment variable named
1439 <envar>HG_URL</envar>.
1440 </para>
1442 <para id="x_28c">This information is not always known. If a hook is
1443 invoked in a repository that is being served via http or
1444 ssh, Mercurial cannot tell where the remote repository is,
1445 but it may know where the client is connecting from. In
1446 such cases, the URL will take one of the following forms:
1447 </para>
1448 <itemizedlist>
1449 <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote
1450 ssh client, at the IP address
1451 <literal>1.2.3.4</literal>.
1452 </para>
1453 </listitem>
1454 <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote
1455 http client, at the IP address
1456 <literal>1.2.3.4</literal>. If the client is using SSL,
1457 this will be of the form
1458 <literal>remote:https:1.2.3.4</literal>.
1459 </para>
1460 </listitem>
1461 <listitem><para id="x_28f">Empty&emdash;no information could be
1462 discovered about the remote client.
1463 </para>
1464 </listitem></itemizedlist>
1466 </sect3>
1467 </sect2>
1468 </sect1>
1469 <sect1>
1470 <title>Hook reference</title>
1472 <sect2 id="sec:hook:changegroup">
1473 <title><literal role="hook">changegroup</literal>&emdash;after
1474 remote changesets added</title>
1476 <para id="x_290">This hook is run after a group of pre-existing changesets
1477 has been added to the repository, for example via a <command
1478 role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
1479 unbundle</command>. This hook is run once per operation
1480 that added one or more changesets. This is in contrast to the
1481 <literal role="hook">incoming</literal> hook, which is run
1482 once per changeset, regardless of whether the changesets
1483 arrive in a group.
1484 </para>
1486 <para id="x_291">Some possible uses for this hook include kicking off an
1487 automated build or test of the added changesets, updating a
1488 bug database, or notifying subscribers that a repository
1489 contains new changes.
1490 </para>
1492 <para id="x_292">Parameters to this hook:
1493 </para>
1494 <itemizedlist>
1495 <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The
1496 changeset ID of the first changeset in the group that was
1497 added. All changesets between this and
1498 <literal role="tag">tip</literal>, inclusive, were added by a single
1499 <command role="hg-cmd">hg pull</command>, <command
1500 role="hg-cmd">hg push</command> or <command
1501 role="hg-cmd">hg unbundle</command>.
1502 </para>
1503 </listitem>
1504 <listitem><para id="x_294"><literal>source</literal>: A
1505 string. The source of these changes. See <xref
1506 linkend="sec:hook:sources"/> for details.
1507 </para>
1508 </listitem>
1509 <listitem><para id="x_295"><literal>url</literal>: A URL. The
1510 location of the remote repository, if known. See <xref
1511 linkend="sec:hook:url"/> for more information.
1512 </para>
1513 </listitem></itemizedlist>
1515 <para id="x_296">See also: <literal
1516 role="hook">incoming</literal> (<xref
1517 linkend="sec:hook:incoming"/>), <literal
1518 role="hook">prechangegroup</literal> (<xref
1519 linkend="sec:hook:prechangegroup"/>), <literal
1520 role="hook">pretxnchangegroup</literal> (<xref
1521 linkend="sec:hook:pretxnchangegroup"/>)
1522 </para>
1524 </sect2>
1525 <sect2 id="sec:hook:commit">
1526 <title><literal role="hook">commit</literal>&emdash;after a new
1527 changeset is created</title>
1529 <para id="x_297">This hook is run after a new changeset has been created.
1530 </para>
1532 <para id="x_298">Parameters to this hook:
1533 </para>
1534 <itemizedlist>
1535 <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The
1536 changeset ID of the newly committed changeset.
1537 </para>
1538 </listitem>
1539 <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID.
1540 The changeset ID of the first parent of the newly
1541 committed changeset.
1542 </para>
1543 </listitem>
1544 <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID.
1545 The changeset ID of the second parent of the newly
1546 committed changeset.
1547 </para>
1548 </listitem></itemizedlist>
1550 <para id="x_29c">See also: <literal
1551 role="hook">precommit</literal> (<xref
1552 linkend="sec:hook:precommit"/>), <literal
1553 role="hook">pretxncommit</literal> (<xref
1554 linkend="sec:hook:pretxncommit"/>)
1555 </para>
1557 </sect2>
1558 <sect2 id="sec:hook:incoming">
1559 <title><literal role="hook">incoming</literal>&emdash;after one
1560 remote changeset is added</title>
1562 <para id="x_29d">This hook is run after a pre-existing changeset has been
1563 added to the repository, for example via a <command
1564 role="hg-cmd">hg push</command>. If a group of changesets
1565 was added in a single operation, this hook is called once for
1566 each added changeset.
1567 </para>
1569 <para id="x_29e">You can use this hook for the same purposes as
1570 the <literal role="hook">changegroup</literal> hook (<xref
1571 linkend="sec:hook:changegroup"/>); it's simply more
1572 convenient sometimes to run a hook once per group of
1573 changesets, while other times it's handier once per changeset.
1574 </para>
1576 <para id="x_29f">Parameters to this hook:
1577 </para>
1578 <itemizedlist>
1579 <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The
1580 ID of the newly added changeset.
1581 </para>
1582 </listitem>
1583 <listitem><para id="x_2a1"><literal>source</literal>: A
1584 string. The source of these changes. See <xref
1585 linkend="sec:hook:sources"/> for details.
1586 </para>
1587 </listitem>
1588 <listitem><para id="x_2a2"><literal>url</literal>: A URL. The
1589 location of the remote repository, if known. See <xref
1590 linkend="sec:hook:url"/> for more information.
1591 </para>
1592 </listitem></itemizedlist>
1594 <para id="x_2a3">See also: <literal
1595 role="hook">changegroup</literal> (<xref
1596 linkend="sec:hook:changegroup"/>) <literal
1597 role="hook">prechangegroup</literal> (<xref
1598 linkend="sec:hook:prechangegroup"/>), <literal
1599 role="hook">pretxnchangegroup</literal> (<xref
1600 linkend="sec:hook:pretxnchangegroup"/>)
1601 </para>
1603 </sect2>
1604 <sect2 id="sec:hook:outgoing">
1605 <title><literal role="hook">outgoing</literal>&emdash;after
1606 changesets are propagated</title>
1608 <para id="x_2a4">This hook is run after a group of changesets has been
1609 propagated out of this repository, for example by a <command
1610 role="hg-cmd">hg push</command> or <command role="hg-cmd">hg
1611 bundle</command> command.
1612 </para>
1614 <para id="x_2a5">One possible use for this hook is to notify administrators
1615 that changes have been pulled.
1616 </para>
1618 <para id="x_2a6">Parameters to this hook:
1619 </para>
1620 <itemizedlist>
1621 <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The
1622 changeset ID of the first changeset of the group that was
1623 sent.
1624 </para>
1625 </listitem>
1626 <listitem><para id="x_2a8"><literal>source</literal>: A string. The
1627 source of the of the operation (see <xref
1628 linkend="sec:hook:sources"/>). If a remote
1629 client pulled changes from this repository,
1630 <literal>source</literal> will be
1631 <literal>serve</literal>. If the client that obtained
1632 changes from this repository was local,
1633 <literal>source</literal> will be
1634 <literal>bundle</literal>, <literal>pull</literal>, or
1635 <literal>push</literal>, depending on the operation the
1636 client performed.
1637 </para>
1638 </listitem>
1639 <listitem><para id="x_2a9"><literal>url</literal>: A URL. The
1640 location of the remote repository, if known. See <xref
1641 linkend="sec:hook:url"/> for more information.
1642 </para>
1643 </listitem></itemizedlist>
1645 <para id="x_2aa">See also: <literal
1646 role="hook">preoutgoing</literal> (<xref
1647 linkend="sec:hook:preoutgoing"/>)
1648 </para>
1650 </sect2>
1651 <sect2 id="sec:hook:prechangegroup">
1652 <title><literal
1653 role="hook">prechangegroup</literal>&emdash;before starting
1654 to add remote changesets</title>
1656 <para id="x_2ab">This controlling hook is run before Mercurial begins to
1657 add a group of changesets from another repository.
1658 </para>
1660 <para id="x_2ac">This hook does not have any information about the
1661 changesets to be added, because it is run before transmission
1662 of those changesets is allowed to begin. If this hook fails,
1663 the changesets will not be transmitted.
1664 </para>
1666 <para id="x_2ad">One use for this hook is to prevent external changes from
1667 being added to a repository. For example, you could use this
1668 to <quote>freeze</quote> a server-hosted branch temporarily or
1669 permanently so that users cannot push to it, while still
1670 allowing a local administrator to modify the repository.
1671 </para>
1673 <para id="x_2ae">Parameters to this hook:
1674 </para>
1675 <itemizedlist>
1676 <listitem><para id="x_2af"><literal>source</literal>: A string. The
1677 source of these changes. See <xref
1678 linkend="sec:hook:sources"/> for details.
1679 </para>
1680 </listitem>
1681 <listitem><para id="x_2b0"><literal>url</literal>: A URL. The
1682 location of the remote repository, if known. See <xref
1683 linkend="sec:hook:url"/> for more information.
1684 </para>
1685 </listitem></itemizedlist>
1687 <para id="x_2b1">See also: <literal
1688 role="hook">changegroup</literal> (<xref
1689 linkend="sec:hook:changegroup"/>), <literal
1690 role="hook">incoming</literal> (<xref
1691 linkend="sec:hook:incoming"/>), <literal
1692 role="hook">pretxnchangegroup</literal> (<xref
1693 linkend="sec:hook:pretxnchangegroup"/>)
1694 </para>
1696 </sect2>
1697 <sect2 id="sec:hook:precommit">
1698 <title><literal role="hook">precommit</literal>&emdash;before
1699 starting to commit a changeset</title>
1701 <para id="x_2b2">This hook is run before Mercurial begins to commit a new
1702 changeset. It is run before Mercurial has any of the metadata
1703 for the commit, such as the files to be committed, the commit
1704 message, or the commit date.
1705 </para>
1707 <para id="x_2b3">One use for this hook is to disable the ability to commit
1708 new changesets, while still allowing incoming changesets.
1709 Another is to run a build or test, and only allow the commit
1710 to begin if the build or test succeeds.
1711 </para>
1713 <para id="x_2b4">Parameters to this hook:
1714 </para>
1715 <itemizedlist>
1716 <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID.
1717 The changeset ID of the first parent of the working
1718 directory.
1719 </para>
1720 </listitem>
1721 <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID.
1722 The changeset ID of the second parent of the working
1723 directory.
1724 </para>
1725 </listitem></itemizedlist>
1726 <para id="x_2b7">If the commit proceeds, the parents of the working
1727 directory will become the parents of the new changeset.
1728 </para>
1730 <para id="x_2b8">See also: <literal role="hook">commit</literal>
1731 (<xref linkend="sec:hook:commit"/>), <literal
1732 role="hook">pretxncommit</literal> (<xref
1733 linkend="sec:hook:pretxncommit"/>)
1734 </para>
1736 </sect2>
1737 <sect2 id="sec:hook:preoutgoing">
1738 <title><literal role="hook">preoutgoing</literal>&emdash;before
1739 starting to propagate changesets</title>
1741 <para id="x_2b9">This hook is invoked before Mercurial knows the identities
1742 of the changesets to be transmitted.
1743 </para>
1745 <para id="x_2ba">One use for this hook is to prevent changes from being
1746 transmitted to another repository.
1747 </para>
1749 <para id="x_2bb">Parameters to this hook:
1750 </para>
1751 <itemizedlist>
1752 <listitem><para id="x_2bc"><literal>source</literal>: A
1753 string. The source of the operation that is attempting to
1754 obtain changes from this repository (see <xref
1755 linkend="sec:hook:sources"/>). See the documentation
1756 for the <literal>source</literal> parameter to the
1757 <literal role="hook">outgoing</literal> hook, in
1758 <xref linkend="sec:hook:outgoing"/>, for possible values
1759 of this parameter.
1760 </para>
1761 </listitem>
1762 <listitem><para id="x_2bd"><literal>url</literal>: A URL. The
1763 location of the remote repository, if known. See <xref
1764 linkend="sec:hook:url"/> for more information.
1765 </para>
1766 </listitem></itemizedlist>
1768 <para id="x_2be">See also: <literal
1769 role="hook">outgoing</literal> (<xref
1770 linkend="sec:hook:outgoing"/>)
1771 </para>
1773 </sect2>
1774 <sect2 id="sec:hook:pretag">
1775 <title><literal role="hook">pretag</literal>&emdash;before
1776 tagging a changeset</title>
1778 <para id="x_2bf">This controlling hook is run before a tag is created. If
1779 the hook succeeds, creation of the tag proceeds. If the hook
1780 fails, the tag is not created.
1781 </para>
1783 <para id="x_2c0">Parameters to this hook:
1784 </para>
1785 <itemizedlist>
1786 <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether
1787 the tag is local to this repository instance (i.e. stored
1788 in <filename role="special">.hg/localtags</filename>) or
1789 managed by Mercurial (stored in <filename
1790 role="special">.hgtags</filename>).
1791 </para>
1792 </listitem>
1793 <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The
1794 ID of the changeset to be tagged.
1795 </para>
1796 </listitem>
1797 <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of
1798 the tag to be created.
1799 </para>
1800 </listitem></itemizedlist>
1802 <para id="x_2c4">If the tag to be created is
1803 revision-controlled, the <literal
1804 role="hook">precommit</literal> and <literal
1805 role="hook">pretxncommit</literal> hooks (<xref
1806 linkend="sec:hook:commit"/> and <xref
1807 linkend="sec:hook:pretxncommit"/>) will also be run.
1808 </para>
1810 <para id="x_2c5">See also: <literal role="hook">tag</literal>
1811 (<xref linkend="sec:hook:tag"/>)
1812 </para>
1813 </sect2>
1814 <sect2 id="sec:hook:pretxnchangegroup">
1815 <title><literal
1816 role="hook">pretxnchangegroup</literal>&emdash;before
1817 completing addition of remote changesets</title>
1819 <para id="x_2c6">This controlling hook is run before a
1820 transaction&emdash;that manages the addition of a group of new
1821 changesets from outside the repository&emdash;completes. If
1822 the hook succeeds, the transaction completes, and all of the
1823 changesets become permanent within this repository. If the
1824 hook fails, the transaction is rolled back, and the data for
1825 the changesets is erased.
1826 </para>
1828 <para id="x_2c7">This hook can access the metadata associated with the
1829 almost-added changesets, but it should not do anything
1830 permanent with this data. It must also not modify the working
1831 directory.
1832 </para>
1834 <para id="x_2c8">While this hook is running, if other Mercurial processes
1835 access this repository, they will be able to see the
1836 almost-added changesets as if they are permanent. This may
1837 lead to race conditions if you do not take steps to avoid
1838 them.
1839 </para>
1841 <para id="x_2c9">This hook can be used to automatically vet a group of
1842 changesets. If the hook fails, all of the changesets are
1843 <quote>rejected</quote> when the transaction rolls back.
1844 </para>
1846 <para id="x_2ca">Parameters to this hook:
1847 </para>
1848 <itemizedlist>
1849 <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The
1850 changeset ID of the first changeset in the group that was
1851 added. All changesets between this and
1852 <literal role="tag">tip</literal>,
1853 inclusive, were added by a single <command
1854 role="hg-cmd">hg pull</command>, <command
1855 role="hg-cmd">hg push</command> or <command
1856 role="hg-cmd">hg unbundle</command>.
1857 </para>
1858 </listitem>
1859 <listitem><para id="x_2cc"><literal>source</literal>: A
1860 string. The source of these changes. See <xref
1861 linkend="sec:hook:sources"/> for details.
1862 </para>
1863 </listitem>
1864 <listitem><para id="x_2cd"><literal>url</literal>: A URL. The
1865 location of the remote repository, if known. See <xref
1866 linkend="sec:hook:url"/> for more information.
1867 </para>
1868 </listitem></itemizedlist>
1870 <para id="x_2ce">See also: <literal
1871 role="hook">changegroup</literal> (<xref
1872 linkend="sec:hook:changegroup"/>), <literal
1873 role="hook">incoming</literal> (<xref
1874 linkend="sec:hook:incoming"/>), <literal
1875 role="hook">prechangegroup</literal> (<xref
1876 linkend="sec:hook:prechangegroup"/>)
1877 </para>
1879 </sect2>
1880 <sect2 id="sec:hook:pretxncommit">
1881 <title><literal role="hook">pretxncommit</literal>&emdash;before
1882 completing commit of new changeset</title>
1884 <para id="x_2cf">This controlling hook is run before a
1885 transaction&emdash;that manages a new commit&emdash;completes.
1886 If the hook succeeds, the transaction completes and the
1887 changeset becomes permanent within this repository. If the
1888 hook fails, the transaction is rolled back, and the commit
1889 data is erased.
1890 </para>
1892 <para id="x_2d0">This hook can access the metadata associated with the
1893 almost-new changeset, but it should not do anything permanent
1894 with this data. It must also not modify the working
1895 directory.
1896 </para>
1898 <para id="x_2d1">While this hook is running, if other Mercurial processes
1899 access this repository, they will be able to see the
1900 almost-new changeset as if it is permanent. This may lead to
1901 race conditions if you do not take steps to avoid them.
1902 </para>
1904 <para id="x_2d2">Parameters to this hook:
1905 </para>
1906 <itemizedlist>
1907 <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The
1908 changeset ID of the newly committed changeset.
1909 </para>
1910 </listitem>
1911 <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID.
1912 The changeset ID of the first parent of the newly
1913 committed changeset.
1914 </para>
1915 </listitem>
1916 <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID.
1917 The changeset ID of the second parent of the newly
1918 committed changeset.
1919 </para>
1920 </listitem></itemizedlist>
1922 <para id="x_2d6">See also: <literal
1923 role="hook">precommit</literal> (<xref
1924 linkend="sec:hook:precommit"/>)
1925 </para>
1927 </sect2>
1928 <sect2 id="sec:hook:preupdate">
1929 <title><literal role="hook">preupdate</literal>&emdash;before
1930 updating or merging working directory</title>
1932 <para id="x_2d7">This controlling hook is run before an update
1933 or merge of the working directory begins. It is run only if
1934 Mercurial's normal pre-update checks determine that the update
1935 or merge can proceed. If the hook succeeds, the update or
1936 merge may proceed; if it fails, the update or merge does not
1937 start.
1938 </para>
1940 <para id="x_2d8">Parameters to this hook:
1941 </para>
1942 <itemizedlist>
1943 <listitem><para id="x_2d9"><literal>parent1</literal>: A
1944 changeset ID. The ID of the parent that the working
1945 directory is to be updated to. If the working directory
1946 is being merged, it will not change this parent.
1947 </para>
1948 </listitem>
1949 <listitem><para id="x_2da"><literal>parent2</literal>: A
1950 changeset ID. Only set if the working directory is being
1951 merged. The ID of the revision that the working directory
1952 is being merged with.
1953 </para>
1954 </listitem></itemizedlist>
1956 <para id="x_2db">See also: <literal role="hook">update</literal>
1957 (<xref linkend="sec:hook:update"/>)</para>
1959 </sect2>
1960 <sect2 id="sec:hook:tag">
1961 <title><literal role="hook">tag</literal>&emdash;after tagging a
1962 changeset</title>
1964 <para id="x_2dc">This hook is run after a tag has been created.
1965 </para>
1967 <para id="x_2dd">Parameters to this hook:
1968 </para>
1969 <itemizedlist>
1970 <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether
1971 the new tag is local to this repository instance (i.e.
1972 stored in <filename
1973 role="special">.hg/localtags</filename>) or managed by
1974 Mercurial (stored in <filename
1975 role="special">.hgtags</filename>).
1976 </para>
1977 </listitem>
1978 <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The
1979 ID of the changeset that was tagged.
1980 </para>
1981 </listitem>
1982 <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of
1983 the tag that was created.
1984 </para>
1985 </listitem></itemizedlist>
1987 <para id="x_2e1">If the created tag is revision-controlled, the <literal
1988 role="hook">commit</literal> hook (section <xref
1989 linkend="sec:hook:commit"/>) is run before this hook.
1990 </para>
1992 <para id="x_2e2">See also: <literal role="hook">pretag</literal>
1993 (<xref linkend="sec:hook:pretag"/>)
1994 </para>
1996 </sect2>
1997 <sect2 id="sec:hook:update">
1998 <title><literal role="hook">update</literal>&emdash;after
1999 updating or merging working directory</title>
2001 <para id="x_2e3">This hook is run after an update or merge of the working
2002 directory completes. Since a merge can fail (if the external
2003 <command>hgmerge</command> command fails to resolve conflicts
2004 in a file), this hook communicates whether the update or merge
2005 completed cleanly.
2006 </para>
2008 <itemizedlist>
2009 <listitem><para id="x_2e4"><literal>error</literal>: A boolean.
2010 Indicates whether the update or merge completed
2011 successfully.
2012 </para>
2013 </listitem>
2014 <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID.
2015 The ID of the parent that the working directory was
2016 updated to. If the working directory was merged, it will
2017 not have changed this parent.
2018 </para>
2019 </listitem>
2020 <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID.
2021 Only set if the working directory was merged. The ID of
2022 the revision that the working directory was merged with.
2023 </para>
2024 </listitem></itemizedlist>
2026 <para id="x_2e7">See also: <literal role="hook">preupdate</literal>
2027 (<xref linkend="sec:hook:preupdate"/>)
2028 </para>
2030 </sect2>
2031 </sect1>
2032 </chapter>
2034 <!--
2035 local variables:
2036 sgml-parent-document: ("00book.xml" "book" "chapter")
2037 end:
2038 -->