hgbook

annotate fr/ch10-hook.xml @ 964:6b680d569bb4

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