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