hgbook

annotate en/ch09-hook.xml @ 690:2c266a253b44

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