1.1 --- a/fr/ch10-hook.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch10-hook.xml	Thu Apr 22 12:39:32 2010 +0200
     1.3 @@ -1,1883 +1,1928 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>Handling repository events with hooks</title>
     1.8 -<para>\label{chap:hook}</para>
     1.9 -
    1.10 -<para>Mercurial offers a powerful mechanism to let you perform automated
    1.11 -actions in response to events that occur in a repository.  In some
    1.12 -cases, you can even control Mercurial's response to those events.</para>
    1.13 -
    1.14 -<para>The name Mercurial uses for one of these actions is a <emphasis>hook</emphasis>.
    1.15 -Hooks are called <quote>triggers</quote> in some revision control systems, but
    1.16 -the two names refer to the same idea.</para>
    1.17 -
    1.18 -<sect1>
    1.19 -<title>An overview of hooks in Mercurial</title>
    1.20 -
    1.21 -<para>Here is a brief list of the hooks that Mercurial supports.  We will
    1.22 -revisit each of these hooks in more detail later, in
    1.23 -section <xref linkend="sec:hook:ref"/>.</para>
    1.24 -
    1.25 -<itemizedlist>
    1.26 -<listitem><para><literal role="hook">changegroup</literal>: This is run after a group of
    1.27 -  changesets has been brought into the repository from elsewhere.</para>
    1.28 -</listitem>
    1.29 -<listitem><para><literal role="hook">commit</literal>: This is run after a new changeset has been
    1.30 -  created in the local repository.</para>
    1.31 -</listitem>
    1.32 -<listitem><para><literal role="hook">incoming</literal>: This is run once for each new changeset
    1.33 -  that is brought into the repository from elsewhere.  Notice the
    1.34 -  difference from <literal role="hook">changegroup</literal>, which is run once per
    1.35 -  <emphasis>group</emphasis> of changesets brought in.</para>
    1.36 -</listitem>
    1.37 -<listitem><para><literal role="hook">outgoing</literal>: This is run after a group of changesets
    1.38 -  has been transmitted from this repository.</para>
    1.39 -</listitem>
    1.40 -<listitem><para><literal role="hook">prechangegroup</literal>: This is run before starting to
    1.41 -  bring a group of changesets into the repository.
    1.42 -</para>
    1.43 -</listitem>
    1.44 -<listitem><para><literal role="hook">precommit</literal>: Controlling. This is run before starting
    1.45 -  a commit.
    1.46 -</para>
    1.47 -</listitem>
    1.48 -<listitem><para><literal role="hook">preoutgoing</literal>: Controlling. This is run before
    1.49 -  starting to transmit a group of changesets from this repository.
    1.50 -</para>
    1.51 -</listitem>
    1.52 -<listitem><para><literal role="hook">pretag</literal>: Controlling. This is run before creating a tag.
    1.53 -</para>
    1.54 -</listitem>
    1.55 -<listitem><para><literal role="hook">pretxnchangegroup</literal>: Controlling. This is run after a
    1.56 -  group of changesets has been brought into the local repository from
    1.57 -  another, but before the transaction completes that will make the
    1.58 -  changes permanent in the repository.
    1.59 -</para>
    1.60 -</listitem>
    1.61 -<listitem><para><literal role="hook">pretxncommit</literal>: Controlling. This is run after a new
    1.62 -  changeset has been created in the local repository, but before the
    1.63 -  transaction completes that will make it permanent.
    1.64 -</para>
    1.65 -</listitem>
    1.66 -<listitem><para><literal role="hook">preupdate</literal>: Controlling. This is run before starting
    1.67 -  an update or merge of the working directory.
    1.68 -</para>
    1.69 -</listitem>
    1.70 -<listitem><para><literal role="hook">tag</literal>: This is run after a tag is created.
    1.71 -</para>
    1.72 -</listitem>
    1.73 -<listitem><para><literal role="hook">update</literal>: This is run after an update or merge of the
    1.74 -  working directory has finished.
    1.75 -</para>
    1.76 -</listitem></itemizedlist>
    1.77 -<para>Each of the hooks whose description begins with the word
    1.78 -<quote>Controlling</quote> has the ability to determine whether an activity can
    1.79 -proceed.  If the hook succeeds, the activity may proceed; if it fails,
    1.80 -the activity is either not permitted or undone, depending on the hook.
    1.81 -</para>
    1.82 -
    1.83 -</sect1>
    1.84 -<sect1>
    1.85 -<title>Hooks and security</title>
    1.86 -
    1.87 -<sect2>
    1.88 -<title>Hooks are run with your privileges</title>
    1.89 -
    1.90 -<para>When you run a Mercurial command in a repository, and the command
    1.91 -causes a hook to run, that hook runs on <emphasis>your</emphasis> system, under
    1.92 -<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> privilege level.  Since
    1.93 -hooks are arbitrary pieces of executable code, you should treat them
    1.94 -with an appropriate level of suspicion.  Do not install a hook unless
    1.95 -you are confident that you know who created it and what it does.
    1.96 -</para>
    1.97 -
    1.98 -<para>In some cases, you may be exposed to hooks that you did not install
    1.99 -yourself.  If you work with Mercurial on an unfamiliar system,
   1.100 -Mercurial will run hooks defined in that system's global <filename role="special"> /.hgrc</filename>\ file.
   1.101 -</para>
   1.102 -
   1.103 -<para>If you are working with a repository owned by another user, Mercurial
   1.104 -can run hooks defined in that user's repository, but it will still run
   1.105 -them as <quote>you</quote>.  For example, if you <command role="hg-cmd">hg pull</command> from that
   1.106 -repository, and its <filename role="special">.hg/hgrc</filename> defines a local
   1.107 -<literal role="hook">outgoing</literal> hook, that hook will run under your user account, even
   1.108 -though you don't own that repository.
   1.109 -</para>
   1.110 -
   1.111 -<note>
   1.112 -<para>  This only applies if you are pulling from a repository on a local or
   1.113 -  network filesystem.  If you're pulling over http or ssh, any
   1.114 -  <literal role="hook">outgoing</literal> hook will run under whatever account is executing
   1.115 -  the server process, on the server.
   1.116 -</para>
   1.117 -</note>
   1.118 -
   1.119 -<para>XXX To see what hooks are defined in a repository, use the
   1.120 -<command role="hg-cmd">hg config hooks</command> command.  If you are working in one
   1.121 -repository, but talking to another that you do not own (e.g. using
   1.122 -<command role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg incoming</command>), remember that it is the other
   1.123 -repository's hooks you should be checking, not your own.
   1.124 -</para>
   1.125 -
   1.126 -</sect2>
   1.127 -<sect2>
   1.128 -<title>Hooks do not propagate</title>
   1.129 -
   1.130 -<para>In Mercurial, hooks are not revision controlled, and do not propagate
   1.131 -when you clone, or pull from, a repository.  The reason for this is
   1.132 -simple: a hook is a completely arbitrary piece of executable code.  It
   1.133 -runs under your user identity, with your privilege level, on your
   1.134 -machine.
   1.135 -</para>
   1.136 -
   1.137 -<para>It would be extremely reckless for any distributed revision control
   1.138 -system to implement revision-controlled hooks, as this would offer an
   1.139 -easily exploitable way to subvert the accounts of users of the
   1.140 -revision control system.
   1.141 -</para>
   1.142 -
   1.143 -<para>Since Mercurial does not propagate hooks, if you are collaborating
   1.144 -with other people on a common project, you should not assume that they
   1.145 -are using the same Mercurial hooks as you are, or that theirs are
   1.146 -correctly configured.  You should document the hooks you expect people
   1.147 -to use.
   1.148 -</para>
   1.149 -
   1.150 -<para>In a corporate intranet, this is somewhat easier to control, as you
   1.151 -can for example provide a <quote>standard</quote> installation of Mercurial on an
   1.152 -NFS filesystem, and use a site-wide <filename role="special"> /.hgrc</filename>\ file to define hooks that
   1.153 -all users will see.  However, this too has its limits; see below.
   1.154 -</para>
   1.155 -
   1.156 -</sect2>
   1.157 -<sect2>
   1.158 -<title>Hooks can be overridden</title>
   1.159 -
   1.160 -<para>Mercurial allows you to override a hook definition by redefining the
   1.161 -hook.  You can disable it by setting its value to the empty string, or
   1.162 -change its behaviour as you wish.
   1.163 -</para>
   1.164 -
   1.165 -<para>If you deploy a system- or site-wide <filename role="special"> /.hgrc</filename>\ file that defines some
   1.166 -hooks, you should thus understand that your users can disable or
   1.167 -override those hooks.
   1.168 -</para>
   1.169 -
   1.170 -</sect2>
   1.171 -<sect2>
   1.172 -<title>Ensuring that critical hooks are run</title>
   1.173 -
   1.174 -<para>Sometimes you may want to enforce a policy that you do not want others
   1.175 -to be able to work around.  For example, you may have a requirement
   1.176 -that every changeset must pass a rigorous set of tests.  Defining this
   1.177 -requirement via a hook in a site-wide <filename role="special"> /.hgrc</filename>\ won't work for remote
   1.178 -users on laptops, and of course local users can subvert it at will by
   1.179 -overriding the hook.
   1.180 -</para>
   1.181 -
   1.182 -<para>Instead, you can set up your policies for use of Mercurial so that
   1.183 -people are expected to propagate changes through a well-known
   1.184 -<quote>canonical</quote> server that you have locked down and configured
   1.185 -appropriately.
   1.186 -</para>
   1.187 -
   1.188 -<para>One way to do this is via a combination of social engineering and
   1.189 -technology.  Set up a restricted-access account; users can push
   1.190 -changes over the network to repositories managed by this account, but
   1.191 -they cannot log into the account and run normal shell commands.  In
   1.192 -this scenario, a user can commit a changeset that contains any old
   1.193 -garbage they want.
   1.194 -</para>
   1.195 -
   1.196 -<para>When someone pushes a changeset to the server that everyone pulls
   1.197 -from, the server will test the changeset before it accepts it as
   1.198 -permanent, and reject it if it fails to pass the test suite.  If
   1.199 -people only pull changes from this filtering server, it will serve to
   1.200 -ensure that all changes that people pull have been automatically
   1.201 -vetted.
   1.202 -</para>
   1.203 -
   1.204 -</sect2>
   1.205 -</sect1>
   1.206 -<sect1>
   1.207 -<title>Care with <literal>pretxn</literal> hooks in a shared-access repository</title>
   1.208 -
   1.209 -<para>If you want to use hooks to do some automated work in a repository
   1.210 -that a number of people have shared access to, you need to be careful
   1.211 -in how you do this.
   1.212 -</para>
   1.213 -
   1.214 -<para>Mercurial only locks a repository when it is writing to the
   1.215 -repository, and only the parts of Mercurial that write to the
   1.216 -repository pay attention to locks.  Write locks are necessary to
   1.217 -prevent multiple simultaneous writers from scribbling on each other's
   1.218 -work, corrupting the repository.
   1.219 -</para>
   1.220 -
   1.221 -<para>Because Mercurial is careful with the order in which it reads and
   1.222 -writes data, it does not need to acquire a lock when it wants to read
   1.223 -data from the repository.  The parts of Mercurial that read from the
   1.224 -repository never pay attention to locks.  This lockless reading scheme
   1.225 -greatly increases performance and concurrency.
   1.226 -</para>
   1.227 -
   1.228 -<para>With great performance comes a trade-off, though, one which has the
   1.229 -potential to cause you trouble unless you're aware of it.  To describe
   1.230 -this requires a little detail about how Mercurial adds changesets to a
   1.231 -repository and reads those changes.
   1.232 -</para>
   1.233 -
   1.234 -<para>When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight into the
   1.235 -destination file.  It writes file data first, then manifest data
   1.236 -(which contains pointers to the new file data), then changelog data
   1.237 -(which contains pointers to the new manifest data).  Before the first
   1.238 -write to each file, it stores a record of where the end of the file
   1.239 -was in its transaction log.  If the transaction must be rolled back,
   1.240 -Mercurial simply truncates each file back to the size it was before the
   1.241 -transaction began.
   1.242 -</para>
   1.243 -
   1.244 -<para>When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog first,
   1.245 -then everything else.  Since a reader will only access parts of the
   1.246 -manifest or file metadata that it can see in the changelog, it can
   1.247 -never see partially written data.
   1.248 -</para>
   1.249 -
   1.250 -<para>Some controlling hooks (<literal role="hook">pretxncommit</literal> and
   1.251 -<literal role="hook">pretxnchangegroup</literal>) run when a transaction is almost complete.
   1.252 -All of the metadata has been written, but Mercurial can still roll the
   1.253 -transaction back and cause the newly-written data to disappear.
   1.254 -</para>
   1.255 -
   1.256 -<para>If one of these hooks runs for long, it opens a window of time during
   1.257 -which a reader can see the metadata for changesets that are not yet
   1.258 -permanent, and should not be thought of as <quote>really there</quote>.  The
   1.259 -longer the hook runs, the longer that window is open.
   1.260 -</para>
   1.261 -
   1.262 -<sect2>
   1.263 -<title>The problem illustrated</title>
   1.264 -
   1.265 -<para>In principle, a good use for the <literal role="hook">pretxnchangegroup</literal> hook would
   1.266 -be to automatically build and test incoming changes before they are
   1.267 -accepted into a central repository.  This could let you guarantee that
   1.268 -nobody can push changes to this repository that <quote>break the build</quote>.
   1.269 -But if a client can pull changes while they're being tested, the
   1.270 -usefulness of the test is zero; an unsuspecting someone can pull
   1.271 -untested changes, potentially breaking their build.
   1.272 -</para>
   1.273 -
   1.274 -<para>The safest technological answer to this challenge is to set up such a
   1.275 -<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>.  Let it take
   1.276 -changes pushed in from the outside, but do not allow anyone to pull
   1.277 -changes from it (use the <literal role="hook">preoutgoing</literal> hook to lock it down).
   1.278 -Configure a <literal role="hook">changegroup</literal> hook so that if a build or test
   1.279 -succeeds, the hook will push the new changes out to another repository
   1.280 -that people <emphasis>can</emphasis> pull from.
   1.281 -</para>
   1.282 -
   1.283 -<para>In practice, putting a centralised bottleneck like this in place is
   1.284 -not often a good idea, and transaction visibility has nothing to do
   1.285 -with the problem.  As the size of a project&emdash;and the time it takes to
   1.286 -build and test&emdash;grows, you rapidly run into a wall with this <quote>try
   1.287 -before you buy</quote> approach, where you have more changesets to test than
   1.288 -time in which to deal with them.  The inevitable result is frustration
   1.289 -on the part of all involved.
   1.290 -</para>
   1.291 -
   1.292 -<para>An approach that scales better is to get people to build and test
   1.293 -before they push, then run automated builds and tests centrally
   1.294 -<emphasis>after</emphasis> a push, to be sure all is well.  The advantage of this
   1.295 -approach is that it does not impose a limit on the rate at which the
   1.296 -repository can accept changes.
   1.297 -</para>
   1.298 -
   1.299 -</sect2>
   1.300 -</sect1>
   1.301 -<sect1>
   1.302 -<title>A short tutorial on using hooks</title>
   1.303 -<para>\label{sec:hook:simple}
   1.304 -</para>
   1.305 -
   1.306 -<para>It is easy to write a Mercurial hook.  Let's start with a hook that
   1.307 -runs when you finish a <command role="hg-cmd">hg commit</command>, and simply prints the hash of
   1.308 -the changeset you just created.  The hook is called <literal role="hook">commit</literal>.
   1.309 -</para>
   1.310 -
   1.311 -<informalfigure>
   1.312 -<para>  <!-- &interaction.hook.simple.init; -->
   1.313 -  <caption><para>A simple hook that runs when a changeset is committed</para></caption>
   1.314 -  \label{ex:hook:init}
   1.315 -</para>
   1.316 -</informalfigure>
   1.317 -
   1.318 -<para>All hooks follow the pattern in example <xref linkend="ex:hook:init"/>.  You add
   1.319 -an entry to the <literal role="rc-hooks">hooks</literal> section of your <filename role="special"> /.hgrc</filename>.  On the left
   1.320 -is the name of the event to trigger on; on the right is the action to
   1.321 -take.  As you can see, you can run an arbitrary shell command in a
   1.322 -hook.  Mercurial passes extra information to the hook using
   1.323 -environment variables (look for <envar>HG_NODE</envar> in the example).
   1.324 -</para>
   1.325 -
   1.326 -<sect2>
   1.327 -<title>Performing multiple actions per event</title>
   1.328 -
   1.329 -<para>Quite often, you will want to define more than one hook for a
   1.330 -particular kind of event, as shown in example <xref linkend="ex:hook:ext"/>.
   1.331 -Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the end of
   1.332 -a hook's name.  You extend a hook's name by giving the name of the
   1.333 -hook, followed by a full stop (the <quote><literal>.</literal></quote> character), followed
   1.334 -by some more text of your choosing.  For example, Mercurial will run
   1.335 -both <literal>commit.foo</literal> and <literal>commit.bar</literal> when the
   1.336 -<literal>commit</literal> event occurs.
   1.337 -</para>
   1.338 -
   1.339 -<informalfigure>
   1.340 -<para>  <!-- &interaction.hook.simple.ext; -->
   1.341 -  <caption><para>Defining a second <literal role="hook">commit</para></caption> hook</literal>
   1.342 -  \label{ex:hook:ext}
   1.343 -</para>
   1.344 -</informalfigure>
   1.345 -
   1.346 -<para>To give a well-defined order of execution when there are multiple
   1.347 -hooks defined for an event, Mercurial sorts hooks by extension, and
   1.348 -executes the hook commands in this sorted order.  In the above
   1.349 -example, it will execute <literal>commit.bar</literal> before
   1.350 -<literal>commit.foo</literal>, and <literal>commit</literal> before both.
   1.351 -</para>
   1.352 -
   1.353 -<para>It is a good idea to use a somewhat descriptive extension when you
   1.354 -define a new hook.  This will help you to remember what the hook was
   1.355 -for.  If the hook fails, you'll get an error message that contains the
   1.356 -hook name and extension, so using a descriptive extension could give
   1.357 -you an immediate hint as to why the hook failed (see
   1.358 -section <xref linkend="sec:hook:perm"/> for an example).
   1.359 -</para>
   1.360 -
   1.361 -</sect2>
   1.362 -<sect2>
   1.363 -<title>Controlling whether an activity can proceed</title>
   1.364 -<para>\label{sec:hook:perm}
   1.365 -</para>
   1.366 -
   1.367 -<para>In our earlier examples, we used the <literal role="hook">commit</literal> hook, which is
   1.368 -run after a commit has completed.  This is one of several Mercurial
   1.369 -hooks that run after an activity finishes.  Such hooks have no way of
   1.370 -influencing the activity itself.
   1.371 -</para>
   1.372 -
   1.373 -<para>Mercurial defines a number of events that occur before an activity
   1.374 -starts; or after it starts, but before it finishes.  Hooks that
   1.375 -trigger on these events have the added ability to choose whether the
   1.376 -activity can continue, or will abort.
   1.377 -</para>
   1.378 -
   1.379 -<para>The <literal role="hook">pretxncommit</literal> hook runs after a commit has all but
   1.380 -completed.  In other words, the metadata representing the changeset
   1.381 -has been written out to disk, but the transaction has not yet been
   1.382 -allowed to complete.  The <literal role="hook">pretxncommit</literal> hook has the ability to
   1.383 -decide whether the transaction can complete, or must be rolled back.
   1.384 -</para>
   1.385 -
   1.386 -<para>If the <literal role="hook">pretxncommit</literal> hook exits with a status code of zero, the
   1.387 -transaction is allowed to complete; the commit finishes; and the
   1.388 -<literal role="hook">commit</literal> hook is run.  If the <literal role="hook">pretxncommit</literal> hook exits with
   1.389 -a non-zero status code, the transaction is rolled back; the metadata
   1.390 -representing the changeset is erased; and the <literal role="hook">commit</literal> hook is
   1.391 -not run.
   1.392 -</para>
   1.393 -
   1.394 -<informalfigure>
   1.395 -<para>  <!-- &interaction.hook.simple.pretxncommit; -->
   1.396 -  <caption><para>Using the <literal role="hook">pretxncommit</para></caption> hook to control commits</literal>
   1.397 -  \label{ex:hook:pretxncommit}
   1.398 -</para>
   1.399 -</informalfigure>
   1.400 -
   1.401 -<para>The hook in example <xref linkend="ex:hook:pretxncommit"/> checks that a commit
   1.402 -comment contains a bug ID.  If it does, the commit can complete.  If
   1.403 -not, the commit is rolled back.
   1.404 -</para>
   1.405 -
   1.406 -</sect2>
   1.407 -</sect1>
   1.408 -<sect1>
   1.409 -<title>Writing your own hooks</title>
   1.410 -
   1.411 -<para>When you are writing a hook, you might find it useful to run Mercurial
   1.412 -either with the <option role="hg-opt-global">-v</option> option, or the <envar role="rc-item-ui">verbose</envar> config
   1.413 -item set to <quote>true</quote>.  When you do so, Mercurial will print a message
   1.414 -before it calls each hook.
   1.415 -</para>
   1.416 -
   1.417 -<sect2>
   1.418 -<title>Choosing how your hook should run</title>
   1.419 -<para>\label{sec:hook:lang}
   1.420 -</para>
   1.421 -
   1.422 -<para>You can write a hook either as a normal program&emdash;typically a shell
   1.423 -script&emdash;or as a Python function that is executed within the Mercurial
   1.424 -process.
   1.425 -</para>
   1.426 -
   1.427 -<para>Writing a hook as an external program has the advantage that it
   1.428 -requires no knowledge of Mercurial's internals.  You can call normal
   1.429 -Mercurial commands to get any added information you need.  The
   1.430 -trade-off is that external hooks are slower than in-process hooks.
   1.431 -</para>
   1.432 -
   1.433 -<para>An in-process Python hook has complete access to the Mercurial API,
   1.434 -and does not <quote>shell out</quote> to another process, so it is inherently
   1.435 -faster than an external hook.  It is also easier to obtain much of the
   1.436 -information that a hook requires by using the Mercurial API than by
   1.437 -running Mercurial commands.
   1.438 -</para>
   1.439 -
   1.440 -<para>If you are comfortable with Python, or require high performance,
   1.441 -writing your hooks in Python may be a good choice.  However, when you
   1.442 -have a straightforward hook to write and you don't need to care about
   1.443 -performance (probably the majority of hooks), a shell script is
   1.444 -perfectly fine.
   1.445 -</para>
   1.446 -
   1.447 -</sect2>
   1.448 -<sect2>
   1.449 -<title>Hook parameters</title>
   1.450 -<para>\label{sec:hook:param}
   1.451 -</para>
   1.452 -
   1.453 -<para>Mercurial calls each hook with a set of well-defined parameters.  In
   1.454 -Python, a parameter is passed as a keyword argument to your hook
   1.455 -function.  For an external program, a parameter is passed as an
   1.456 -environment variable.
   1.457 -</para>
   1.458 -
   1.459 -<para>Whether your hook is written in Python or as a shell script, the
   1.460 -hook-specific parameter names and values will be the same.  A boolean
   1.461 -parameter will be represented as a boolean value in Python, but as the
   1.462 -number 1 (for <quote>true</quote>) or 0 (for <quote>false</quote>) as an environment
   1.463 -variable for an external hook.  If a hook parameter is named
   1.464 -<literal>foo</literal>, the keyword argument for a Python hook will also be
   1.465 -named <literal>foo</literal>, while the environment variable for an external
   1.466 -hook will be named <literal>HG_FOO</literal>.
   1.467 -</para>
   1.468 -
   1.469 -</sect2>
   1.470 -<sect2>
   1.471 -<title>Hook return values and activity control</title>
   1.472 -
   1.473 -<para>A hook that executes successfully must exit with a status of zero if
   1.474 -external, or return boolean <quote>false</quote> if in-process.  Failure is
   1.475 -indicated with a non-zero exit status from an external hook, or an
   1.476 -in-process hook returning boolean <quote>true</quote>.  If an in-process hook
   1.477 -raises an exception, the hook is considered to have failed.
   1.478 -</para>
   1.479 -
   1.480 -<para>For a hook that controls whether an activity can proceed, zero/false
   1.481 -means <quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>.
   1.482 -</para>
   1.483 -
   1.484 -</sect2>
   1.485 -<sect2>
   1.486 -<title>Writing an external hook</title>
   1.487 -
   1.488 -<para>When you define an external hook in your <filename role="special"> /.hgrc</filename>\ and the hook is run,
   1.489 -its value is passed to your shell, which interprets it.  This means
   1.490 -that you can use normal shell constructs in the body of the hook.
   1.491 -</para>
   1.492 -
   1.493 -<para>An executable hook is always run with its current directory set to a
   1.494 -repository's root directory.
   1.495 -</para>
   1.496 -
   1.497 -<para>Each hook parameter is passed in as an environment variable; the name
   1.498 -is upper-cased, and prefixed with the string <quote><literal>HG_</literal></quote>.
   1.499 -</para>
   1.500 -
   1.501 -<para>With the exception of hook parameters, Mercurial does not set or
   1.502 -modify any environment variables when running a hook.  This is useful
   1.503 -to remember if you are writing a site-wide hook that may be run by a
   1.504 -number of different users with differing environment variables set.
   1.505 -In multi-user situations, you should not rely on environment variables
   1.506 -being set to the values you have in your environment when testing the
   1.507 -hook.
   1.508 -</para>
   1.509 -
   1.510 -</sect2>
   1.511 -<sect2>
   1.512 -<title>Telling Mercurial to use an in-process hook</title>
   1.513 -
   1.514 -<para>The <filename role="special"> /.hgrc</filename>\ syntax for defining an in-process hook is slightly
   1.515 -different than for an executable hook.  The value of the hook must
   1.516 -start with the text <quote><literal>python:</literal></quote>, and continue with the
   1.517 -fully-qualified name of a callable object to use as the hook's value.
   1.518 -</para>
   1.519 -
   1.520 -<para>The module in which a hook lives is automatically imported when a hook
   1.521 -is run.  So long as you have the module name and <envar>PYTHONPATH</envar>
   1.522 -right, it should <quote>just work</quote>.
   1.523 -</para>
   1.524 -
   1.525 -<para>The following <filename role="special"> /.hgrc</filename>\ example snippet illustrates the syntax and
   1.526 -meaning of the notions we just described.
   1.527 -</para>
   1.528 -<programlisting>
   1.529 -<para>  [hooks]
   1.530 -  commit.example = python:mymodule.submodule.myhook
   1.531 -</para>
   1.532 -</programlisting>
   1.533 -<para>When Mercurial runs the <literal>commit.example</literal> hook, it imports
   1.534 -<literal>mymodule.submodule</literal>, looks for the callable object named
   1.535 -<literal>myhook</literal>, and calls it.
   1.536 -</para>
   1.537 -
   1.538 -</sect2>
   1.539 -<sect2>
   1.540 -<title>Writing an in-process hook</title>
   1.541 -
   1.542 -<para>The simplest in-process hook does nothing, but illustrates the basic
   1.543 -shape of the hook API:
   1.544 -</para>
   1.545 -<programlisting>
   1.546 -<para>  def myhook(ui, repo, **kwargs):
   1.547 -      pass
   1.548 -</para>
   1.549 -</programlisting>
   1.550 -<para>The first argument to a Python hook is always a
   1.551 -<literal role="py-mod-mercurial.ui">ui</literal> object.  The second is a repository object;
   1.552 -at the moment, it is always an instance of
   1.553 -<literal role="py-mod-mercurial.localrepo">localrepository</literal>.  Following these two
   1.554 -arguments are other keyword arguments.  Which ones are passed in
   1.555 -depends on the hook being called, but a hook can ignore arguments it
   1.556 -doesn't care about by dropping them into a keyword argument dict, as
   1.557 -with <literal>**kwargs</literal> above.
   1.558 -</para>
   1.559 -
   1.560 -</sect2>
   1.561 -</sect1>
   1.562 -<sect1>
   1.563 -<title>Some hook examples</title>
   1.564 -
   1.565 -<sect2>
   1.566 -<title>Writing meaningful commit messages</title>
   1.567 -
   1.568 -<para>It's hard to imagine a useful commit message being very short.  The
   1.569 -simple <literal role="hook">pretxncommit</literal> hook of figure <xref linkend="ex:hook:msglen.go"/>
   1.570 -will prevent you from committing a changeset with a message that is
   1.571 -less than ten bytes long.
   1.572 -</para>
   1.573 -
   1.574 -<informalfigure>
   1.575 -<para>  <!-- &interaction.hook.msglen.go; -->
   1.576 -  <caption><para>A hook that forbids overly short commit messages</para></caption>
   1.577 -  \label{ex:hook:msglen.go}
   1.578 -</para>
   1.579 -</informalfigure>
   1.580 -
   1.581 -</sect2>
   1.582 -<sect2>
   1.583 -<title>Checking for trailing whitespace</title>
   1.584 -
   1.585 -<para>An interesting use of a commit-related hook is to help you to write
   1.586 -cleaner code.  A simple example of <quote>cleaner code</quote> is the dictum that
   1.587 -a change should not add any new lines of text that contain <quote>trailing
   1.588 -whitespace</quote>.  Trailing whitespace is a series of space and tab
   1.589 -characters at the end of a line of text.  In most cases, trailing
   1.590 -whitespace is unnecessary, invisible noise, but it is occasionally
   1.591 -problematic, and people often prefer to get rid of it.
   1.592 -</para>
   1.593 -
   1.594 -<para>You can use either the <literal role="hook">precommit</literal> or <literal role="hook">pretxncommit</literal> hook to
   1.595 -tell whether you have a trailing whitespace problem.  If you use the
   1.596 -<literal role="hook">precommit</literal> hook, the hook will not know which files you are
   1.597 -committing, so it will have to check every modified file in the
   1.598 -repository for trailing white space.  If you want to commit a change
   1.599 -to just the file <filename>foo</filename>, but the file <filename>bar</filename> contains
   1.600 -trailing whitespace, doing a check in the <literal role="hook">precommit</literal> hook will
   1.601 -prevent you from committing <filename>foo</filename> due to the problem with
   1.602 -<filename>bar</filename>.  This doesn't seem right.
   1.603 -</para>
   1.604 -
   1.605 -<para>Should you choose the <literal role="hook">pretxncommit</literal> hook, the check won't occur
   1.606 -until just before the transaction for the commit completes.  This will
   1.607 -allow you to check for problems only the exact files that are being
   1.608 -committed.  However, if you entered the commit message interactively
   1.609 -and the hook fails, the transaction will roll back; you'll have to
   1.610 -re-enter the commit message after you fix the trailing whitespace and
   1.611 -run <command role="hg-cmd">hg commit</command> again.
   1.612 -</para>
   1.613 -
   1.614 -<informalfigure>
   1.615 -<para>  <!-- &interaction.hook.ws.simple; -->
   1.616 -  <caption><para>A simple hook that checks for trailing whitespace</para></caption>
   1.617 -  \label{ex:hook:ws.simple}
   1.618 -</para>
   1.619 -</informalfigure>
   1.620 -
   1.621 -<para>Figure <xref linkend="ex:hook:ws.simple"/> introduces a simple <literal role="hook">pretxncommit</literal>
   1.622 -hook that checks for trailing whitespace.  This hook is short, but not
   1.623 -very helpful.  It exits with an error status if a change adds a line
   1.624 -with trailing whitespace to any file, but does not print any
   1.625 -information that might help us to identify the offending file or
   1.626 -line.  It also has the nice property of not paying attention to
   1.627 -unmodified lines; only lines that introduce new trailing whitespace
   1.628 -cause problems.
   1.629 -</para>
   1.630 -
   1.631 -<informalfigure>
   1.632 -<para>  <!-- &interaction.hook.ws.better; -->
   1.633 -  <caption><para>A better trailing whitespace hook</para></caption>
   1.634 -  \label{ex:hook:ws.better}
   1.635 -</para>
   1.636 -</informalfigure>
   1.637 -
   1.638 -<para>The example of figure <xref linkend="ex:hook:ws.better"/> is much more complex,
   1.639 -but also more useful.  It parses a unified diff to see if any lines
   1.640 -add trailing whitespace, and prints the name of the file and the line
   1.641 -number of each such occurrence.  Even better, if the change adds
   1.642 -trailing whitespace, this hook saves the commit comment and prints the
   1.643 -name of the save file before exiting and telling Mercurial to roll the
   1.644 -transaction back, so you can use
   1.645 -<command role="hg-cmd">hg commit <option role="hg-opt-commit">-l</option> <emphasis>filename</emphasis></command> to reuse the
   1.646 -saved commit message once you've corrected the problem.
   1.647 -</para>
   1.648 -
   1.649 -<para>As a final aside, note in figure <xref linkend="ex:hook:ws.better"/> the use of
   1.650 -<command>perl</command>'s in-place editing feature to get rid of trailing
   1.651 -whitespace from a file.  This is concise and useful enough that I will
   1.652 -reproduce it here.
   1.653 -</para>
   1.654 -<programlisting>
   1.655 -<para>  perl -pi -e 's,\textbackslash{}s+$,,' filename
   1.656 -</para>
   1.657 -</programlisting>
   1.658 -
   1.659 -</sect2>
   1.660 -</sect1>
   1.661 -<sect1>
   1.662 -<title>Bundled hooks</title>
   1.663 -
   1.664 -<para>Mercurial ships with several bundled hooks.  You can find them in the
   1.665 -<filename class="directory">hgext</filename> directory of a Mercurial source tree.  If you are
   1.666 -using a Mercurial binary package, the hooks will be located in the
   1.667 -<filename class="directory">hgext</filename> directory of wherever your package installer put
   1.668 -Mercurial.
   1.669 -</para>
   1.670 -
   1.671 -<sect2>
   1.672 -<title><literal role="hg-ext">acl</literal>&emdash;access control for parts of a repository</title>
   1.673 -
   1.674 -<para>The <literal role="hg-ext">acl</literal> extension lets you control which remote users are
   1.675 -allowed to push changesets to a networked server.  You can protect any
   1.676 -portion of a repository (including the entire repo), so that a
   1.677 -specific remote user can push changes that do not affect the protected
   1.678 -portion.
   1.679 -</para>
   1.680 -
   1.681 -<para>This extension implements access control based on the identity of the
   1.682 -user performing a push, <emphasis>not</emphasis> on who committed the changesets
   1.683 -they're pushing.  It makes sense to use this hook only if you have a
   1.684 -locked-down server environment that authenticates remote users, and
   1.685 -you want to be sure that only specific users are allowed to push
   1.686 -changes to that server.
   1.687 -</para>
   1.688 -
   1.689 -<sect3>
   1.690 -<title>Configuring the <literal role="hook">acl</literal> hook</title>
   1.691 -
   1.692 -<para>In order to manage incoming changesets, the <literal role="hg-ext">acl</literal> hook must be
   1.693 -used as a <literal role="hook">pretxnchangegroup</literal> hook.  This lets it see which files
   1.694 -are modified by each incoming changeset, and roll back a group of
   1.695 -changesets if they modify <quote>forbidden</quote> files.  Example:
   1.696 -</para>
   1.697 -<programlisting>
   1.698 -<para>  [hooks]
   1.699 -  pretxnchangegroup.acl = python:hgext.acl.hook
   1.700 -</para>
   1.701 -</programlisting>
   1.702 -
   1.703 -<para>The <literal role="hg-ext">acl</literal> extension is configured using three sections.
   1.704 -</para>
   1.705 -
   1.706 -<para>The <literal role="rc-acl">acl</literal> section has only one entry, <envar role="rc-item-acl">sources</envar>,
   1.707 -which lists the sources of incoming changesets that the hook should
   1.708 -pay attention to.  You don't normally need to configure this section.
   1.709 -</para>
   1.710 -<itemizedlist>
   1.711 -<listitem><para><envar role="rc-item-acl">serve</envar>: Control incoming changesets that are arriving
   1.712 -  from a remote repository over http or ssh.  This is the default
   1.713 -  value of <envar role="rc-item-acl">sources</envar>, and usually the only setting you'll
   1.714 -  need for this configuration item.
   1.715 -</para>
   1.716 -</listitem>
   1.717 -<listitem><para><envar role="rc-item-acl">pull</envar>: Control incoming changesets that are
   1.718 -  arriving via a pull from a local repository.
   1.719 -</para>
   1.720 -</listitem>
   1.721 -<listitem><para><envar role="rc-item-acl">push</envar>: Control incoming changesets that are
   1.722 -  arriving via a push from a local repository.
   1.723 -</para>
   1.724 -</listitem>
   1.725 -<listitem><para><envar role="rc-item-acl">bundle</envar>: Control incoming changesets that are
   1.726 -  arriving from another repository via a bundle.
   1.727 -</para>
   1.728 -</listitem></itemizedlist>
   1.729 -
   1.730 -<para>The <literal role="rc-acl.allow">acl.allow</literal> section controls the users that are allowed to
   1.731 -add changesets to the repository.  If this section is not present, all
   1.732 -users that are not explicitly denied are allowed.  If this section is
   1.733 -present, all users that are not explicitly allowed are denied (so an
   1.734 -empty section means that all users are denied).
   1.735 -</para>
   1.736 -
   1.737 -<para>The <literal role="rc-acl.deny">acl.deny</literal> section determines which users are denied
   1.738 -from adding changesets to the repository.  If this section is not
   1.739 -present or is empty, no users are denied.
   1.740 -</para>
   1.741 -
   1.742 -<para>The syntaxes for the <literal role="rc-acl.allow">acl.allow</literal> and <literal role="rc-acl.deny">acl.deny</literal>
   1.743 -sections are identical.  On the left of each entry is a glob pattern
   1.744 -that matches files or directories, relative to the root of the
   1.745 -repository; on the right, a user name.
   1.746 -</para>
   1.747 -
   1.748 -<para>In the following example, the user <literal>docwriter</literal> can only push
   1.749 -changes to the <filename class="directory">docs</filename> subtree of the repository, while
   1.750 -<literal>intern</literal> can push changes to any file or directory except
   1.751 -<filename class="directory">source/sensitive</filename>.
   1.752 -</para>
   1.753 -<programlisting>
   1.754 -<para>  [acl.allow]
   1.755 -  docs/** = docwriter
   1.756 -</para>
   1.757 -
   1.758 -<para>  [acl.deny]
   1.759 -  source/sensitive/** = intern
   1.760 -</para>
   1.761 -</programlisting>
   1.762 -
   1.763 -</sect3>
   1.764 -<sect3>
   1.765 -<title>Testing and troubleshooting</title>
   1.766 -
   1.767 -<para>If you want to test the <literal role="hg-ext">acl</literal> hook, run it with Mercurial's
   1.768 -debugging output enabled.  Since you'll probably be running it on a
   1.769 -server where it's not convenient (or sometimes possible) to pass in
   1.770 -the <option role="hg-opt-global">--debug</option> option, don't forget that you can enable
   1.771 -debugging output in your <filename role="special"> /.hgrc</filename>:
   1.772 -</para>
   1.773 -<programlisting>
   1.774 -<para>  [ui]
   1.775 -  debug = true
   1.776 -</para>
   1.777 -</programlisting>
   1.778 -<para>With this enabled, the <literal role="hg-ext">acl</literal> hook will print enough information
   1.779 -to let you figure out why it is allowing or forbidding pushes from
   1.780 -specific users.
   1.781 -</para>
   1.782 -
   1.783 -</sect3>
   1.784 -</sect2>
   1.785 -<sect2>
   1.786 -<title><literal role="hg-ext">bugzilla</literal>&emdash;integration with Bugzilla</title>
   1.787 -
   1.788 -<para>The <literal role="hg-ext">bugzilla</literal> extension adds a comment to a Bugzilla bug
   1.789 -whenever it finds a reference to that bug ID in a commit comment.  You
   1.790 -can install this hook on a shared server, so that any time a remote
   1.791 -user pushes changes to this server, the hook gets run.
   1.792 -</para>
   1.793 -
   1.794 -<para>It adds a comment to the bug that looks like this (you can configure
   1.795 -the contents of the comment&emdash;see below):
   1.796 -</para>
   1.797 -<programlisting>
   1.798 -<para>  Changeset aad8b264143a, made by Joe User &lt;joe.user@domain.com&gt; in
   1.799 -  the frobnitz repository, refers to this bug.
   1.800 -</para>
   1.801 -
   1.802 -<para>  For complete details, see
   1.803 -  http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
   1.804 -</para>
   1.805 -
   1.806 -<para>  Changeset description:
   1.807 -        Fix bug 10483 by guarding against some NULL pointers
   1.808 -</para>
   1.809 -</programlisting>
   1.810 -<para>The value of this hook is that it automates the process of updating a
   1.811 -bug any time a changeset refers to it.  If you configure the hook
   1.812 -properly, it makes it easy for people to browse straight from a
   1.813 -Bugzilla bug to a changeset that refers to that bug.
   1.814 -</para>
   1.815 -
   1.816 -<para>You can use the code in this hook as a starting point for some more
   1.817 -exotic Bugzilla integration recipes.  Here are a few possibilities:
   1.818 -</para>
   1.819 -<itemizedlist>
   1.820 -<listitem><para>Require that every changeset pushed to the server have a valid
   1.821 -  bug ID in its commit comment.  In this case, you'd want to configure
   1.822 -  the hook as a <literal role="hook">pretxncommit</literal> hook.  This would allow the hook
   1.823 -  to reject changes that didn't contain bug IDs.
   1.824 -</para>
   1.825 -</listitem>
   1.826 -<listitem><para>Allow incoming changesets to automatically modify the
   1.827 -  <emphasis>state</emphasis> of a bug, as well as simply adding a comment.  For
   1.828 -  example, the hook could recognise the string <quote>fixed bug 31337</quote> as
   1.829 -  indicating that it should update the state of bug 31337 to
   1.830 -  <quote>requires testing</quote>.
   1.831 -</para>
   1.832 -</listitem></itemizedlist>
   1.833 -
   1.834 -<sect3>
   1.835 -<title>Configuring the <literal role="hook">bugzilla</literal> hook</title>
   1.836 -<para>\label{sec:hook:bugzilla:config}
   1.837 -</para>
   1.838 -
   1.839 -<para>You should configure this hook in your server's <filename role="special"> /.hgrc</filename>\ as an
   1.840 -<literal role="hook">incoming</literal> hook, for example as follows:
   1.841 -</para>
   1.842 -<programlisting>
   1.843 -<para>  [hooks]
   1.844 -  incoming.bugzilla = python:hgext.bugzilla.hook
   1.845 -</para>
   1.846 -</programlisting>
   1.847 -
   1.848 -<para>Because of the specialised nature of this hook, and because Bugzilla
   1.849 -was not written with this kind of integration in mind, configuring
   1.850 -this hook is a somewhat involved process.
   1.851 -</para>
   1.852 -
   1.853 -<para>Before you begin, you must install the MySQL bindings for Python on
   1.854 -the host(s) where you'll be running the hook.  If this is not
   1.855 -available as a binary package for your system, you can download it
   1.856 -from <citation>web:mysql-python</citation>.
   1.857 -</para>
   1.858 -
   1.859 -<para>Configuration information for this hook lives in the
   1.860 -<literal role="rc-bugzilla">bugzilla</literal> section of your <filename role="special"> /.hgrc</filename>.
   1.861 -</para>
   1.862 -<itemizedlist>
   1.863 -<listitem><para><envar role="rc-item-bugzilla">version</envar>: The version of Bugzilla installed on
   1.864 -  the server.  The database schema that Bugzilla uses changes
   1.865 -  occasionally, so this hook has to know exactly which schema to use.
   1.866 -  At the moment, the only version supported is <literal>2.16</literal>.
   1.867 -</para>
   1.868 -</listitem>
   1.869 -<listitem><para><envar role="rc-item-bugzilla">host</envar>: The hostname of the MySQL server that
   1.870 -  stores your Bugzilla data.  The database must be configured to allow
   1.871 -  connections from whatever host you are running the <literal role="hook">bugzilla</literal>
   1.872 -  hook on.
   1.873 -</para>
   1.874 -</listitem>
   1.875 -<listitem><para><envar role="rc-item-bugzilla">user</envar>: The username with which to connect to
   1.876 -  the MySQL server.  The database must be configured to allow this
   1.877 -  user to connect from whatever host you are running the
   1.878 -  <literal role="hook">bugzilla</literal> hook on.  This user must be able to access and
   1.879 -  modify Bugzilla tables.  The default value of this item is
   1.880 -  <literal>bugs</literal>, which is the standard name of the Bugzilla user in a
   1.881 -  MySQL database.
   1.882 -</para>
   1.883 -</listitem>
   1.884 -<listitem><para><envar role="rc-item-bugzilla">password</envar>: The MySQL password for the user you
   1.885 -  configured above.  This is stored as plain text, so you should make
   1.886 -  sure that unauthorised users cannot read the <filename role="special"> /.hgrc</filename>\ file where you
   1.887 -  store this information.
   1.888 -</para>
   1.889 -</listitem>
   1.890 -<listitem><para><envar role="rc-item-bugzilla">db</envar>: The name of the Bugzilla database on the
   1.891 -  MySQL server.  The default value of this item is <literal>bugs</literal>,
   1.892 -  which is the standard name of the MySQL database where Bugzilla
   1.893 -  stores its data.
   1.894 -</para>
   1.895 -</listitem>
   1.896 -<listitem><para><envar role="rc-item-bugzilla">notify</envar>: If you want Bugzilla to send out a
   1.897 -  notification email to subscribers after this hook has added a
   1.898 -  comment to a bug, you will need this hook to run a command whenever
   1.899 -  it updates the database.  The command to run depends on where you
   1.900 -  have installed Bugzilla, but it will typically look something like
   1.901 -  this, if you have Bugzilla installed in
   1.902 -  <filename class="directory">/var/www/html/bugzilla</filename>:
   1.903 -</para>
   1.904 -</listitem><programlisting>
   1.905 -<listitem><para>    cd /var/www/html/bugzilla &amp;&amp; ./processmail %s nobody@nowhere.com
   1.906 -</para>
   1.907 -</listitem></programlisting>
   1.908 -<listitem><para>  The Bugzilla <literal>processmail</literal> program expects to be given a
   1.909 -  bug ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID) and an
   1.910 -  email address.  It also expects to be able to write to some files in
   1.911 -  the directory that it runs in.  If Bugzilla and this hook are not
   1.912 -  installed on the same machine, you will need to find a way to run
   1.913 -  <literal>processmail</literal> on the server where Bugzilla is installed.
   1.914 -</para>
   1.915 -</listitem></itemizedlist>
   1.916 -
   1.917 -</sect3>
   1.918 -<sect3>
   1.919 -<title>Mapping committer names to Bugzilla user names</title>
   1.920 -
   1.921 -<para>By default, the <literal role="hg-ext">bugzilla</literal> hook tries to use the email address
   1.922 -of a changeset's committer as the Bugzilla user name with which to
   1.923 -update a bug.  If this does not suit your needs, you can map committer
   1.924 -email addresses to Bugzilla user names using a <literal role="rc-usermap">usermap</literal>
   1.925 -section.
   1.926 -</para>
   1.927 -
   1.928 -<para>Each item in the <literal role="rc-usermap">usermap</literal> section contains an email address
   1.929 -on the left, and a Bugzilla user name on the right.
   1.930 -</para>
   1.931 -<programlisting>
   1.932 -<para>  [usermap]
   1.933 -  jane.user@example.com = jane
   1.934 -</para>
   1.935 -</programlisting>
   1.936 -<para>You can either keep the <literal role="rc-usermap">usermap</literal> data in a normal <filename role="special"> /.hgrc</filename>, or
   1.937 -tell the <literal role="hg-ext">bugzilla</literal> hook to read the information from an
   1.938 -external <filename>usermap</filename> file.  In the latter case, you can store
   1.939 -<filename>usermap</filename> data by itself in (for example) a user-modifiable
   1.940 -repository.  This makes it possible to let your users maintain their
   1.941 -own <envar role="rc-item-bugzilla">usermap</envar> entries.  The main <filename role="special"> /.hgrc</filename>\ file might
   1.942 -look like this:
   1.943 -</para>
   1.944 -<programlisting>
   1.945 -<para>  # regular hgrc file refers to external usermap file
   1.946 -  [bugzilla]
   1.947 -  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
   1.948 -</para>
   1.949 -</programlisting>
   1.950 -<para>While the <filename>usermap</filename> file that it refers to might look like
   1.951 -this:
   1.952 -</para>
   1.953 -<programlisting>
   1.954 -<para>  # bugzilla-usermap.conf - inside a hg repository
   1.955 -  [usermap]
   1.956 -  stephanie@example.com = steph
   1.957 -</para>
   1.958 -</programlisting>
   1.959 -
   1.960 -</sect3>
   1.961 -<sect3>
   1.962 -<title>Configuring the text that gets added to a bug</title>
   1.963 -
   1.964 -<para>You can configure the text that this hook adds as a comment; you
   1.965 -specify it in the form of a Mercurial template.  Several <filename role="special"> /.hgrc</filename>\
   1.966 -entries (still in the <literal role="rc-bugzilla">bugzilla</literal> section) control this
   1.967 -behaviour.
   1.968 -</para>
   1.969 -<itemizedlist>
   1.970 -<listitem><para><literal>strip</literal>: The number of leading path elements to strip
   1.971 -  from a repository's path name to construct a partial path for a URL.
   1.972 -  For example, if the repositories on your server live under
   1.973 -  <filename class="directory">/home/hg/repos</filename>, and you have a repository whose path is
   1.974 -  <filename class="directory">/home/hg/repos/app/tests</filename>, then setting <literal>strip</literal> to
   1.975 -  <literal>4</literal> will give a partial path of <filename class="directory">app/tests</filename>.  The
   1.976 -  hook will make this partial path available when expanding a
   1.977 -  template, as <literal>webroot</literal>.
   1.978 -</para>
   1.979 -</listitem>
   1.980 -<listitem><para><literal>template</literal>: The text of the template to use.  In addition
   1.981 -  to the usual changeset-related variables, this template can use
   1.982 -  <literal>hgweb</literal> (the value of the <literal>hgweb</literal> configuration item
   1.983 -  above) and <literal>webroot</literal> (the path constructed using
   1.984 -  <literal>strip</literal> above).
   1.985 -</para>
   1.986 -</listitem></itemizedlist>
   1.987 -
   1.988 -<para>In addition, you can add a <envar role="rc-item-web">baseurl</envar> item to the
   1.989 -<literal role="rc-web">web</literal> section of your <filename role="special"> /.hgrc</filename>.  The <literal role="hg-ext">bugzilla</literal> hook will
   1.990 -make this available when expanding a template, as the base string to
   1.991 -use when constructing a URL that will let users browse from a Bugzilla
   1.992 -comment to view a changeset.  Example:
   1.993 -</para>
   1.994 -<programlisting>
   1.995 -<para>  [web]
   1.996 -  baseurl = http://hg.domain.com/
   1.997 -</para>
   1.998 -</programlisting>
   1.999 -
  1.1000 -<para>Here is an example set of <literal role="hg-ext">bugzilla</literal> hook config information.
  1.1001 -</para>
  1.1002 -<programlisting>
  1.1003 -<para>  [bugzilla]
  1.1004 -  host = bugzilla.example.com
  1.1005 -  password = mypassword
  1.1006 -  version = 2.16
  1.1007 -  # server-side repos live in /home/hg/repos, so strip 4 leading
  1.1008 -  # separators
  1.1009 -  strip = 4
  1.1010 -  hgweb = http://hg.example.com/
  1.1011 -  usermap = /home/hg/repos/notify/bugzilla.conf
  1.1012 -  template = Changeset {node|short}, made by {author} in the {webroot}
  1.1013 -    repo, refers to this bug.\\nFor complete details, see
  1.1014 -    {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset
  1.1015 -    description:\\n\\t{desc|tabindent}
  1.1016 -</para>
  1.1017 -</programlisting>
  1.1018 -
  1.1019 -</sect3>
  1.1020 -<sect3>
  1.1021 -<title>Testing and troubleshooting</title>
  1.1022 -
  1.1023 -<para>The most common problems with configuring the <literal role="hg-ext">bugzilla</literal> hook
  1.1024 -relate to running Bugzilla's <filename>processmail</filename> script and mapping
  1.1025 -committer names to user names.
  1.1026 -</para>
  1.1027 -
  1.1028 -<para>Recall from section <xref linkend="sec:hook:bugzilla:config"/> above that the user
  1.1029 -that runs the Mercurial process on the server is also the one that
  1.1030 -will run the <filename>processmail</filename> script.  The
  1.1031 -<filename>processmail</filename> script sometimes causes Bugzilla to write to
  1.1032 -files in its configuration directory, and Bugzilla's configuration
  1.1033 -files are usually owned by the user that your web server runs under.
  1.1034 -</para>
  1.1035 -
  1.1036 -<para>You can cause <filename>processmail</filename> to be run with the suitable
  1.1037 -user's identity using the <command>sudo</command> command.  Here is an example
  1.1038 -entry for a <filename>sudoers</filename> file.
  1.1039 -</para>
  1.1040 -<programlisting>
  1.1041 -<para>  hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
  1.1042 -</para>
  1.1043 -</programlisting>
  1.1044 -<para>This allows the <literal>hg_user</literal> user to run a
  1.1045 -<filename>processmail-wrapper</filename> program under the identity of
  1.1046 -<literal>httpd_user</literal>.
  1.1047 -</para>
  1.1048 -
  1.1049 -<para>This indirection through a wrapper script is necessary, because
  1.1050 -<filename>processmail</filename> expects to be run with its current directory
  1.1051 -set to wherever you installed Bugzilla; you can't specify that kind of
  1.1052 -constraint in a <filename>sudoers</filename> file.  The contents of the wrapper
  1.1053 -script are simple:
  1.1054 -</para>
  1.1055 -<programlisting>
  1.1056 -<para>  #!/bin/sh
  1.1057 -  cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com
  1.1058 -</para>
  1.1059 -</programlisting>
  1.1060 -<para>It doesn't seem to matter what email address you pass to
  1.1061 -<filename>processmail</filename>.
  1.1062 -</para>
  1.1063 -
  1.1064 -<para>If your <literal role="rc-usermap">usermap</literal> is not set up correctly, users will see an
  1.1065 -error message from the <literal role="hg-ext">bugzilla</literal> hook when they push changes
  1.1066 -to the server.  The error message will look like this:
  1.1067 -</para>
  1.1068 -<programlisting>
  1.1069 -<para>  cannot find bugzilla user id for john.q.public@example.com
  1.1070 -</para>
  1.1071 -</programlisting>
  1.1072 -<para>What this means is that the committer's address,
  1.1073 -<literal>john.q.public@example.com</literal>, is not a valid Bugzilla user name,
  1.1074 -nor does it have an entry in your <literal role="rc-usermap">usermap</literal> that maps it to
  1.1075 -a valid Bugzilla user name.
  1.1076 -</para>
  1.1077 -
  1.1078 -</sect3>
  1.1079 -</sect2>
  1.1080 -<sect2>
  1.1081 -<title><literal role="hg-ext">notify</literal>&emdash;send email notifications</title>
  1.1082 -
  1.1083 -<para>Although Mercurial's built-in web server provides RSS feeds of changes
  1.1084 -in every repository, many people prefer to receive change
  1.1085 -notifications via email.  The <literal role="hg-ext">notify</literal> hook lets you send out
  1.1086 -notifications to a set of email addresses whenever changesets arrive
  1.1087 -that those subscribers are interested in.
  1.1088 -</para>
  1.1089 -
  1.1090 -<para>As with the <literal role="hg-ext">bugzilla</literal> hook, the <literal role="hg-ext">notify</literal> hook is
  1.1091 -template-driven, so you can customise the contents of the notification
  1.1092 -messages that it sends.
  1.1093 -</para>
  1.1094 -
  1.1095 -<para>By default, the <literal role="hg-ext">notify</literal> hook includes a diff of every changeset
  1.1096 -that it sends out; you can limit the size of the diff, or turn this
  1.1097 -feature off entirely.  It is useful for letting subscribers review
  1.1098 -changes immediately, rather than clicking to follow a URL.
  1.1099 -</para>
  1.1100 -
  1.1101 -<sect3>
  1.1102 -<title>Configuring the <literal role="hg-ext">notify</literal> hook</title>
  1.1103 -
  1.1104 -<para>You can set up the <literal role="hg-ext">notify</literal> hook to send one email message per
  1.1105 -incoming changeset, or one per incoming group of changesets (all those
  1.1106 -that arrived in a single pull or push).
  1.1107 -</para>
  1.1108 -<programlisting>
  1.1109 -<para>  [hooks]
  1.1110 -  # send one email per group of changes
  1.1111 -  changegroup.notify = python:hgext.notify.hook
  1.1112 -  # send one email per change
  1.1113 -  incoming.notify = python:hgext.notify.hook
  1.1114 -</para>
  1.1115 -</programlisting>
  1.1116 -
  1.1117 -<para>Configuration information for this hook lives in the
  1.1118 -<literal role="rc-notify">notify</literal> section of a <filename role="special"> /.hgrc</filename>\ file.
  1.1119 -</para>
  1.1120 -<itemizedlist>
  1.1121 -<listitem><para><envar role="rc-item-notify">test</envar>: By default, this hook does not send out
  1.1122 -  email at all; instead, it prints the message that it <emphasis>would</emphasis>
  1.1123 -  send.  Set this item to <literal>false</literal> to allow email to be sent.
  1.1124 -  The reason that sending of email is turned off by default is that it
  1.1125 -  takes several tries to configure this extension exactly as you would
  1.1126 -  like, and it would be bad form to spam subscribers with a number of
  1.1127 -  <quote>broken</quote> notifications while you debug your configuration.
  1.1128 -</para>
  1.1129 -</listitem>
  1.1130 -<listitem><para><envar role="rc-item-notify">config</envar>: The path to a configuration file that
  1.1131 -  contains subscription information.  This is kept separate from the
  1.1132 -  main <filename role="special"> /.hgrc</filename>\ so that you can maintain it in a repository of its own.
  1.1133 -  People can then clone that repository, update their subscriptions,
  1.1134 -  and push the changes back to your server.
  1.1135 -</para>
  1.1136 -</listitem>
  1.1137 -<listitem><para><envar role="rc-item-notify">strip</envar>: The number of leading path separator
  1.1138 -  characters to strip from a repository's path, when deciding whether
  1.1139 -  a repository has subscribers.  For example, if the repositories on
  1.1140 -  your server live in <filename class="directory">/home/hg/repos</filename>, and <literal role="hg-ext">notify</literal> is
  1.1141 -  considering a repository named <filename class="directory">/home/hg/repos/shared/test</filename>,
  1.1142 -  setting <envar role="rc-item-notify">strip</envar> to <literal>4</literal> will cause
  1.1143 -  <literal role="hg-ext">notify</literal> to trim the path it considers down to
  1.1144 -  <filename class="directory">shared/test</filename>, and it will match subscribers against that.
  1.1145 -</para>
  1.1146 -</listitem>
  1.1147 -<listitem><para><envar role="rc-item-notify">template</envar>: The template text to use when sending
  1.1148 -  messages.  This specifies both the contents of the message header
  1.1149 -  and its body.
  1.1150 -</para>
  1.1151 -</listitem>
  1.1152 -<listitem><para><envar role="rc-item-notify">maxdiff</envar>: The maximum number of lines of diff
  1.1153 -  data to append to the end of a message.  If a diff is longer than
  1.1154 -  this, it is truncated.  By default, this is set to 300.  Set this to
  1.1155 -  <literal>0</literal> to omit diffs from notification emails.
  1.1156 -</para>
  1.1157 -</listitem>
  1.1158 -<listitem><para><envar role="rc-item-notify">sources</envar>: A list of sources of changesets to
  1.1159 -  consider.  This lets you limit <literal role="hg-ext">notify</literal> to only sending out
  1.1160 -  email about changes that remote users pushed into this repository
  1.1161 -  via a server, for example.  See section <xref linkend="sec:hook:sources"/> for
  1.1162 -  the sources you can specify here.
  1.1163 -</para>
  1.1164 -</listitem></itemizedlist>
  1.1165 -
  1.1166 -<para>If you set the <envar role="rc-item-web">baseurl</envar> item in the <literal role="rc-web">web</literal>
  1.1167 -section, you can use it in a template; it will be available as
  1.1168 -<literal>webroot</literal>.
  1.1169 -</para>
  1.1170 -
  1.1171 -<para>Here is an example set of <literal role="hg-ext">notify</literal> configuration information.
  1.1172 -</para>
  1.1173 -<programlisting>
  1.1174 -<para>  [notify]
  1.1175 -  # really send email
  1.1176 -  test = false
  1.1177 -  # subscriber data lives in the notify repo
  1.1178 -  config = /home/hg/repos/notify/notify.conf
  1.1179 -  # repos live in /home/hg/repos on server, so strip 4 "/" chars
  1.1180 -  strip = 4
  1.1181 -  template = X-Hg-Repo: {webroot}
  1.1182 -    Subject: {webroot}: {desc|firstline|strip}
  1.1183 -    From: {author}
  1.1184 -</para>
  1.1185 -
  1.1186 -<para>    changeset {node|short} in {root}
  1.1187 -    details: {baseurl}{webroot}?cmd=changeset;node={node|short}
  1.1188 -    description:
  1.1189 -      {desc|tabindent|strip}
  1.1190 -</para>
  1.1191 -
  1.1192 -<para>  [web]
  1.1193 -  baseurl = http://hg.example.com/
  1.1194 -</para>
  1.1195 -</programlisting>
  1.1196 -
  1.1197 -<para>This will produce a message that looks like the following:
  1.1198 -</para>
  1.1199 -<programlisting>
  1.1200 -<para>  X-Hg-Repo: tests/slave
  1.1201 -  Subject: tests/slave: Handle error case when slave has no buffers
  1.1202 -  Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
  1.1203 -</para>
  1.1204 -
  1.1205 -<para>  changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
  1.1206 -  details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
  1.1207 -  description:
  1.1208 -          Handle error case when slave has no buffers
  1.1209 -  diffs (54 lines):
  1.1210 -</para>
  1.1211 -
  1.1212 -<para>  diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
  1.1213 -  &emdash; a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
  1.1214 -  +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
  1.1215 -  @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
  1.1216 -  [...snip...]
  1.1217 -</para>
  1.1218 -</programlisting>
  1.1219 -
  1.1220 -</sect3>
  1.1221 -<sect3>
  1.1222 -<title>Testing and troubleshooting</title>
  1.1223 -
  1.1224 -<para>Do not forget that by default, the <literal role="hg-ext">notify</literal> extension \emph{will
  1.1225 -  not send any mail} until you explicitly configure it to do so, by
  1.1226 -setting <envar role="rc-item-notify">test</envar> to <literal>false</literal>.  Until you do that,
  1.1227 -it simply prints the message it <emphasis>would</emphasis> send.
  1.1228 -</para>
  1.1229 -
  1.1230 -</sect3>
  1.1231 -</sect2>
  1.1232 -</sect1>
  1.1233 -<sect1>
  1.1234 -<title>Information for writers of hooks</title>
  1.1235 -<para>\label{sec:hook:ref}
  1.1236 -</para>
  1.1237 -
  1.1238 -<sect2>
  1.1239 -<title>In-process hook execution</title>
  1.1240 -
  1.1241 -<para>An in-process hook is called with arguments of the following form:
  1.1242 -</para>
  1.1243 -<programlisting>
  1.1244 -<para>  def myhook(ui, repo, **kwargs):
  1.1245 -      pass
  1.1246 -</para>
  1.1247 -</programlisting>
  1.1248 -<para>The <literal>ui</literal> parameter is a <literal role="py-mod-mercurial.ui">ui</literal> object.
  1.1249 -The <literal>repo</literal> parameter is a
  1.1250 -<literal role="py-mod-mercurial.localrepo">localrepository</literal> object.  The
  1.1251 -names and values of the <literal>**kwargs</literal> parameters depend on the
  1.1252 -hook being invoked, with the following common features:
  1.1253 -</para>
  1.1254 -<itemizedlist>
  1.1255 -<listitem><para>If a parameter is named <literal>node</literal> or
  1.1256 -  <literal>parent<emphasis>N</emphasis></literal>, it will contain a hexadecimal changeset ID.
  1.1257 -  The empty string is used to represent <quote>null changeset ID</quote> instead
  1.1258 -  of a string of zeroes.
  1.1259 -</para>
  1.1260 -</listitem>
  1.1261 -<listitem><para>If a parameter is named <literal>url</literal>, it will contain the URL of
  1.1262 -  a remote repository, if that can be determined.
  1.1263 -</para>
  1.1264 -</listitem>
  1.1265 -<listitem><para>Boolean-valued parameters are represented as Python
  1.1266 -  <literal>bool</literal> objects.
  1.1267 -</para>
  1.1268 -</listitem></itemizedlist>
  1.1269 -
  1.1270 -<para>An in-process hook is called without a change to the process's working
  1.1271 -directory (unlike external hooks, which are run in the root of the
  1.1272 -repository).  It must not change the process's working directory, or
  1.1273 -it will cause any calls it makes into the Mercurial API to fail.
  1.1274 -</para>
  1.1275 -
  1.1276 -<para>If a hook returns a boolean <quote>false</quote> value, it is considered to have
  1.1277 -succeeded.  If it returns a boolean <quote>true</quote> value or raises an
  1.1278 -exception, it is considered to have failed.  A useful way to think of
  1.1279 -the calling convention is <quote>tell me if you fail</quote>.
  1.1280 -</para>
  1.1281 -
  1.1282 -<para>Note that changeset IDs are passed into Python hooks as hexadecimal
  1.1283 -strings, not the binary hashes that Mercurial's APIs normally use.  To
  1.1284 -convert a hash from hex to binary, use the
  1.1285 -\pymodfunc{mercurial.node}{bin} function.
  1.1286 -</para>
  1.1287 -
  1.1288 -</sect2>
  1.1289 -<sect2>
  1.1290 -<title>External hook execution</title>
  1.1291 -
  1.1292 -<para>An external hook is passed to the shell of the user running Mercurial.
  1.1293 -Features of that shell, such as variable substitution and command
  1.1294 -redirection, are available.  The hook is run in the root directory of
  1.1295 -the repository (unlike in-process hooks, which are run in the same
  1.1296 -directory that Mercurial was run in).
  1.1297 -</para>
  1.1298 -
  1.1299 -<para>Hook parameters are passed to the hook as environment variables.  Each
  1.1300 -environment variable's name is converted in upper case and prefixed
  1.1301 -with the string <quote><literal>HG_</literal></quote>.  For example, if the name of a
  1.1302 -parameter is <quote><literal>node</literal></quote>, the name of the environment variable
  1.1303 -representing that parameter will be <quote><literal>HG_NODE</literal></quote>.
  1.1304 -</para>
  1.1305 -
  1.1306 -<para>A boolean parameter is represented as the string <quote><literal>1</literal></quote> for
  1.1307 -<quote>true</quote>, <quote><literal>0</literal></quote> for <quote>false</quote>.  If an environment variable is
  1.1308 -named <envar>HG_NODE</envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
  1.1309 -contains a changeset ID represented as a hexadecimal string.  The
  1.1310 -empty string is used to represent <quote>null changeset ID</quote> instead of a
  1.1311 -string of zeroes.  If an environment variable is named
  1.1312 -<envar>HG_URL</envar>, it will contain the URL of a remote repository, if
  1.1313 -that can be determined.
  1.1314 -</para>
  1.1315 -
  1.1316 -<para>If a hook exits with a status of zero, it is considered to have
  1.1317 -succeeded.  If it exits with a non-zero status, it is considered to
  1.1318 -have failed.
  1.1319 -</para>
  1.1320 -
  1.1321 -</sect2>
  1.1322 -<sect2>
  1.1323 -<title>Finding out where changesets come from</title>
  1.1324 -
  1.1325 -<para>A hook that involves the transfer of changesets between a local
  1.1326 -repository and another may be able to find out information about the
  1.1327 -<quote>far side</quote>.  Mercurial knows <emphasis>how</emphasis> changes are being
  1.1328 -transferred, and in many cases <emphasis>where</emphasis> they are being transferred
  1.1329 -to or from.
  1.1330 -</para>
  1.1331 -
  1.1332 -<sect3>
  1.1333 -<title>Sources of changesets</title>
  1.1334 -<para>\label{sec:hook:sources}
  1.1335 -</para>
  1.1336 -
  1.1337 -<para>Mercurial will tell a hook what means are, or were, used to transfer
  1.1338 -changesets between repositories.  This is provided by Mercurial in a
  1.1339 -Python parameter named <literal>source</literal>, or an environment variable named
  1.1340 -<envar>HG_SOURCE</envar>.
  1.1341 -</para>
  1.1342 -
  1.1343 -<itemizedlist>
  1.1344 -<listitem><para><literal>serve</literal>: Changesets are transferred to or from a remote
  1.1345 -  repository over http or ssh.
  1.1346 -</para>
  1.1347 -</listitem>
  1.1348 -<listitem><para><literal>pull</literal>: Changesets are being transferred via a pull from
  1.1349 -  one repository into another.
  1.1350 -</para>
  1.1351 -</listitem>
  1.1352 -<listitem><para><literal>push</literal>: Changesets are being transferred via a push from
  1.1353 -  one repository into another.
  1.1354 -</para>
  1.1355 -</listitem>
  1.1356 -<listitem><para><literal>bundle</literal>: Changesets are being transferred to or from a
  1.1357 -  bundle.
  1.1358 -</para>
  1.1359 -</listitem></itemizedlist>
  1.1360 -
  1.1361 -</sect3>
  1.1362 -<sect3>
  1.1363 -<title>Where changes are going&emdash;remote repository URLs</title>
  1.1364 -<para>\label{sec:hook:url}
  1.1365 -</para>
  1.1366 -
  1.1367 -<para>When possible, Mercurial will tell a hook the location of the <quote>far
  1.1368 -side</quote> of an activity that transfers changeset data between
  1.1369 -repositories.  This is provided by Mercurial in a Python parameter
  1.1370 -named <literal>url</literal>, or an environment variable named <envar>HG_URL</envar>.
  1.1371 -</para>
  1.1372 -
  1.1373 -<para>This information is not always known.  If a hook is invoked in a
  1.1374 -repository that is being served via http or ssh, Mercurial cannot tell
  1.1375 -where the remote repository is, but it may know where the client is
  1.1376 -connecting from.  In such cases, the URL will take one of the
  1.1377 -following forms:
  1.1378 -</para>
  1.1379 -<itemizedlist>
  1.1380 -<listitem><para><literal>remote:ssh:<emphasis>ip-address</emphasis></literal>&emdash;remote ssh client, at
  1.1381 -  the given IP address.
  1.1382 -</para>
  1.1383 -</listitem>
  1.1384 -<listitem><para><literal>remote:http:<emphasis>ip-address</emphasis></literal>&emdash;remote http client, at
  1.1385 -  the given IP address.  If the client is using SSL, this will be of
  1.1386 -  the form <literal>remote:https:<emphasis>ip-address</emphasis></literal>.
  1.1387 -</para>
  1.1388 -</listitem>
  1.1389 -<listitem><para>Empty&emdash;no information could be discovered about the remote
  1.1390 -  client.
  1.1391 -</para>
  1.1392 -</listitem></itemizedlist>
  1.1393 -
  1.1394 -</sect3>
  1.1395 -</sect2>
  1.1396 -</sect1>
  1.1397 -<sect1>
  1.1398 -<title>Hook reference</title>
  1.1399 -
  1.1400 -<sect2>
  1.1401 -<title><literal role="hook">changegroup</literal>&emdash;after remote changesets added</title>
  1.1402 -<para>\label{sec:hook:changegroup}
  1.1403 -</para>
  1.1404 -
  1.1405 -<para>This hook is run after a group of pre-existing changesets has been
  1.1406 -added to the repository, for example via a <command role="hg-cmd">hg pull</command> or
  1.1407 -<command role="hg-cmd">hg unbundle</command>.  This hook is run once per operation that added one
  1.1408 -or more changesets.  This is in contrast to the <literal role="hook">incoming</literal> hook,
  1.1409 -which is run once per changeset, regardless of whether the changesets
  1.1410 -arrive in a group.
  1.1411 -</para>
  1.1412 -
  1.1413 -<para>Some possible uses for this hook include kicking off an automated
  1.1414 -build or test of the added changesets, updating a bug database, or
  1.1415 -notifying subscribers that a repository contains new changes.
  1.1416 -</para>
  1.1417 -
  1.1418 -<para>Parameters to this hook:
  1.1419 -</para>
  1.1420 -<itemizedlist>
  1.1421 -<listitem><para><literal>node</literal>: A changeset ID.  The changeset ID of the first
  1.1422 -  changeset in the group that was added.  All changesets between this
  1.1423 -  and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by
  1.1424 -  a single <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg unbundle</command>.
  1.1425 -</para>
  1.1426 -</listitem>
  1.1427 -<listitem><para><literal>source</literal>: A string.  The source of these changes.  See
  1.1428 -  section <xref linkend="sec:hook:sources"/> for details.
  1.1429 -</para>
  1.1430 -</listitem>
  1.1431 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1432 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1433 -</para>
  1.1434 -</listitem></itemizedlist>
  1.1435 -
  1.1436 -<para>See also: <literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>),
  1.1437 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>),
  1.1438 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>)
  1.1439 -</para>
  1.1440 -
  1.1441 -</sect2>
  1.1442 -<sect2>
  1.1443 -<title><literal role="hook">commit</literal>&emdash;after a new changeset is created</title>
  1.1444 -<para>\label{sec:hook:commit}
  1.1445 -</para>
  1.1446 -
  1.1447 -<para>This hook is run after a new changeset has been created.
  1.1448 -</para>
  1.1449 -
  1.1450 -<para>Parameters to this hook:
  1.1451 -</para>
  1.1452 -<itemizedlist>
  1.1453 -<listitem><para><literal>node</literal>: A changeset ID.  The changeset ID of the newly
  1.1454 -  committed changeset.
  1.1455 -</para>
  1.1456 -</listitem>
  1.1457 -<listitem><para><literal>parent1</literal>: A changeset ID.  The changeset ID of the first
  1.1458 -  parent of the newly committed changeset.
  1.1459 -</para>
  1.1460 -</listitem>
  1.1461 -<listitem><para><literal>parent2</literal>: A changeset ID.  The changeset ID of the second
  1.1462 -  parent of the newly committed changeset.
  1.1463 -</para>
  1.1464 -</listitem></itemizedlist>
  1.1465 -
  1.1466 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>),
  1.1467 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>)
  1.1468 -</para>
  1.1469 -
  1.1470 -</sect2>
  1.1471 -<sect2>
  1.1472 -<title><literal role="hook">incoming</literal>&emdash;after one remote changeset is added</title>
  1.1473 -<para>\label{sec:hook:incoming}
  1.1474 -</para>
  1.1475 -
  1.1476 -<para>This hook is run after a pre-existing changeset has been added to the
  1.1477 -repository, for example via a <command role="hg-cmd">hg push</command>.  If a group of changesets
  1.1478 -was added in a single operation, this hook is called once for each
  1.1479 -added changeset.
  1.1480 -</para>
  1.1481 -
  1.1482 -<para>You can use this hook for the same purposes as the <literal role="hook">changegroup</literal>
  1.1483 -hook (section <xref linkend="sec:hook:changegroup"/>); it's simply more convenient
  1.1484 -sometimes to run a hook once per group of changesets, while other
  1.1485 -times it's handier once per changeset.
  1.1486 -</para>
  1.1487 -
  1.1488 -<para>Parameters to this hook:
  1.1489 -</para>
  1.1490 -<itemizedlist>
  1.1491 -<listitem><para><literal>node</literal>: A changeset ID.  The ID of the newly added
  1.1492 -  changeset.
  1.1493 -</para>
  1.1494 -</listitem>
  1.1495 -<listitem><para><literal>source</literal>: A string.  The source of these changes.  See
  1.1496 -  section <xref linkend="sec:hook:sources"/> for details.
  1.1497 -</para>
  1.1498 -</listitem>
  1.1499 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1500 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1501 -</para>
  1.1502 -</listitem></itemizedlist>
  1.1503 -
  1.1504 -<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"/>)
  1.1505 -</para>
  1.1506 -
  1.1507 -</sect2>
  1.1508 -<sect2>
  1.1509 -<title><literal role="hook">outgoing</literal>&emdash;after changesets are propagated</title>
  1.1510 -<para>\label{sec:hook:outgoing}
  1.1511 -</para>
  1.1512 -
  1.1513 -<para>This hook is run after a group of changesets has been propagated out
  1.1514 -of this repository, for example by a <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg bundle</command>
  1.1515 -command.
  1.1516 -</para>
  1.1517 -
  1.1518 -<para>One possible use for this hook is to notify administrators that
  1.1519 -changes have been pulled.
  1.1520 -</para>
  1.1521 -
  1.1522 -<para>Parameters to this hook:
  1.1523 -</para>
  1.1524 -<itemizedlist>
  1.1525 -<listitem><para><literal>node</literal>: A changeset ID.  The changeset ID of the first
  1.1526 -  changeset of the group that was sent.
  1.1527 -</para>
  1.1528 -</listitem>
  1.1529 -<listitem><para><literal>source</literal>: A string.  The source of the of the operation
  1.1530 -  (see section <xref linkend="sec:hook:sources"/>).  If a remote client pulled
  1.1531 -  changes from this repository, <literal>source</literal> will be
  1.1532 -  <literal>serve</literal>.  If the client that obtained changes from this
  1.1533 -  repository was local, <literal>source</literal> will be <literal>bundle</literal>,
  1.1534 -  <literal>pull</literal>, or <literal>push</literal>, depending on the operation the
  1.1535 -  client performed.
  1.1536 -</para>
  1.1537 -</listitem>
  1.1538 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1539 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1540 -</para>
  1.1541 -</listitem></itemizedlist>
  1.1542 -
  1.1543 -<para>See also: <literal role="hook">preoutgoing</literal> (section <xref linkend="sec:hook:preoutgoing"/>)
  1.1544 -</para>
  1.1545 -
  1.1546 -</sect2>
  1.1547 -<sect2>
  1.1548 -<title><literal role="hook">prechangegroup</literal>&emdash;before starting to add remote changesets</title>
  1.1549 -<para>\label{sec:hook:prechangegroup}
  1.1550 -</para>
  1.1551 -
  1.1552 -<para>This controlling hook is run before Mercurial begins to add a group of
  1.1553 -changesets from another repository.
  1.1554 -</para>
  1.1555 -
  1.1556 -<para>This hook does not have any information about the changesets to be
  1.1557 -added, because it is run before transmission of those changesets is
  1.1558 -allowed to begin.  If this hook fails, the changesets will not be
  1.1559 -transmitted.
  1.1560 -</para>
  1.1561 -
  1.1562 -<para>One use for this hook is to prevent external changes from being added
  1.1563 -to a repository.  For example, you could use this to <quote>freeze</quote> a
  1.1564 -server-hosted branch temporarily or permanently so that users cannot
  1.1565 -push to it, while still allowing a local administrator to modify the
  1.1566 -repository.
  1.1567 -</para>
  1.1568 -
  1.1569 -<para>Parameters to this hook:
  1.1570 -</para>
  1.1571 -<itemizedlist>
  1.1572 -<listitem><para><literal>source</literal>: A string.  The source of these changes.  See
  1.1573 -  section <xref linkend="sec:hook:sources"/> for details.
  1.1574 -</para>
  1.1575 -</listitem>
  1.1576 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1577 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1578 -</para>
  1.1579 -</listitem></itemizedlist>
  1.1580 -
  1.1581 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>),
  1.1582 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), ,
  1.1583 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>)
  1.1584 -</para>
  1.1585 -
  1.1586 -</sect2>
  1.1587 -<sect2>
  1.1588 -<title><literal role="hook">precommit</literal>&emdash;before starting to commit a changeset</title>
  1.1589 -<para>\label{sec:hook:precommit}
  1.1590 -</para>
  1.1591 -
  1.1592 -<para>This hook is run before Mercurial begins to commit a new changeset.
  1.1593 -It is run before Mercurial has any of the metadata for the commit,
  1.1594 -such as the files to be committed, the commit message, or the commit
  1.1595 -date.
  1.1596 -</para>
  1.1597 -
  1.1598 -<para>One use for this hook is to disable the ability to commit new
  1.1599 -changesets, while still allowing incoming changesets.  Another is to
  1.1600 -run a build or test, and only allow the commit to begin if the build
  1.1601 -or test succeeds.
  1.1602 -</para>
  1.1603 -
  1.1604 -<para>Parameters to this hook:
  1.1605 -</para>
  1.1606 -<itemizedlist>
  1.1607 -<listitem><para><literal>parent1</literal>: A changeset ID.  The changeset ID of the first
  1.1608 -  parent of the working directory.
  1.1609 -</para>
  1.1610 -</listitem>
  1.1611 -<listitem><para><literal>parent2</literal>: A changeset ID.  The changeset ID of the second
  1.1612 -  parent of the working directory.
  1.1613 -</para>
  1.1614 -</listitem></itemizedlist>
  1.1615 -<para>If the commit proceeds, the parents of the working directory will
  1.1616 -become the parents of the new changeset.
  1.1617 -</para>
  1.1618 -
  1.1619 -<para>See also: <literal role="hook">commit</literal> (section <xref linkend="sec:hook:commit"/>),
  1.1620 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>)
  1.1621 -</para>
  1.1622 -
  1.1623 -</sect2>
  1.1624 -<sect2>
  1.1625 -<title><literal role="hook">preoutgoing</literal>&emdash;before starting to propagate changesets</title>
  1.1626 -<para>\label{sec:hook:preoutgoing}
  1.1627 -</para>
  1.1628 -
  1.1629 -<para>This hook is invoked before Mercurial knows the identities of the
  1.1630 -changesets to be transmitted.
  1.1631 -</para>
  1.1632 -
  1.1633 -<para>One use for this hook is to prevent changes from being transmitted to
  1.1634 -another repository.
  1.1635 -</para>
  1.1636 -
  1.1637 -<para>Parameters to this hook:
  1.1638 -</para>
  1.1639 -<itemizedlist>
  1.1640 -<listitem><para><literal>source</literal>: A string.  The source of the operation that is
  1.1641 -  attempting to obtain changes from this repository (see
  1.1642 -  section <xref linkend="sec:hook:sources"/>).  See the documentation for the
  1.1643 -  <literal>source</literal> parameter to the <literal role="hook">outgoing</literal> hook, in
  1.1644 -  section <xref linkend="sec:hook:outgoing"/>, for possible values of this
  1.1645 -  parameter.
  1.1646 -</para>
  1.1647 -</listitem>
  1.1648 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1649 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1650 -</para>
  1.1651 -</listitem></itemizedlist>
  1.1652 -
  1.1653 -<para>See also: <literal role="hook">outgoing</literal> (section <xref linkend="sec:hook:outgoing"/>)
  1.1654 -</para>
  1.1655 -
  1.1656 -</sect2>
  1.1657 -<sect2>
  1.1658 -<title><literal role="hook">pretag</literal>&emdash;before tagging a changeset</title>
  1.1659 -<para>\label{sec:hook:pretag}
  1.1660 -</para>
  1.1661 -
  1.1662 -<para>This controlling hook is run before a tag is created.  If the hook
  1.1663 -succeeds, creation of the tag proceeds.  If the hook fails, the tag is
  1.1664 -not created.
  1.1665 -</para>
  1.1666 -
  1.1667 -<para>Parameters to this hook:
  1.1668 -</para>
  1.1669 -<itemizedlist>
  1.1670 -<listitem><para><literal>local</literal>: A boolean.  Whether the tag is local to this
  1.1671 -  repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or
  1.1672 -  managed by Mercurial (stored in <filename role="special">.hgtags</filename>).
  1.1673 -</para>
  1.1674 -</listitem>
  1.1675 -<listitem><para><literal>node</literal>: A changeset ID.  The ID of the changeset to be tagged.
  1.1676 -</para>
  1.1677 -</listitem>
  1.1678 -<listitem><para><literal>tag</literal>: A string.  The name of the tag to be created.
  1.1679 -</para>
  1.1680 -</listitem></itemizedlist>
  1.1681 -
  1.1682 -<para>If the tag to be created is revision-controlled, the <literal role="hook">precommit</literal>
  1.1683 -and <literal role="hook">pretxncommit</literal> hooks (sections <xref linkend="sec:hook:commit"/>
  1.1684 -and <xref linkend="sec:hook:pretxncommit"/>) will also be run.
  1.1685 -</para>
  1.1686 -
  1.1687 -<para>See also: <literal role="hook">tag</literal> (section <xref linkend="sec:hook:tag"/>)
  1.1688 -</para>
  1.1689 -
  1.1690 -<para>\subsection{<literal role="hook">pretxnchangegroup</literal>&emdash;before completing addition of
  1.1691 -  remote changesets}
  1.1692 -\label{sec:hook:pretxnchangegroup}
  1.1693 -</para>
  1.1694 -
  1.1695 -<para>This controlling hook is run before a transaction&emdash;that manages the
  1.1696 -addition of a group of new changesets from outside the
  1.1697 -repository&emdash;completes.  If the hook succeeds, the transaction
  1.1698 -completes, and all of the changesets become permanent within this
  1.1699 -repository.  If the hook fails, the transaction is rolled back, and
  1.1700 -the data for the changesets is erased.
  1.1701 -</para>
  1.1702 -
  1.1703 -<para>This hook can access the metadata associated with the almost-added
  1.1704 -changesets, but it should not do anything permanent with this data.
  1.1705 -It must also not modify the working directory.
  1.1706 -</para>
  1.1707 -
  1.1708 -<para>While this hook is running, if other Mercurial processes access this
  1.1709 -repository, they will be able to see the almost-added changesets as if
  1.1710 -they are permanent.  This may lead to race conditions if you do not
  1.1711 -take steps to avoid them.
  1.1712 -</para>
  1.1713 -
  1.1714 -<para>This hook can be used to automatically vet a group of changesets.  If
  1.1715 -the hook fails, all of the changesets are <quote>rejected</quote> when the
  1.1716 -transaction rolls back.
  1.1717 -</para>
  1.1718 -
  1.1719 -<para>Parameters to this hook:
  1.1720 -</para>
  1.1721 -<itemizedlist>
  1.1722 -<listitem><para><literal>node</literal>: A changeset ID.  The changeset ID of the first
  1.1723 -  changeset in the group that was added.  All changesets between this
  1.1724 -  and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by
  1.1725 -  a single <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg unbundle</command>.
  1.1726 -</para>
  1.1727 -</listitem>
  1.1728 -<listitem><para><literal>source</literal>: A string.  The source of these changes.  See
  1.1729 -  section <xref linkend="sec:hook:sources"/> for details.
  1.1730 -</para>
  1.1731 -</listitem>
  1.1732 -<listitem><para><literal>url</literal>: A URL.  The location of the remote repository, if
  1.1733 -  known.  See section <xref linkend="sec:hook:url"/> for more information.
  1.1734 -</para>
  1.1735 -</listitem></itemizedlist>
  1.1736 -
  1.1737 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>),
  1.1738 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>),
  1.1739 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>)
  1.1740 -</para>
  1.1741 -
  1.1742 -</sect2>
  1.1743 -<sect2>
  1.1744 -<title><literal role="hook">pretxncommit</literal>&emdash;before completing commit of new changeset</title>
  1.1745 -<para>\label{sec:hook:pretxncommit}
  1.1746 -</para>
  1.1747 -
  1.1748 -<para>This controlling hook is run before a transaction&emdash;that manages a new
  1.1749 -commit&emdash;completes.  If the hook succeeds, the transaction completes
  1.1750 -and the changeset becomes permanent within this repository.  If the
  1.1751 -hook fails, the transaction is rolled back, and the commit data is
  1.1752 -erased.
  1.1753 -</para>
  1.1754 -
  1.1755 -<para>This hook can access the metadata associated with the almost-new
  1.1756 -changeset, but it should not do anything permanent with this data.  It
  1.1757 -must also not modify the working directory.
  1.1758 -</para>
  1.1759 -
  1.1760 -<para>While this hook is running, if other Mercurial processes access this
  1.1761 -repository, they will be able to see the almost-new changeset as if it
  1.1762 -is permanent.  This may lead to race conditions if you do not take
  1.1763 -steps to avoid them.
  1.1764 -</para>
  1.1765 -
  1.1766 -<para>Parameters to this hook:
  1.1767 -</para>
  1.1768 -<itemizedlist>
  1.1769 -<listitem><para><literal>node</literal>: A changeset ID.  The changeset ID of the newly
  1.1770 -  committed changeset.
  1.1771 -</para>
  1.1772 -</listitem>
  1.1773 -<listitem><para><literal>parent1</literal>: A changeset ID.  The changeset ID of the first
  1.1774 -  parent of the newly committed changeset.
  1.1775 -</para>
  1.1776 -</listitem>
  1.1777 -<listitem><para><literal>parent2</literal>: A changeset ID.  The changeset ID of the second
  1.1778 -  parent of the newly committed changeset.
  1.1779 -</para>
  1.1780 -</listitem></itemizedlist>
  1.1781 -
  1.1782 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>)
  1.1783 -</para>
  1.1784 -
  1.1785 -</sect2>
  1.1786 -<sect2>
  1.1787 -<title><literal role="hook">preupdate</literal>&emdash;before updating or merging working directory</title>
  1.1788 -<para>\label{sec:hook:preupdate}
  1.1789 -</para>
  1.1790 -
  1.1791 -<para>This controlling hook is run before an update or merge of the working
  1.1792 -directory begins.  It is run only if Mercurial's normal pre-update
  1.1793 -checks determine that the update or merge can proceed.  If the hook
  1.1794 -succeeds, the update or merge may proceed; if it fails, the update or
  1.1795 -merge does not start.
  1.1796 -</para>
  1.1797 -
  1.1798 -<para>Parameters to this hook:
  1.1799 -</para>
  1.1800 -<itemizedlist>
  1.1801 -<listitem><para><literal>parent1</literal>: A changeset ID.  The ID of the parent that the
  1.1802 -  working directory is to be updated to.  If the working directory is
  1.1803 -  being merged, it will not change this parent.
  1.1804 -</para>
  1.1805 -</listitem>
  1.1806 -<listitem><para><literal>parent2</literal>: A changeset ID.  Only set if the working
  1.1807 -  directory is being merged.  The ID of the revision that the working
  1.1808 -  directory is being merged with.
  1.1809 -</para>
  1.1810 -</listitem></itemizedlist>
  1.1811 -
  1.1812 -<para>See also: <literal role="hook">update</literal> (section <xref linkend="sec:hook:update"/>)
  1.1813 -</para>
  1.1814 -
  1.1815 -</sect2>
  1.1816 -<sect2>
  1.1817 -<title><literal role="hook">tag</literal>&emdash;after tagging a changeset</title>
  1.1818 -<para>\label{sec:hook:tag}
  1.1819 -</para>
  1.1820 -
  1.1821 -<para>This hook is run after a tag has been created.
  1.1822 -</para>
  1.1823 -
  1.1824 -<para>Parameters to this hook:
  1.1825 -</para>
  1.1826 -<itemizedlist>
  1.1827 -<listitem><para><literal>local</literal>: A boolean.  Whether the new tag is local to this
  1.1828 -  repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or
  1.1829 -  managed by Mercurial (stored in <filename role="special">.hgtags</filename>).
  1.1830 -</para>
  1.1831 -</listitem>
  1.1832 -<listitem><para><literal>node</literal>: A changeset ID.  The ID of the changeset that was
  1.1833 -  tagged.
  1.1834 -</para>
  1.1835 -</listitem>
  1.1836 -<listitem><para><literal>tag</literal>: A string.  The name of the tag that was created.
  1.1837 -</para>
  1.1838 -</listitem></itemizedlist>
  1.1839 -
  1.1840 -<para>If the created tag is revision-controlled, the <literal role="hook">commit</literal> hook
  1.1841 -(section <xref linkend="sec:hook:commit"/>) is run before this hook.
  1.1842 -</para>
  1.1843 -
  1.1844 -<para>See also: <literal role="hook">pretag</literal> (section <xref linkend="sec:hook:pretag"/>)
  1.1845 -</para>
  1.1846 -
  1.1847 -</sect2>
  1.1848 -<sect2>
  1.1849 -<title><literal role="hook">update</literal>&emdash;after updating or merging working directory</title>
  1.1850 -<para>\label{sec:hook:update}
  1.1851 -</para>
  1.1852 -
  1.1853 -<para>This hook is run after an update or merge of the working directory
  1.1854 -completes.  Since a merge can fail (if the external <command>hgmerge</command>
  1.1855 -command fails to resolve conflicts in a file), this hook communicates
  1.1856 -whether the update or merge completed cleanly.
  1.1857 -</para>
  1.1858 -
  1.1859 -<itemizedlist>
  1.1860 -<listitem><para><literal>error</literal>: A boolean.  Indicates whether the update or
  1.1861 -  merge completed successfully.
  1.1862 -</para>
  1.1863 -</listitem>
  1.1864 -<listitem><para><literal>parent1</literal>: A changeset ID.  The ID of the parent that the
  1.1865 -  working directory was updated to.  If the working directory was
  1.1866 -  merged, it will not have changed this parent.
  1.1867 -</para>
  1.1868 -</listitem>
  1.1869 -<listitem><para><literal>parent2</literal>: A changeset ID.  Only set if the working
  1.1870 -  directory was merged.  The ID of the revision that the working
  1.1871 -  directory was merged with.
  1.1872 -</para>
  1.1873 -</listitem></itemizedlist>
  1.1874 -
  1.1875 -<para>See also: <literal role="hook">preupdate</literal> (section <xref linkend="sec:hook:preupdate"/>)
  1.1876 -</para>
  1.1877 -
  1.1878 -</sect2>
  1.1879 -</sect1>
  1.1880 +<chapter id="chap:hook">
  1.1881 +  <?dbhtml filename="handling-repository-events-with-hooks.html"?>
  1.1882 +  <title>Handling repository events with hooks</title>
  1.1883 +
  1.1884 +  <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
  1.1885 +    automated actions in response to events that occur in a
  1.1886 +    repository.  In some cases, you can even control Mercurial's
  1.1887 +    response to those events.</para>
  1.1888 +
  1.1889 +  <para id="x_1e7">The name Mercurial uses for one of these actions is a
  1.1890 +    <emphasis>hook</emphasis>. Hooks are called
  1.1891 +    <quote>triggers</quote> in some revision control systems, but the
  1.1892 +    two names refer to the same idea.</para>
  1.1893 +
  1.1894 +  <sect1>
  1.1895 +    <title>An overview of hooks in Mercurial</title>
  1.1896 +
  1.1897 +    <para id="x_1e8">Here is a brief list of the hooks that Mercurial
  1.1898 +      supports. We will revisit each of these hooks in more detail
  1.1899 +      later, in <xref linkend="sec:hook:ref"/>.</para>
  1.1900 +
  1.1901 +    <para id="x_1f6">Each of the hooks whose description begins with the word
  1.1902 +      <quote>Controlling</quote> has the ability to determine whether
  1.1903 +      an activity can proceed.  If the hook succeeds, the activity may
  1.1904 +      proceed; if it fails, the activity is either not permitted or
  1.1905 +      undone, depending on the hook.</para>
  1.1906 +
  1.1907 +    <itemizedlist>
  1.1908 +      <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This
  1.1909 +	  is run after a group of changesets has been brought into the
  1.1910 +	  repository from elsewhere.</para>
  1.1911 +      </listitem>
  1.1912 +      <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is
  1.1913 +	  run after a new changeset has been created in the local
  1.1914 +	  repository.</para>
  1.1915 +      </listitem>
  1.1916 +      <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is
  1.1917 +	  run once for each new changeset that is brought into the
  1.1918 +	  repository from elsewhere.  Notice the difference from
  1.1919 +	  <literal role="hook">changegroup</literal>, which is run
  1.1920 +	  once per <emphasis>group</emphasis> of changesets brought
  1.1921 +	  in.</para>
  1.1922 +      </listitem>
  1.1923 +      <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is
  1.1924 +	  run after a group of changesets has been transmitted from
  1.1925 +	  this repository.</para>
  1.1926 +      </listitem>
  1.1927 +      <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>:
  1.1928 +	  This is run before starting to bring a group of changesets
  1.1929 +	  into the repository.
  1.1930 +	</para>
  1.1931 +      </listitem>
  1.1932 +      <listitem><para id="x_1ee"><literal role="hook">precommit</literal>:
  1.1933 +	  Controlling. This is run before starting a commit.
  1.1934 +	</para>
  1.1935 +      </listitem>
  1.1936 +      <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>:
  1.1937 +	  Controlling. This is run before starting to transmit a group
  1.1938 +	  of changesets from this repository.
  1.1939 +	</para>
  1.1940 +      </listitem>
  1.1941 +      <listitem><para id="x_1f0"><literal role="hook">pretag</literal>:
  1.1942 +	  Controlling. This is run before creating a tag.
  1.1943 +	</para>
  1.1944 +      </listitem>
  1.1945 +      <listitem><para id="x_1f1"><literal
  1.1946 +	    role="hook">pretxnchangegroup</literal>: Controlling. This
  1.1947 +	  is run after a group of changesets has been brought into the
  1.1948 +	  local repository from another, but before the transaction
  1.1949 +	  completes that will make the changes permanent in the
  1.1950 +	  repository.
  1.1951 +	</para>
  1.1952 +      </listitem>
  1.1953 +      <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>:
  1.1954 +	  Controlling. This is run after a new changeset has been
  1.1955 +	  created in the local repository, but before the transaction
  1.1956 +	  completes that will make it permanent.
  1.1957 +	</para>
  1.1958 +      </listitem>
  1.1959 +      <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>:
  1.1960 +	  Controlling. This is run before starting an update or merge
  1.1961 +	  of the working directory.
  1.1962 +	</para>
  1.1963 +      </listitem>
  1.1964 +      <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run
  1.1965 +	  after a tag is created.
  1.1966 +	</para>
  1.1967 +      </listitem>
  1.1968 +      <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is
  1.1969 +	  run after an update or merge of the working directory has
  1.1970 +	  finished.
  1.1971 +	</para>
  1.1972 +      </listitem></itemizedlist>
  1.1973 +
  1.1974 +  </sect1>
  1.1975 +  <sect1>
  1.1976 +    <title>Hooks and security</title>
  1.1977 +
  1.1978 +    <sect2>
  1.1979 +      <title>Hooks are run with your privileges</title>
  1.1980 +
  1.1981 +      <para id="x_1f7">When you run a Mercurial command in a repository, and the
  1.1982 +	command causes a hook to run, that hook runs on
  1.1983 +	<emphasis>your</emphasis> system, under
  1.1984 +	<emphasis>your</emphasis> user account, with
  1.1985 +	<emphasis>your</emphasis> privilege level.  Since hooks are
  1.1986 +	arbitrary pieces of executable code, you should treat them
  1.1987 +	with an appropriate level of suspicion.  Do not install a hook
  1.1988 +	unless you are confident that you know who created it and what
  1.1989 +	it does.
  1.1990 +      </para>
  1.1991 +
  1.1992 +      <para id="x_1f8">In some cases, you may be exposed to hooks that you did
  1.1993 +	not install yourself.  If you work with Mercurial on an
  1.1994 +	unfamiliar system, Mercurial will run hooks defined in that
  1.1995 +	system's global <filename role="special">~/.hgrc</filename>
  1.1996 +	file.
  1.1997 +      </para>
  1.1998 +
  1.1999 +      <para id="x_1f9">If you are working with a repository owned by another
  1.2000 +	user, Mercurial can run hooks defined in that user's
  1.2001 +	repository, but it will still run them as <quote>you</quote>.
  1.2002 +	For example, if you <command role="hg-cmd">hg pull</command>
  1.2003 +	from that repository, and its <filename
  1.2004 +	  role="special">.hg/hgrc</filename> defines a local <literal
  1.2005 +	  role="hook">outgoing</literal> hook, that hook will run
  1.2006 +	under your user account, even though you don't own that
  1.2007 +	repository.
  1.2008 +      </para>
  1.2009 +
  1.2010 +      <note>
  1.2011 +	<para id="x_1fa">  This only applies if you are pulling from a repository
  1.2012 +	  on a local or network filesystem.  If you're pulling over
  1.2013 +	  http or ssh, any <literal role="hook">outgoing</literal>
  1.2014 +	  hook will run under whatever account is executing the server
  1.2015 +	  process, on the server.
  1.2016 +	</para>
  1.2017 +      </note>
  1.2018 +
  1.2019 +      <para id="x_1fb">To see what hooks are defined in a repository,
  1.2020 +	use the <command role="hg-cmd">hg showconfig hooks</command>
  1.2021 +	command.  If you are working in one repository, but talking to
  1.2022 +	another that you do not own (e.g. using <command
  1.2023 +	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
  1.2024 +	  incoming</command>), remember that it is the other
  1.2025 +	repository's hooks you should be checking, not your own.
  1.2026 +      </para>
  1.2027 +    </sect2>
  1.2028 +
  1.2029 +    <sect2>
  1.2030 +      <title>Hooks do not propagate</title>
  1.2031 +
  1.2032 +      <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
  1.2033 +	not propagate when you clone, or pull from, a repository.  The
  1.2034 +	reason for this is simple: a hook is a completely arbitrary
  1.2035 +	piece of executable code.  It runs under your user identity,
  1.2036 +	with your privilege level, on your machine.
  1.2037 +      </para>
  1.2038 +
  1.2039 +      <para id="x_1fd">It would be extremely reckless for any distributed
  1.2040 +	revision control system to implement revision-controlled
  1.2041 +	hooks, as this would offer an easily exploitable way to
  1.2042 +	subvert the accounts of users of the revision control system.
  1.2043 +      </para>
  1.2044 +
  1.2045 +      <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
  1.2046 +	collaborating with other people on a common project, you
  1.2047 +	should not assume that they are using the same Mercurial hooks
  1.2048 +	as you are, or that theirs are correctly configured.  You
  1.2049 +	should document the hooks you expect people to use.
  1.2050 +      </para>
  1.2051 +
  1.2052 +      <para id="x_1ff">In a corporate intranet, this is somewhat easier to
  1.2053 +	control, as you can for example provide a
  1.2054 +	<quote>standard</quote> installation of Mercurial on an NFS
  1.2055 +	filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will
  1.2056 +	see.  However, this too has its limits; see below.
  1.2057 +      </para>
  1.2058 +    </sect2>
  1.2059 +
  1.2060 +    <sect2>
  1.2061 +      <title>Hooks can be overridden</title>
  1.2062 +
  1.2063 +      <para id="x_200">Mercurial allows you to override a hook definition by
  1.2064 +	redefining the hook.  You can disable it by setting its value
  1.2065 +	to the empty string, or change its behavior as you wish.
  1.2066 +      </para>
  1.2067 +
  1.2068 +      <para id="x_201">If you deploy a system- or site-wide <filename
  1.2069 +	  role="special">~/.hgrc</filename> file that defines some
  1.2070 +	hooks, you should thus understand that your users can disable
  1.2071 +	or override those hooks.
  1.2072 +      </para>
  1.2073 +    </sect2>
  1.2074 +
  1.2075 +    <sect2>
  1.2076 +      <title>Ensuring that critical hooks are run</title>
  1.2077 +
  1.2078 +      <para id="x_202">Sometimes you may want to enforce a policy that you do not
  1.2079 +	want others to be able to work around.  For example, you may
  1.2080 +	have a requirement that every changeset must pass a rigorous
  1.2081 +	set of tests.  Defining this requirement via a hook in a
  1.2082 +	site-wide <filename role="special">~/.hgrc</filename> won't
  1.2083 +	work for remote users on laptops, and of course local users
  1.2084 +	can subvert it at will by overriding the hook.
  1.2085 +      </para>
  1.2086 +
  1.2087 +      <para id="x_203">Instead, you can set up your policies for use of Mercurial
  1.2088 +	so that people are expected to propagate changes through a
  1.2089 +	well-known <quote>canonical</quote> server that you have
  1.2090 +	locked down and configured appropriately.
  1.2091 +      </para>
  1.2092 +
  1.2093 +      <para id="x_204">One way to do this is via a combination of social
  1.2094 +	engineering and technology.  Set up a restricted-access
  1.2095 +	account; users can push changes over the network to
  1.2096 +	repositories managed by this account, but they cannot log into
  1.2097 +	the account and run normal shell commands.  In this scenario,
  1.2098 +	a user can commit a changeset that contains any old garbage
  1.2099 +	they want.
  1.2100 +      </para>
  1.2101 +
  1.2102 +      <para id="x_205">When someone pushes a changeset to the server that
  1.2103 +	everyone pulls from, the server will test the changeset before
  1.2104 +	it accepts it as permanent, and reject it if it fails to pass
  1.2105 +	the test suite.  If people only pull changes from this
  1.2106 +	filtering server, it will serve to ensure that all changes
  1.2107 +	that people pull have been automatically vetted.
  1.2108 +      </para>
  1.2109 +
  1.2110 +    </sect2>
  1.2111 +  </sect1>
  1.2112 +
  1.2113 +  <sect1 id="sec:hook:simple">
  1.2114 +    <title>A short tutorial on using hooks</title>
  1.2115 +
  1.2116 +    <para id="x_212">It is easy to write a Mercurial hook.  Let's start with a
  1.2117 +      hook that runs when you finish a <command role="hg-cmd">hg
  1.2118 +	commit</command>, and simply prints the hash of the changeset
  1.2119 +      you just created.  The hook is called <literal
  1.2120 +	role="hook">commit</literal>.
  1.2121 +    </para>
  1.2122 +
  1.2123 +    <para id="x_213">All hooks follow the pattern in this example.</para>
  1.2124 +
  1.2125 +&interaction.hook.simple.init;
  1.2126 +
  1.2127 +    <para id="x_214">You add an entry to the <literal
  1.2128 +	role="rc-hooks">hooks</literal> section of your <filename
  1.2129 +	role="special">~/.hgrc</filename>.  On the left is the name of
  1.2130 +      the event to trigger on; on the right is the action to take.  As
  1.2131 +      you can see, you can run an arbitrary shell command in a hook.
  1.2132 +      Mercurial passes extra information to the hook using environment
  1.2133 +      variables (look for <envar>HG_NODE</envar> in the example).
  1.2134 +    </para>
  1.2135 +
  1.2136 +    <sect2>
  1.2137 +      <title>Performing multiple actions per event</title>
  1.2138 +
  1.2139 +      <para id="x_215">Quite often, you will want to define more than one hook
  1.2140 +	for a particular kind of event, as shown below.</para>
  1.2141 +
  1.2142 +&interaction.hook.simple.ext;
  1.2143 +
  1.2144 +      <para id="x_216">Mercurial lets you do this by adding an
  1.2145 +	<emphasis>extension</emphasis> to the end of a hook's name.
  1.2146 +	You extend a hook's name by giving the name of the hook,
  1.2147 +	followed by a full stop (the
  1.2148 +	<quote><literal>.</literal></quote> character), followed by
  1.2149 +	some more text of your choosing.  For example, Mercurial will
  1.2150 +	run both <literal>commit.foo</literal> and
  1.2151 +	<literal>commit.bar</literal> when the
  1.2152 +	<literal>commit</literal> event occurs.
  1.2153 +      </para>
  1.2154 +
  1.2155 +      <para id="x_217">To give a well-defined order of execution when there are
  1.2156 +	multiple hooks defined for an event, Mercurial sorts hooks by
  1.2157 +	extension, and executes the hook commands in this sorted
  1.2158 +	order.  In the above example, it will execute
  1.2159 +	<literal>commit.bar</literal> before
  1.2160 +	<literal>commit.foo</literal>, and <literal>commit</literal>
  1.2161 +	before both.
  1.2162 +      </para>
  1.2163 +
  1.2164 +      <para id="x_218">It is a good idea to use a somewhat descriptive
  1.2165 +	extension when you define a new hook.  This will help you to
  1.2166 +	remember what the hook was for.  If the hook fails, you'll get
  1.2167 +	an error message that contains the hook name and extension, so
  1.2168 +	using a descriptive extension could give you an immediate hint
  1.2169 +	as to why the hook failed (see <xref
  1.2170 +	  linkend="sec:hook:perm"/> for an example).
  1.2171 +      </para>
  1.2172 +
  1.2173 +    </sect2>
  1.2174 +    <sect2 id="sec:hook:perm">
  1.2175 +      <title>Controlling whether an activity can proceed</title>
  1.2176 +
  1.2177 +      <para id="x_219">In our earlier examples, we used the <literal
  1.2178 +	  role="hook">commit</literal> hook, which is run after a
  1.2179 +	commit has completed.  This is one of several Mercurial hooks
  1.2180 +	that run after an activity finishes.  Such hooks have no way
  1.2181 +	of influencing the activity itself.
  1.2182 +      </para>
  1.2183 +
  1.2184 +      <para id="x_21a">Mercurial defines a number of events that occur before an
  1.2185 +	activity starts; or after it starts, but before it finishes.
  1.2186 +	Hooks that trigger on these events have the added ability to
  1.2187 +	choose whether the activity can continue, or will abort.
  1.2188 +      </para>
  1.2189 +
  1.2190 +      <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs
  1.2191 +	after a commit has all but completed.  In other words, the
  1.2192 +	metadata representing the changeset has been written out to
  1.2193 +	disk, but the transaction has not yet been allowed to
  1.2194 +	complete.  The <literal role="hook">pretxncommit</literal>
  1.2195 +	hook has the ability to decide whether the transaction can
  1.2196 +	complete, or must be rolled back.
  1.2197 +      </para>
  1.2198 +
  1.2199 +      <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook
  1.2200 +	exits with a status code of zero, the transaction is allowed
  1.2201 +	to complete; the commit finishes; and the <literal
  1.2202 +	  role="hook">commit</literal> hook is run.  If the <literal
  1.2203 +	  role="hook">pretxncommit</literal> hook exits with a
  1.2204 +	non-zero status code, the transaction is rolled back; the
  1.2205 +	metadata representing the changeset is erased; and the
  1.2206 +	<literal role="hook">commit</literal> hook is not run.
  1.2207 +      </para>
  1.2208 +
  1.2209 +&interaction.hook.simple.pretxncommit;
  1.2210 +
  1.2211 +      <para id="x_21d">The hook in the example above checks that a commit comment
  1.2212 +	contains a bug ID.  If it does, the commit can complete.  If
  1.2213 +	not, the commit is rolled back.
  1.2214 +      </para>
  1.2215 +
  1.2216 +    </sect2>
  1.2217 +  </sect1>
  1.2218 +  <sect1>
  1.2219 +    <title>Writing your own hooks</title>
  1.2220 +
  1.2221 +    <para id="x_21e">When you are writing a hook, you might find it useful to run
  1.2222 +      Mercurial either with the <option
  1.2223 +	role="hg-opt-global">-v</option> option, or the <envar
  1.2224 +	role="rc-item-ui">verbose</envar> config item set to
  1.2225 +      <quote>true</quote>.  When you do so, Mercurial will print a
  1.2226 +      message before it calls each hook.
  1.2227 +    </para>
  1.2228 +
  1.2229 +    <sect2 id="sec:hook:lang">
  1.2230 +      <title>Choosing how your hook should run</title>
  1.2231 +
  1.2232 +      <para id="x_21f">You can write a hook either as a normal
  1.2233 +	program&emdash;typically a shell script&emdash;or as a Python
  1.2234 +	function that is executed within the Mercurial process.
  1.2235 +      </para>
  1.2236 +
  1.2237 +      <para id="x_220">Writing a hook as an external program has the advantage
  1.2238 +	that it requires no knowledge of Mercurial's internals.  You
  1.2239 +	can call normal Mercurial commands to get any added
  1.2240 +	information you need.  The trade-off is that external hooks
  1.2241 +	are slower than in-process hooks.
  1.2242 +      </para>
  1.2243 +
  1.2244 +      <para id="x_221">An in-process Python hook has complete access to the
  1.2245 +	Mercurial API, and does not <quote>shell out</quote> to
  1.2246 +	another process, so it is inherently faster than an external
  1.2247 +	hook.  It is also easier to obtain much of the information
  1.2248 +	that a hook requires by using the Mercurial API than by
  1.2249 +	running Mercurial commands.
  1.2250 +      </para>
  1.2251 +
  1.2252 +      <para id="x_222">If you are comfortable with Python, or require high
  1.2253 +	performance, writing your hooks in Python may be a good
  1.2254 +	choice.  However, when you have a straightforward hook to
  1.2255 +	write and you don't need to care about performance (probably
  1.2256 +	the majority of hooks), a shell script is perfectly fine.
  1.2257 +      </para>
  1.2258 +
  1.2259 +    </sect2>
  1.2260 +    <sect2 id="sec:hook:param">
  1.2261 +      <title>Hook parameters</title>
  1.2262 +
  1.2263 +      <para id="x_223">Mercurial calls each hook with a set of well-defined
  1.2264 +	parameters.  In Python, a parameter is passed as a keyword
  1.2265 +	argument to your hook function.  For an external program, a
  1.2266 +	parameter is passed as an environment variable.
  1.2267 +      </para>
  1.2268 +
  1.2269 +      <para id="x_224">Whether your hook is written in Python or as a shell
  1.2270 +	script, the hook-specific parameter names and values will be
  1.2271 +	the same.  A boolean parameter will be represented as a
  1.2272 +	boolean value in Python, but as the number 1 (for
  1.2273 +	<quote>true</quote>) or 0 (for <quote>false</quote>) as an
  1.2274 +	environment variable for an external hook.  If a hook
  1.2275 +	parameter is named <literal>foo</literal>, the keyword
  1.2276 +	argument for a Python hook will also be named
  1.2277 +	<literal>foo</literal>, while the environment variable for an
  1.2278 +	external hook will be named <literal>HG_FOO</literal>.
  1.2279 +      </para>
  1.2280 +    </sect2>
  1.2281 +
  1.2282 +    <sect2>
  1.2283 +      <title>Hook return values and activity control</title>
  1.2284 +
  1.2285 +      <para id="x_225">A hook that executes successfully must exit with a status
  1.2286 +	of zero if external, or return boolean <quote>false</quote> if
  1.2287 +	in-process.  Failure is indicated with a non-zero exit status
  1.2288 +	from an external hook, or an in-process hook returning boolean
  1.2289 +	<quote>true</quote>.  If an in-process hook raises an
  1.2290 +	exception, the hook is considered to have failed.
  1.2291 +      </para>
  1.2292 +
  1.2293 +      <para id="x_226">For a hook that controls whether an activity can proceed,
  1.2294 +	zero/false means <quote>allow</quote>, while
  1.2295 +	non-zero/true/exception means <quote>deny</quote>.
  1.2296 +      </para>
  1.2297 +    </sect2>
  1.2298 +
  1.2299 +    <sect2>
  1.2300 +      <title>Writing an external hook</title>
  1.2301 +
  1.2302 +      <para id="x_227">When you define an external hook in your <filename
  1.2303 +	  role="special">~/.hgrc</filename> and the hook is run, its
  1.2304 +	value is passed to your shell, which interprets it.  This
  1.2305 +	means that you can use normal shell constructs in the body of
  1.2306 +	the hook.
  1.2307 +      </para>
  1.2308 +
  1.2309 +      <para id="x_228">An executable hook is always run with its current
  1.2310 +	directory set to a repository's root directory.
  1.2311 +      </para>
  1.2312 +
  1.2313 +      <para id="x_229">Each hook parameter is passed in as an environment
  1.2314 +	variable; the name is upper-cased, and prefixed with the
  1.2315 +	string <quote><literal>HG_</literal></quote>.
  1.2316 +      </para>
  1.2317 +
  1.2318 +      <para id="x_22a">With the exception of hook parameters, Mercurial does not
  1.2319 +	set or modify any environment variables when running a hook.
  1.2320 +	This is useful to remember if you are writing a site-wide hook
  1.2321 +	that may be run by a number of different users with differing
  1.2322 +	environment variables set. In multi-user situations, you
  1.2323 +	should not rely on environment variables being set to the
  1.2324 +	values you have in your environment when testing the hook.
  1.2325 +      </para>
  1.2326 +    </sect2>
  1.2327 +
  1.2328 +    <sect2>
  1.2329 +      <title>Telling Mercurial to use an in-process hook</title>
  1.2330 +
  1.2331 +      <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax
  1.2332 +	for defining an in-process hook is slightly different than for
  1.2333 +	an executable hook.  The value of the hook must start with the
  1.2334 +	text <quote><literal>python:</literal></quote>, and continue
  1.2335 +	with the fully-qualified name of a callable object to use as
  1.2336 +	the hook's value.
  1.2337 +      </para>
  1.2338 +
  1.2339 +      <para id="x_22c">The module in which a hook lives is automatically imported
  1.2340 +	when a hook is run.  So long as you have the module name and
  1.2341 +	<envar>PYTHONPATH</envar> right, it should <quote>just
  1.2342 +	  work</quote>.
  1.2343 +      </para>
  1.2344 +
  1.2345 +      <para id="x_22d">The following <filename role="special">~/.hgrc</filename>
  1.2346 +	example snippet illustrates the syntax and meaning of the
  1.2347 +	notions we just described.
  1.2348 +      </para>
  1.2349 +      <programlisting>[hooks]
  1.2350 +commit.example = python:mymodule.submodule.myhook</programlisting>
  1.2351 +      <para id="x_22e">When Mercurial runs the <literal>commit.example</literal>
  1.2352 +	hook, it imports <literal>mymodule.submodule</literal>, looks
  1.2353 +	for the callable object named <literal>myhook</literal>, and
  1.2354 +	calls it.
  1.2355 +      </para>
  1.2356 +    </sect2>
  1.2357 +
  1.2358 +    <sect2>
  1.2359 +      <title>Writing an in-process hook</title>
  1.2360 +
  1.2361 +      <para id="x_22f">The simplest in-process hook does nothing, but illustrates
  1.2362 +	the basic shape of the hook API:
  1.2363 +      </para>
  1.2364 +      <programlisting>def myhook(ui, repo, **kwargs):
  1.2365 +    pass</programlisting>
  1.2366 +      <para id="x_230">The first argument to a Python hook is always a <literal
  1.2367 +	  role="py-mod-mercurial.ui">ui</literal> object.  The second
  1.2368 +	is a repository object; at the moment, it is always an
  1.2369 +	instance of <literal
  1.2370 +	  role="py-mod-mercurial.localrepo">localrepository</literal>.
  1.2371 +	Following these two arguments are other keyword arguments.
  1.2372 +	Which ones are passed in depends on the hook being called, but
  1.2373 +	a hook can ignore arguments it doesn't care about by dropping
  1.2374 +	them into a keyword argument dict, as with
  1.2375 +	<literal>**kwargs</literal> above.
  1.2376 +      </para>
  1.2377 +
  1.2378 +    </sect2>
  1.2379 +  </sect1>
  1.2380 +  <sect1>
  1.2381 +    <title>Some hook examples</title>
  1.2382 +
  1.2383 +    <sect2>
  1.2384 +      <title>Writing meaningful commit messages</title>
  1.2385 +
  1.2386 +      <para id="x_231">It's hard to imagine a useful commit message being very
  1.2387 +	short. The simple <literal role="hook">pretxncommit</literal>
  1.2388 +	hook of the example below will prevent you from committing a
  1.2389 +	changeset with a message that is less than ten bytes long.
  1.2390 +      </para>
  1.2391 +
  1.2392 +&interaction.hook.msglen.go;
  1.2393 +    </sect2>
  1.2394 +
  1.2395 +    <sect2>
  1.2396 +      <title>Checking for trailing whitespace</title>
  1.2397 +
  1.2398 +      <para id="x_232">An interesting use of a commit-related hook is to help you
  1.2399 +	to write cleaner code.  A simple example of <quote>cleaner
  1.2400 +	  code</quote> is the dictum that a change should not add any
  1.2401 +	new lines of text that contain <quote>trailing
  1.2402 +	  whitespace</quote>.  Trailing whitespace is a series of
  1.2403 +	space and tab characters at the end of a line of text.  In
  1.2404 +	most cases, trailing whitespace is unnecessary, invisible
  1.2405 +	noise, but it is occasionally problematic, and people often
  1.2406 +	prefer to get rid of it.
  1.2407 +      </para>
  1.2408 +
  1.2409 +      <para id="x_233">You can use either the <literal
  1.2410 +	  role="hook">precommit</literal> or <literal
  1.2411 +	  role="hook">pretxncommit</literal> hook to tell whether you
  1.2412 +	have a trailing whitespace problem.  If you use the <literal
  1.2413 +	  role="hook">precommit</literal> hook, the hook will not know
  1.2414 +	which files you are committing, so it will have to check every
  1.2415 +	modified file in the repository for trailing white space.  If
  1.2416 +	you want to commit a change to just the file
  1.2417 +	<filename>foo</filename>, but the file
  1.2418 +	<filename>bar</filename> contains trailing whitespace, doing a
  1.2419 +	check in the <literal role="hook">precommit</literal> hook
  1.2420 +	will prevent you from committing <filename>foo</filename> due
  1.2421 +	to the problem with <filename>bar</filename>.  This doesn't
  1.2422 +	seem right.
  1.2423 +      </para>
  1.2424 +
  1.2425 +      <para id="x_234">Should you choose the <literal
  1.2426 +	  role="hook">pretxncommit</literal> hook, the check won't
  1.2427 +	occur until just before the transaction for the commit
  1.2428 +	completes.  This will allow you to check for problems only the
  1.2429 +	exact files that are being committed.  However, if you entered
  1.2430 +	the commit message interactively and the hook fails, the
  1.2431 +	transaction will roll back; you'll have to re-enter the commit
  1.2432 +	message after you fix the trailing whitespace and run <command
  1.2433 +	  role="hg-cmd">hg commit</command> again.
  1.2434 +      </para>
  1.2435 +
  1.2436 +      &interaction.ch09-hook.ws.simple;
  1.2437 +
  1.2438 +      <para id="x_235">In this example, we introduce a simple <literal
  1.2439 +	  role="hook">pretxncommit</literal> hook that checks for
  1.2440 +	trailing whitespace.  This hook is short, but not very
  1.2441 +	helpful.  It exits with an error status if a change adds a
  1.2442 +	line with trailing whitespace to any file, but does not print
  1.2443 +	any information that might help us to identify the offending
  1.2444 +	file or line.  It also has the nice property of not paying
  1.2445 +	attention to unmodified lines; only lines that introduce new
  1.2446 +	trailing whitespace cause problems.
  1.2447 +      </para>
  1.2448 +
  1.2449 +      &ch09-check_whitespace.py.lst;
  1.2450 +
  1.2451 +      <para id="x_236">The above version is much more complex, but also more
  1.2452 +	useful.  It parses a unified diff to see if any lines add
  1.2453 +	trailing whitespace, and prints the name of the file and the
  1.2454 +	line number of each such occurrence.  Even better, if the
  1.2455 +	change adds trailing whitespace, this hook saves the commit
  1.2456 +	comment and prints the name of the save file before exiting
  1.2457 +	and telling Mercurial to roll the transaction back, so you can
  1.2458 +	use the <option role="hg-opt-commit">-l filename</option>
  1.2459 +	option to <command role="hg-cmd">hg commit</command> to reuse
  1.2460 +	the saved commit message once you've corrected the problem.
  1.2461 +      </para>
  1.2462 +
  1.2463 +      &interaction.ch09-hook.ws.better;
  1.2464 +
  1.2465 +      <para id="x_237">As a final aside, note in the example above the
  1.2466 +	use of <command>sed</command>'s in-place editing feature to
  1.2467 +	get rid of trailing whitespace from a file.  This is concise
  1.2468 +	and useful enough that I will reproduce it here (using
  1.2469 +	<command>perl</command> for good measure).</para>
  1.2470 +      <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting>
  1.2471 +
  1.2472 +    </sect2>
  1.2473 +  </sect1>
  1.2474 +  <sect1>
  1.2475 +    <title>Bundled hooks</title>
  1.2476 +
  1.2477 +    <para id="x_238">Mercurial ships with several bundled hooks.  You can find
  1.2478 +      them in the <filename class="directory">hgext</filename>
  1.2479 +      directory of a Mercurial source tree.  If you are using a
  1.2480 +      Mercurial binary package, the hooks will be located in the
  1.2481 +      <filename class="directory">hgext</filename> directory of
  1.2482 +      wherever your package installer put Mercurial.
  1.2483 +    </para>
  1.2484 +
  1.2485 +    <sect2>
  1.2486 +      <title><literal role="hg-ext">acl</literal>&emdash;access
  1.2487 +	control for parts of a repository</title>
  1.2488 +
  1.2489 +      <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets
  1.2490 +	you control which remote users are allowed to push changesets
  1.2491 +	to a networked server.  You can protect any portion of a
  1.2492 +	repository (including the entire repo), so that a specific
  1.2493 +	remote user can push changes that do not affect the protected
  1.2494 +	portion.
  1.2495 +      </para>
  1.2496 +
  1.2497 +      <para id="x_23a">This extension implements access control based on the
  1.2498 +	identity of the user performing a push,
  1.2499 +	<emphasis>not</emphasis> on who committed the changesets
  1.2500 +	they're pushing.  It makes sense to use this hook only if you
  1.2501 +	have a locked-down server environment that authenticates
  1.2502 +	remote users, and you want to be sure that only specific users
  1.2503 +	are allowed to push changes to that server.
  1.2504 +      </para>
  1.2505 +
  1.2506 +      <sect3>
  1.2507 +	<title>Configuring the <literal role="hook">acl</literal>
  1.2508 +	  hook</title>
  1.2509 +
  1.2510 +	<para id="x_23b">In order to manage incoming changesets, the <literal
  1.2511 +	    role="hg-ext">acl</literal> hook must be used as a
  1.2512 +	  <literal role="hook">pretxnchangegroup</literal> hook.  This
  1.2513 +	  lets it see which files are modified by each incoming
  1.2514 +	  changeset, and roll back a group of changesets if they
  1.2515 +	  modify <quote>forbidden</quote> files.  Example:
  1.2516 +	</para>
  1.2517 +	<programlisting>[hooks]
  1.2518 +pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
  1.2519 +
  1.2520 +	<para id="x_23c">The <literal role="hg-ext">acl</literal> extension is
  1.2521 +	  configured using three sections.
  1.2522 +	</para>
  1.2523 +
  1.2524 +	<para id="x_23d">The <literal role="rc-acl">acl</literal> section has
  1.2525 +	  only one entry, <envar role="rc-item-acl">sources</envar>,
  1.2526 +	  which lists the sources of incoming changesets that the hook
  1.2527 +	  should pay attention to.  You don't normally need to
  1.2528 +	  configure this section.
  1.2529 +	</para>
  1.2530 +	<itemizedlist>
  1.2531 +	  <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
  1.2532 +	      Control incoming changesets that are arriving from a
  1.2533 +	      remote repository over http or ssh.  This is the default
  1.2534 +	      value of <envar role="rc-item-acl">sources</envar>, and
  1.2535 +	      usually the only setting you'll need for this
  1.2536 +	      configuration item.
  1.2537 +	    </para>
  1.2538 +	  </listitem>
  1.2539 +	  <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
  1.2540 +	      Control incoming changesets that are arriving via a pull
  1.2541 +	      from a local repository.
  1.2542 +	    </para>
  1.2543 +	  </listitem>
  1.2544 +	  <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
  1.2545 +	      Control incoming changesets that are arriving via a push
  1.2546 +	      from a local repository.
  1.2547 +	    </para>
  1.2548 +	  </listitem>
  1.2549 +	  <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
  1.2550 +	      Control incoming changesets that are arriving from
  1.2551 +	      another repository via a bundle.
  1.2552 +	    </para>
  1.2553 +	  </listitem></itemizedlist>
  1.2554 +
  1.2555 +	<para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal>
  1.2556 +	  section controls the users that are allowed to add
  1.2557 +	  changesets to the repository.  If this section is not
  1.2558 +	  present, all users that are not explicitly denied are
  1.2559 +	  allowed.  If this section is present, all users that are not
  1.2560 +	  explicitly allowed are denied (so an empty section means
  1.2561 +	  that all users are denied).
  1.2562 +	</para>
  1.2563 +
  1.2564 +	<para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal>
  1.2565 +	  section determines which users are denied from adding
  1.2566 +	  changesets to the repository.  If this section is not
  1.2567 +	  present or is empty, no users are denied.
  1.2568 +	</para>
  1.2569 +
  1.2570 +	<para id="x_244">The syntaxes for the <literal
  1.2571 +	    role="rc-acl.allow">acl.allow</literal> and <literal
  1.2572 +	    role="rc-acl.deny">acl.deny</literal> sections are
  1.2573 +	  identical.  On the left of each entry is a glob pattern that
  1.2574 +	  matches files or directories, relative to the root of the
  1.2575 +	  repository; on the right, a user name.
  1.2576 +	</para>
  1.2577 +
  1.2578 +	<para id="x_245">In the following example, the user
  1.2579 +	  <literal>docwriter</literal> can only push changes to the
  1.2580 +	  <filename class="directory">docs</filename> subtree of the
  1.2581 +	  repository, while <literal>intern</literal> can push changes
  1.2582 +	  to any file or directory except <filename
  1.2583 +	    class="directory">source/sensitive</filename>.
  1.2584 +	</para>
  1.2585 +	<programlisting>[acl.allow]
  1.2586 +docs/** = docwriter
  1.2587 +[acl.deny]
  1.2588 +source/sensitive/** = intern</programlisting>
  1.2589 +
  1.2590 +      </sect3>
  1.2591 +      <sect3>
  1.2592 +	<title>Testing and troubleshooting</title>
  1.2593 +
  1.2594 +	<para id="x_246">If you want to test the <literal
  1.2595 +	    role="hg-ext">acl</literal> hook, run it with Mercurial's
  1.2596 +	  debugging output enabled.  Since you'll probably be running
  1.2597 +	  it on a server where it's not convenient (or sometimes
  1.2598 +	  possible) to pass in the <option
  1.2599 +	    role="hg-opt-global">--debug</option> option, don't forget
  1.2600 +	  that you can enable debugging output in your <filename
  1.2601 +	    role="special">~/.hgrc</filename>:
  1.2602 +	</para>
  1.2603 +	<programlisting>[ui]
  1.2604 +debug = true</programlisting>
  1.2605 +	<para id="x_247">With this enabled, the <literal
  1.2606 +	    role="hg-ext">acl</literal> hook will print enough
  1.2607 +	  information to let you figure out why it is allowing or
  1.2608 +	  forbidding pushes from specific users.
  1.2609 +	</para>
  1.2610 +
  1.2611 +      </sect3>    </sect2>
  1.2612 +
  1.2613 +    <sect2>
  1.2614 +      <title><literal
  1.2615 +	  role="hg-ext">bugzilla</literal>&emdash;integration with
  1.2616 +	Bugzilla</title>
  1.2617 +
  1.2618 +      <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension
  1.2619 +	adds a comment to a Bugzilla bug whenever it finds a reference
  1.2620 +	to that bug ID in a commit comment.  You can install this hook
  1.2621 +	on a shared server, so that any time a remote user pushes
  1.2622 +	changes to this server, the hook gets run.
  1.2623 +      </para>
  1.2624 +
  1.2625 +      <para id="x_249">It adds a comment to the bug that looks like this (you can
  1.2626 +	configure the contents of the comment&emdash;see below):
  1.2627 +      </para>
  1.2628 +      <programlisting>Changeset aad8b264143a, made by Joe User
  1.2629 +	&lt;joe.user@domain.com&gt; in the frobnitz repository, refers
  1.2630 +	to this bug. For complete details, see
  1.2631 +	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
  1.2632 +	Changeset description: Fix bug 10483 by guarding against some
  1.2633 +	NULL pointers</programlisting>
  1.2634 +      <para id="x_24a">The value of this hook is that it automates the process of
  1.2635 +	updating a bug any time a changeset refers to it.  If you
  1.2636 +	configure the hook properly, it makes it easy for people to
  1.2637 +	browse straight from a Bugzilla bug to a changeset that refers
  1.2638 +	to that bug.
  1.2639 +      </para>
  1.2640 +
  1.2641 +      <para id="x_24b">You can use the code in this hook as a starting point for
  1.2642 +	some more exotic Bugzilla integration recipes.  Here are a few
  1.2643 +	possibilities:
  1.2644 +      </para>
  1.2645 +      <itemizedlist>
  1.2646 +	<listitem><para id="x_24c">Require that every changeset pushed to the
  1.2647 +	    server have a valid bug ID in its commit comment.  In this
  1.2648 +	    case, you'd want to configure the hook as a <literal
  1.2649 +	      role="hook">pretxncommit</literal> hook.  This would
  1.2650 +	    allow the hook to reject changes that didn't contain bug
  1.2651 +	    IDs.
  1.2652 +	  </para>
  1.2653 +	</listitem>
  1.2654 +	<listitem><para id="x_24d">Allow incoming changesets to automatically
  1.2655 +	    modify the <emphasis>state</emphasis> of a bug, as well as
  1.2656 +	    simply adding a comment.  For example, the hook could
  1.2657 +	    recognise the string <quote>fixed bug 31337</quote> as
  1.2658 +	    indicating that it should update the state of bug 31337 to
  1.2659 +	    <quote>requires testing</quote>.
  1.2660 +	  </para>
  1.2661 +	</listitem></itemizedlist>
  1.2662 +
  1.2663 +      <sect3 id="sec:hook:bugzilla:config">
  1.2664 +	<title>Configuring the <literal role="hook">bugzilla</literal>
  1.2665 +	  hook</title>
  1.2666 +
  1.2667 +	<para id="x_24e">You should configure this hook in your server's
  1.2668 +	  <filename role="special">~/.hgrc</filename> as an <literal
  1.2669 +	    role="hook">incoming</literal> hook, for example as
  1.2670 +	  follows:
  1.2671 +	</para>
  1.2672 +	<programlisting>[hooks]
  1.2673 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
  1.2674 +
  1.2675 +	<para id="x_24f">Because of the specialised nature of this hook, and
  1.2676 +	  because Bugzilla was not written with this kind of
  1.2677 +	  integration in mind, configuring this hook is a somewhat
  1.2678 +	  involved process.
  1.2679 +	</para>
  1.2680 +
  1.2681 +	<para id="x_250">Before you begin, you must install the MySQL bindings
  1.2682 +	  for Python on the host(s) where you'll be running the hook.
  1.2683 +	  If this is not available as a binary package for your
  1.2684 +	  system, you can download it from
  1.2685 +	  <citation>web:mysql-python</citation>.
  1.2686 +	</para>
  1.2687 +
  1.2688 +	<para id="x_251">Configuration information for this hook lives in the
  1.2689 +	  <literal role="rc-bugzilla">bugzilla</literal> section of
  1.2690 +	  your <filename role="special">~/.hgrc</filename>.
  1.2691 +	</para>
  1.2692 +	<itemizedlist>
  1.2693 +	  <listitem><para id="x_252"><envar
  1.2694 +		role="rc-item-bugzilla">version</envar>: The version
  1.2695 +	      of Bugzilla installed on the server.  The database
  1.2696 +	      schema that Bugzilla uses changes occasionally, so this
  1.2697 +	      hook has to know exactly which schema to use.</para>
  1.2698 +	  </listitem>
  1.2699 +	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
  1.2700 +	      The hostname of the MySQL server that stores your
  1.2701 +	      Bugzilla data.  The database must be configured to allow
  1.2702 +	      connections from whatever host you are running the
  1.2703 +	      <literal role="hook">bugzilla</literal> hook on.
  1.2704 +	    </para>
  1.2705 +	  </listitem>
  1.2706 +	  <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
  1.2707 +	      The username with which to connect to the MySQL server.
  1.2708 +	      The database must be configured to allow this user to
  1.2709 +	      connect from whatever host you are running the <literal
  1.2710 +		role="hook">bugzilla</literal> hook on.  This user
  1.2711 +	      must be able to access and modify Bugzilla tables.  The
  1.2712 +	      default value of this item is <literal>bugs</literal>,
  1.2713 +	      which is the standard name of the Bugzilla user in a
  1.2714 +	      MySQL database.
  1.2715 +	    </para>
  1.2716 +	  </listitem>
  1.2717 +	  <listitem><para id="x_255"><envar
  1.2718 +		role="rc-item-bugzilla">password</envar>: The MySQL
  1.2719 +	      password for the user you configured above.  This is
  1.2720 +	      stored as plain text, so you should make sure that
  1.2721 +	      unauthorised users cannot read the <filename
  1.2722 +		role="special">~/.hgrc</filename> file where you
  1.2723 +	      store this information.
  1.2724 +	    </para>
  1.2725 +	  </listitem>
  1.2726 +	  <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
  1.2727 +	      The name of the Bugzilla database on the MySQL server.
  1.2728 +	      The default value of this item is
  1.2729 +	      <literal>bugs</literal>, which is the standard name of
  1.2730 +	      the MySQL database where Bugzilla stores its data.
  1.2731 +	    </para>
  1.2732 +	  </listitem>
  1.2733 +	  <listitem><para id="x_257"><envar
  1.2734 +		role="rc-item-bugzilla">notify</envar>: If you want
  1.2735 +	      Bugzilla to send out a notification email to subscribers
  1.2736 +	      after this hook has added a comment to a bug, you will
  1.2737 +	      need this hook to run a command whenever it updates the
  1.2738 +	      database.  The command to run depends on where you have
  1.2739 +	      installed Bugzilla, but it will typically look something
  1.2740 +	      like this, if you have Bugzilla installed in <filename
  1.2741 +		class="directory">/var/www/html/bugzilla</filename>:
  1.2742 +	    </para>
  1.2743 +	    <programlisting>cd /var/www/html/bugzilla &amp;&amp;
  1.2744 +	      ./processmail %s nobody@nowhere.com</programlisting>
  1.2745 +	  </listitem>
  1.2746 +	  <listitem><para id="x_258">  The Bugzilla
  1.2747 +	      <literal>processmail</literal> program expects to be
  1.2748 +	      given a bug ID (the hook replaces
  1.2749 +	      <quote><literal>%s</literal></quote> with the bug ID)
  1.2750 +	      and an email address.  It also expects to be able to
  1.2751 +	      write to some files in the directory that it runs in.
  1.2752 +	      If Bugzilla and this hook are not installed on the same
  1.2753 +	      machine, you will need to find a way to run
  1.2754 +	      <literal>processmail</literal> on the server where
  1.2755 +	      Bugzilla is installed.
  1.2756 +	    </para>
  1.2757 +	  </listitem></itemizedlist>
  1.2758 +
  1.2759 +      </sect3>
  1.2760 +      <sect3>
  1.2761 +	<title>Mapping committer names to Bugzilla user names</title>
  1.2762 +
  1.2763 +	<para id="x_259">By default, the <literal
  1.2764 +	    role="hg-ext">bugzilla</literal> hook tries to use the
  1.2765 +	  email address of a changeset's committer as the Bugzilla
  1.2766 +	  user name with which to update a bug.  If this does not suit
  1.2767 +	  your needs, you can map committer email addresses to
  1.2768 +	  Bugzilla user names using a <literal
  1.2769 +	    role="rc-usermap">usermap</literal> section.
  1.2770 +	</para>
  1.2771 +
  1.2772 +	<para id="x_25a">Each item in the <literal
  1.2773 +	    role="rc-usermap">usermap</literal> section contains an
  1.2774 +	  email address on the left, and a Bugzilla user name on the
  1.2775 +	  right.
  1.2776 +	</para>
  1.2777 +	<programlisting>[usermap]
  1.2778 +jane.user@example.com = jane</programlisting>
  1.2779 +	<para id="x_25b">You can either keep the <literal
  1.2780 +	    role="rc-usermap">usermap</literal> data in a normal
  1.2781 +	  <filename role="special">~/.hgrc</filename>, or tell the
  1.2782 +	  <literal role="hg-ext">bugzilla</literal> hook to read the
  1.2783 +	  information from an external <filename>usermap</filename>
  1.2784 +	  file.  In the latter case, you can store
  1.2785 +	  <filename>usermap</filename> data by itself in (for example)
  1.2786 +	  a user-modifiable repository.  This makes it possible to let
  1.2787 +	  your users maintain their own <envar
  1.2788 +	    role="rc-item-bugzilla">usermap</envar> entries.  The main
  1.2789 +	  <filename role="special">~/.hgrc</filename> file might look
  1.2790 +	  like this:
  1.2791 +	</para>
  1.2792 +	<programlisting># regular hgrc file refers to external usermap file
  1.2793 +[bugzilla]
  1.2794 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
  1.2795 +	<para id="x_25c">While the <filename>usermap</filename> file that it
  1.2796 +	  refers to might look like this:
  1.2797 +	</para>
  1.2798 +	<programlisting># bugzilla-usermap.conf - inside a hg repository
  1.2799 +[usermap] stephanie@example.com = steph</programlisting>
  1.2800 +
  1.2801 +      </sect3>
  1.2802 +      <sect3>
  1.2803 +	<title>Configuring the text that gets added to a bug</title>
  1.2804 +
  1.2805 +	<para id="x_25d">You can configure the text that this hook adds as a
  1.2806 +	  comment; you specify it in the form of a Mercurial template.
  1.2807 +	  Several <filename role="special">~/.hgrc</filename> entries
  1.2808 +	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
  1.2809 +	  section) control this behavior.
  1.2810 +	</para>
  1.2811 +	<itemizedlist>
  1.2812 +	  <listitem><para id="x_25e"><literal>strip</literal>: The number of
  1.2813 +	      leading path elements to strip from a repository's path
  1.2814 +	      name to construct a partial path for a URL. For example,
  1.2815 +	      if the repositories on your server live under <filename
  1.2816 +		class="directory">/home/hg/repos</filename>, and you
  1.2817 +	      have a repository whose path is <filename
  1.2818 +		class="directory">/home/hg/repos/app/tests</filename>,
  1.2819 +	      then setting <literal>strip</literal> to
  1.2820 +	      <literal>4</literal> will give a partial path of
  1.2821 +	      <filename class="directory">app/tests</filename>.  The
  1.2822 +	      hook will make this partial path available when
  1.2823 +	      expanding a template, as <literal>webroot</literal>.
  1.2824 +	    </para>
  1.2825 +	  </listitem>
  1.2826 +	  <listitem><para id="x_25f"><literal>template</literal>: The text of the
  1.2827 +	      template to use.  In addition to the usual
  1.2828 +	      changeset-related variables, this template can use
  1.2829 +	      <literal>hgweb</literal> (the value of the
  1.2830 +	      <literal>hgweb</literal> configuration item above) and
  1.2831 +	      <literal>webroot</literal> (the path constructed using
  1.2832 +	      <literal>strip</literal> above).
  1.2833 +	    </para>
  1.2834 +	  </listitem></itemizedlist>
  1.2835 +
  1.2836 +	<para id="x_260">In addition, you can add a <envar
  1.2837 +	    role="rc-item-web">baseurl</envar> item to the <literal
  1.2838 +	    role="rc-web">web</literal> section of your <filename
  1.2839 +	    role="special">~/.hgrc</filename>.  The <literal
  1.2840 +	    role="hg-ext">bugzilla</literal> hook will make this
  1.2841 +	  available when expanding a template, as the base string to
  1.2842 +	  use when constructing a URL that will let users browse from
  1.2843 +	  a Bugzilla comment to view a changeset.  Example:
  1.2844 +	</para>
  1.2845 +	<programlisting>[web]
  1.2846 +baseurl = http://hg.domain.com/</programlisting>
  1.2847 +
  1.2848 +	<para id="x_261">Here is an example set of <literal
  1.2849 +	    role="hg-ext">bugzilla</literal> hook config information.
  1.2850 +	</para>
  1.2851 +
  1.2852 +	&ch10-bugzilla-config.lst;
  1.2853 +
  1.2854 +      </sect3>
  1.2855 +      <sect3>
  1.2856 +	<title>Testing and troubleshooting</title>
  1.2857 +
  1.2858 +	<para id="x_262">The most common problems with configuring the <literal
  1.2859 +	    role="hg-ext">bugzilla</literal> hook relate to running
  1.2860 +	  Bugzilla's <filename>processmail</filename> script and
  1.2861 +	  mapping committer names to user names.
  1.2862 +	</para>
  1.2863 +
  1.2864 +	<para id="x_263">Recall from <xref
  1.2865 +	    linkend="sec:hook:bugzilla:config"/> above that the user
  1.2866 +	  that runs the Mercurial process on the server is also the
  1.2867 +	  one that will run the <filename>processmail</filename>
  1.2868 +	  script.  The <filename>processmail</filename> script
  1.2869 +	  sometimes causes Bugzilla to write to files in its
  1.2870 +	  configuration directory, and Bugzilla's configuration files
  1.2871 +	  are usually owned by the user that your web server runs
  1.2872 +	  under.
  1.2873 +	</para>
  1.2874 +
  1.2875 +	<para id="x_264">You can cause <filename>processmail</filename> to be run
  1.2876 +	  with the suitable user's identity using the
  1.2877 +	  <command>sudo</command> command.  Here is an example entry
  1.2878 +	  for a <filename>sudoers</filename> file.
  1.2879 +	</para>
  1.2880 +	<programlisting>hg_user = (httpd_user)
  1.2881 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
  1.2882 +	<para id="x_265">This allows the <literal>hg_user</literal> user to run a
  1.2883 +	  <filename>processmail-wrapper</filename> program under the
  1.2884 +	  identity of <literal>httpd_user</literal>.
  1.2885 +	</para>
  1.2886 +
  1.2887 +	<para id="x_266">This indirection through a wrapper script is necessary,
  1.2888 +	  because <filename>processmail</filename> expects to be run
  1.2889 +	  with its current directory set to wherever you installed
  1.2890 +	  Bugzilla; you can't specify that kind of constraint in a
  1.2891 +	  <filename>sudoers</filename> file.  The contents of the
  1.2892 +	  wrapper script are simple:
  1.2893 +	</para>
  1.2894 +	<programlisting>#!/bin/sh
  1.2895 +cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
  1.2896 +	<para id="x_267">It doesn't seem to matter what email address you pass to
  1.2897 +	  <filename>processmail</filename>.
  1.2898 +	</para>
  1.2899 +
  1.2900 +	<para id="x_268">If your <literal role="rc-usermap">usermap</literal> is
  1.2901 +	  not set up correctly, users will see an error message from
  1.2902 +	  the <literal role="hg-ext">bugzilla</literal> hook when they
  1.2903 +	  push changes to the server.  The error message will look
  1.2904 +	  like this:
  1.2905 +	</para>
  1.2906 +	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
  1.2907 +	<para id="x_269">What this means is that the committer's address,
  1.2908 +	  <literal>john.q.public@example.com</literal>, is not a valid
  1.2909 +	  Bugzilla user name, nor does it have an entry in your
  1.2910 +	  <literal role="rc-usermap">usermap</literal> that maps it to
  1.2911 +	  a valid Bugzilla user name.
  1.2912 +	</para>
  1.2913 +
  1.2914 +      </sect3>    </sect2>
  1.2915 +
  1.2916 +    <sect2>
  1.2917 +      <title><literal role="hg-ext">notify</literal>&emdash;send email
  1.2918 +	notifications</title>
  1.2919 +
  1.2920 +      <para id="x_26a">Although Mercurial's built-in web server provides RSS
  1.2921 +	feeds of changes in every repository, many people prefer to
  1.2922 +	receive change notifications via email.  The <literal
  1.2923 +	  role="hg-ext">notify</literal> hook lets you send out
  1.2924 +	notifications to a set of email addresses whenever changesets
  1.2925 +	arrive that those subscribers are interested in.
  1.2926 +      </para>
  1.2927 +
  1.2928 +      <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal>
  1.2929 +	hook, the <literal role="hg-ext">notify</literal> hook is
  1.2930 +	template-driven, so you can customise the contents of the
  1.2931 +	notification messages that it sends.
  1.2932 +      </para>
  1.2933 +
  1.2934 +      <para id="x_26c">By default, the <literal role="hg-ext">notify</literal>
  1.2935 +	hook includes a diff of every changeset that it sends out; you
  1.2936 +	can limit the size of the diff, or turn this feature off
  1.2937 +	entirely.  It is useful for letting subscribers review changes
  1.2938 +	immediately, rather than clicking to follow a URL.
  1.2939 +      </para>
  1.2940 +
  1.2941 +      <sect3>
  1.2942 +	<title>Configuring the <literal role="hg-ext">notify</literal>
  1.2943 +	  hook</title>
  1.2944 +
  1.2945 +	<para id="x_26d">You can set up the <literal
  1.2946 +	    role="hg-ext">notify</literal> hook to send one email
  1.2947 +	  message per incoming changeset, or one per incoming group of
  1.2948 +	  changesets (all those that arrived in a single pull or
  1.2949 +	  push).
  1.2950 +	</para>
  1.2951 +	<programlisting>[hooks]
  1.2952 +# send one email per group of changes
  1.2953 +changegroup.notify = python:hgext.notify.hook
  1.2954 +# send one email per change
  1.2955 +incoming.notify = python:hgext.notify.hook</programlisting>
  1.2956 +
  1.2957 +	<para id="x_26e">Configuration information for this hook lives in the
  1.2958 +	  <literal role="rc-notify">notify</literal> section of a
  1.2959 +	  <filename role="special">~/.hgrc</filename> file.
  1.2960 +	</para>
  1.2961 +	<itemizedlist>
  1.2962 +	  <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
  1.2963 +	      By default, this hook does not send out email at all;
  1.2964 +	      instead, it prints the message that it
  1.2965 +	      <emphasis>would</emphasis> send.  Set this item to
  1.2966 +	      <literal>false</literal> to allow email to be sent. The
  1.2967 +	      reason that sending of email is turned off by default is
  1.2968 +	      that it takes several tries to configure this extension
  1.2969 +	      exactly as you would like, and it would be bad form to
  1.2970 +	      spam subscribers with a number of <quote>broken</quote>
  1.2971 +	      notifications while you debug your configuration.
  1.2972 +	    </para>
  1.2973 +	  </listitem>
  1.2974 +	  <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
  1.2975 +	      The path to a configuration file that contains
  1.2976 +	      subscription information.  This is kept separate from
  1.2977 +	      the main <filename role="special">~/.hgrc</filename> so
  1.2978 +	      that you can maintain it in a repository of its own.
  1.2979 +	      People can then clone that repository, update their
  1.2980 +	      subscriptions, and push the changes back to your server.
  1.2981 +	    </para>
  1.2982 +	  </listitem>
  1.2983 +	  <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
  1.2984 +	      The number of leading path separator characters to strip
  1.2985 +	      from a repository's path, when deciding whether a
  1.2986 +	      repository has subscribers.  For example, if the
  1.2987 +	      repositories on your server live in <filename
  1.2988 +		class="directory">/home/hg/repos</filename>, and
  1.2989 +	      <literal role="hg-ext">notify</literal> is considering a
  1.2990 +	      repository named <filename
  1.2991 +		class="directory">/home/hg/repos/shared/test</filename>, 
  1.2992 +	      setting <envar role="rc-item-notify">strip</envar> to
  1.2993 +	      <literal>4</literal> will cause <literal
  1.2994 +		role="hg-ext">notify</literal> to trim the path it
  1.2995 +	      considers down to <filename
  1.2996 +		class="directory">shared/test</filename>, and it will
  1.2997 +	      match subscribers against that.
  1.2998 +	    </para>
  1.2999 +	  </listitem>
  1.3000 +	  <listitem><para id="x_272"><envar
  1.3001 +		role="rc-item-notify">template</envar>: The template
  1.3002 +	      text to use when sending messages.  This specifies both
  1.3003 +	      the contents of the message header and its body.
  1.3004 +	    </para>
  1.3005 +	  </listitem>
  1.3006 +	  <listitem><para id="x_273"><envar
  1.3007 +		role="rc-item-notify">maxdiff</envar>: The maximum
  1.3008 +	      number of lines of diff data to append to the end of a
  1.3009 +	      message.  If a diff is longer than this, it is
  1.3010 +	      truncated.  By default, this is set to 300.  Set this to
  1.3011 +	      <literal>0</literal> to omit diffs from notification
  1.3012 +	      emails.
  1.3013 +	    </para>
  1.3014 +	  </listitem>
  1.3015 +	  <listitem><para id="x_274"><envar
  1.3016 +		role="rc-item-notify">sources</envar>: A list of
  1.3017 +	      sources of changesets to consider.  This lets you limit
  1.3018 +	      <literal role="hg-ext">notify</literal> to only sending
  1.3019 +	      out email about changes that remote users pushed into
  1.3020 +	      this repository via a server, for example.  See 
  1.3021 +	      <xref linkend="sec:hook:sources"/> for the sources you
  1.3022 +	      can specify here.
  1.3023 +	    </para>
  1.3024 +	  </listitem></itemizedlist>
  1.3025 +
  1.3026 +	<para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
  1.3027 +	  item in the <literal role="rc-web">web</literal> section,
  1.3028 +	  you can use it in a template; it will be available as
  1.3029 +	  <literal>webroot</literal>.
  1.3030 +	</para>
  1.3031 +
  1.3032 +	<para id="x_276">Here is an example set of <literal
  1.3033 +	    role="hg-ext">notify</literal> configuration information.
  1.3034 +	</para>
  1.3035 +
  1.3036 +	&ch10-notify-config.lst;
  1.3037 +
  1.3038 +	<para id="x_277">This will produce a message that looks like the
  1.3039 +	  following:
  1.3040 +	</para>
  1.3041 +
  1.3042 +	&ch10-notify-config-mail.lst;
  1.3043 +
  1.3044 +      </sect3>
  1.3045 +      <sect3>
  1.3046 +	<title>Testing and troubleshooting</title>
  1.3047 +
  1.3048 +	<para id="x_278">Do not forget that by default, the <literal
  1.3049 +		role="hg-ext">notify</literal> extension <emphasis>will not
  1.3050 +	  send any mail</emphasis> until you explicitly configure it to do so,
  1.3051 +	  by setting <envar role="rc-item-notify">test</envar> to
  1.3052 +	  <literal>false</literal>.  Until you do that, it simply
  1.3053 +	  prints the message it <emphasis>would</emphasis> send.
  1.3054 +	</para>
  1.3055 +
  1.3056 +      </sect3>
  1.3057 +    </sect2>
  1.3058 +  </sect1>
  1.3059 +  <sect1 id="sec:hook:ref">
  1.3060 +    <title>Information for writers of hooks</title>
  1.3061 +
  1.3062 +    <sect2>
  1.3063 +      <title>In-process hook execution</title>
  1.3064 +
  1.3065 +      <para id="x_279">An in-process hook is called with arguments of the
  1.3066 +	following form:
  1.3067 +      </para>
  1.3068 +      <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
  1.3069 +      <para id="x_27a">The <literal>ui</literal> parameter is a <literal
  1.3070 +	  role="py-mod-mercurial.ui">ui</literal> object. The
  1.3071 +	<literal>repo</literal> parameter is a <literal
  1.3072 +	  role="py-mod-mercurial.localrepo">localrepository</literal>
  1.3073 +	object.  The names and values of the
  1.3074 +	<literal>**kwargs</literal> parameters depend on the hook
  1.3075 +	being invoked, with the following common features:
  1.3076 +      </para>
  1.3077 +      <itemizedlist>
  1.3078 +	<listitem><para id="x_27b">If a parameter is named
  1.3079 +	    <literal>node</literal> or <literal>parentN</literal>, it
  1.3080 +	    will contain a hexadecimal changeset ID. The empty string
  1.3081 +	    is used to represent <quote>null changeset ID</quote>
  1.3082 +	    instead of a string of zeroes.
  1.3083 +	  </para>
  1.3084 +	</listitem>
  1.3085 +	<listitem><para id="x_27c">If a parameter is named
  1.3086 +	    <literal>url</literal>, it will contain the URL of a
  1.3087 +	    remote repository, if that can be determined.
  1.3088 +	  </para>
  1.3089 +	</listitem>
  1.3090 +	<listitem><para id="x_27d">Boolean-valued parameters are represented as
  1.3091 +	    Python <literal>bool</literal> objects.
  1.3092 +	  </para>
  1.3093 +	</listitem></itemizedlist>
  1.3094 +
  1.3095 +      <para id="x_27e">An in-process hook is called without a change to the
  1.3096 +	process's working directory (unlike external hooks, which are
  1.3097 +	run in the root of the repository).  It must not change the
  1.3098 +	process's working directory, or it will cause any calls it
  1.3099 +	makes into the Mercurial API to fail.
  1.3100 +      </para>
  1.3101 +
  1.3102 +      <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
  1.3103 +	is considered to have succeeded.  If it returns a boolean
  1.3104 +	<quote>true</quote> value or raises an exception, it is
  1.3105 +	considered to have failed.  A useful way to think of the
  1.3106 +	calling convention is <quote>tell me if you fail</quote>.
  1.3107 +      </para>
  1.3108 +
  1.3109 +      <para id="x_280">Note that changeset IDs are passed into Python hooks as
  1.3110 +	hexadecimal strings, not the binary hashes that Mercurial's
  1.3111 +	APIs normally use.  To convert a hash from hex to binary, use
  1.3112 +	the <literal>bin</literal> function.
  1.3113 +      </para>
  1.3114 +    </sect2>
  1.3115 +
  1.3116 +    <sect2>
  1.3117 +      <title>External hook execution</title>
  1.3118 +
  1.3119 +      <para id="x_281">An external hook is passed to the shell of the user
  1.3120 +	running Mercurial. Features of that shell, such as variable
  1.3121 +	substitution and command redirection, are available.  The hook
  1.3122 +	is run in the root directory of the repository (unlike
  1.3123 +	in-process hooks, which are run in the same directory that
  1.3124 +	Mercurial was run in).
  1.3125 +      </para>
  1.3126 +
  1.3127 +      <para id="x_282">Hook parameters are passed to the hook as environment
  1.3128 +	variables.  Each environment variable's name is converted in
  1.3129 +	upper case and prefixed with the string
  1.3130 +	<quote><literal>HG_</literal></quote>.  For example, if the
  1.3131 +	name of a parameter is <quote><literal>node</literal></quote>,
  1.3132 +	the name of the environment variable representing that
  1.3133 +	parameter will be <quote><literal>HG_NODE</literal></quote>.
  1.3134 +      </para>
  1.3135 +
  1.3136 +      <para id="x_283">A boolean parameter is represented as the string
  1.3137 +	<quote><literal>1</literal></quote> for <quote>true</quote>,
  1.3138 +	<quote><literal>0</literal></quote> for <quote>false</quote>.
  1.3139 +	If an environment variable is named <envar>HG_NODE</envar>,
  1.3140 +	<envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
  1.3141 +	contains a changeset ID represented as a hexadecimal string.
  1.3142 +	The empty string is used to represent <quote>null changeset
  1.3143 +	  ID</quote> instead of a string of zeroes.  If an environment
  1.3144 +	variable is named <envar>HG_URL</envar>, it will contain the
  1.3145 +	URL of a remote repository, if that can be determined.
  1.3146 +      </para>
  1.3147 +
  1.3148 +      <para id="x_284">If a hook exits with a status of zero, it is considered to
  1.3149 +	have succeeded.  If it exits with a non-zero status, it is
  1.3150 +	considered to have failed.
  1.3151 +      </para>
  1.3152 +    </sect2>
  1.3153 +
  1.3154 +    <sect2>
  1.3155 +      <title>Finding out where changesets come from</title>
  1.3156 +
  1.3157 +      <para id="x_285">A hook that involves the transfer of changesets between a
  1.3158 +	local repository and another may be able to find out
  1.3159 +	information about the <quote>far side</quote>.  Mercurial
  1.3160 +	knows <emphasis>how</emphasis> changes are being transferred,
  1.3161 +	and in many cases <emphasis>where</emphasis> they are being
  1.3162 +	transferred to or from.
  1.3163 +      </para>
  1.3164 +
  1.3165 +      <sect3 id="sec:hook:sources">
  1.3166 +	<title>Sources of changesets</title>
  1.3167 +
  1.3168 +	<para id="x_286">Mercurial will tell a hook what means are, or were, used
  1.3169 +	  to transfer changesets between repositories.  This is
  1.3170 +	  provided by Mercurial in a Python parameter named
  1.3171 +	  <literal>source</literal>, or an environment variable named
  1.3172 +	  <envar>HG_SOURCE</envar>.
  1.3173 +	</para>
  1.3174 +
  1.3175 +	<itemizedlist>
  1.3176 +	  <listitem><para id="x_287"><literal>serve</literal>: Changesets are
  1.3177 +	      transferred to or from a remote repository over http or
  1.3178 +	      ssh.
  1.3179 +	    </para>
  1.3180 +	  </listitem>
  1.3181 +	  <listitem><para id="x_288"><literal>pull</literal>: Changesets are
  1.3182 +	      being transferred via a pull from one repository into
  1.3183 +	      another.
  1.3184 +	    </para>
  1.3185 +	  </listitem>
  1.3186 +	  <listitem><para id="x_289"><literal>push</literal>: Changesets are
  1.3187 +	      being transferred via a push from one repository into
  1.3188 +	      another.
  1.3189 +	    </para>
  1.3190 +	  </listitem>
  1.3191 +	  <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are
  1.3192 +	      being transferred to or from a bundle.
  1.3193 +	    </para>
  1.3194 +	  </listitem></itemizedlist>
  1.3195 +      </sect3>
  1.3196 +
  1.3197 +      <sect3 id="sec:hook:url">
  1.3198 +	<title>Where changes are going&emdash;remote repository
  1.3199 +	  URLs</title>
  1.3200 +
  1.3201 +	<para id="x_28b">When possible, Mercurial will tell a hook the location
  1.3202 +	  of the <quote>far side</quote> of an activity that transfers
  1.3203 +	  changeset data between repositories.  This is provided by
  1.3204 +	  Mercurial in a Python parameter named
  1.3205 +	  <literal>url</literal>, or an environment variable named
  1.3206 +	  <envar>HG_URL</envar>.
  1.3207 +	</para>
  1.3208 +
  1.3209 +	<para id="x_28c">This information is not always known.  If a hook is
  1.3210 +	  invoked in a repository that is being served via http or
  1.3211 +	  ssh, Mercurial cannot tell where the remote repository is,
  1.3212 +	  but it may know where the client is connecting from.  In
  1.3213 +	  such cases, the URL will take one of the following forms:
  1.3214 +	</para>
  1.3215 +	<itemizedlist>
  1.3216 +	  <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
  1.3217 +	      ssh client, at the IP address
  1.3218 +	      <literal>1.2.3.4</literal>.
  1.3219 +	    </para>
  1.3220 +	  </listitem>
  1.3221 +	  <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 
  1.3222 +	      http client, at the IP address
  1.3223 +	      <literal>1.2.3.4</literal>.  If the client is using SSL,
  1.3224 +	      this will be of the form
  1.3225 +	      <literal>remote:https:1.2.3.4</literal>.
  1.3226 +	    </para>
  1.3227 +	  </listitem>
  1.3228 +	  <listitem><para id="x_28f">Empty&emdash;no information could be
  1.3229 +	      discovered about the remote client.
  1.3230 +	    </para>
  1.3231 +	  </listitem></itemizedlist>
  1.3232 +      </sect3>
  1.3233 +    </sect2>
  1.3234 +  </sect1>
  1.3235 +  <sect1>
  1.3236 +    <title>Hook reference</title>
  1.3237 +
  1.3238 +    <sect2 id="sec:hook:changegroup">
  1.3239 +      <title><literal role="hook">changegroup</literal>&emdash;after
  1.3240 +	remote changesets added</title>
  1.3241 +
  1.3242 +      <para id="x_290">This hook is run after a group of pre-existing changesets
  1.3243 +	has been added to the repository, for example via a <command
  1.3244 +	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
  1.3245 +	  unbundle</command>.  This hook is run once per operation
  1.3246 +	that added one or more changesets.  This is in contrast to the
  1.3247 +	<literal role="hook">incoming</literal> hook, which is run
  1.3248 +	once per changeset, regardless of whether the changesets
  1.3249 +	arrive in a group.
  1.3250 +      </para>
  1.3251 +
  1.3252 +      <para id="x_291">Some possible uses for this hook include kicking off an
  1.3253 +	automated build or test of the added changesets, updating a
  1.3254 +	bug database, or notifying subscribers that a repository
  1.3255 +	contains new changes.
  1.3256 +      </para>
  1.3257 +
  1.3258 +      <para id="x_292">Parameters to this hook:
  1.3259 +      </para>
  1.3260 +      <itemizedlist>
  1.3261 +	<listitem><para id="x_293"><literal>node</literal>: A changeset ID.  The
  1.3262 +	    changeset ID of the first changeset in the group that was
  1.3263 +	    added.  All changesets between this and
  1.3264 +	    <literal role="tag">tip</literal>, inclusive, were added by a single
  1.3265 +	    <command role="hg-cmd">hg pull</command>, <command
  1.3266 +	      role="hg-cmd">hg push</command> or <command
  1.3267 +	      role="hg-cmd">hg unbundle</command>.
  1.3268 +	  </para>
  1.3269 +	</listitem>
  1.3270 +	<listitem><para id="x_294"><literal>source</literal>: A
  1.3271 +	    string.  The source of these changes.  See <xref
  1.3272 +	      linkend="sec:hook:sources"/> for details.
  1.3273 +	  </para>
  1.3274 +	</listitem>
  1.3275 +	<listitem><para id="x_295"><literal>url</literal>: A URL.  The
  1.3276 +	    location of the remote repository, if known.  See <xref
  1.3277 +	      linkend="sec:hook:url"/> for more information.
  1.3278 +	  </para>
  1.3279 +	</listitem></itemizedlist>
  1.3280 +
  1.3281 +      <para id="x_296">See also: <literal
  1.3282 +	  role="hook">incoming</literal> (<xref
  1.3283 +	  linkend="sec:hook:incoming"/>), <literal
  1.3284 +	  role="hook">prechangegroup</literal> (<xref
  1.3285 +	  linkend="sec:hook:prechangegroup"/>), <literal
  1.3286 +	  role="hook">pretxnchangegroup</literal> (<xref
  1.3287 +	  linkend="sec:hook:pretxnchangegroup"/>)
  1.3288 +      </para>
  1.3289 +    </sect2>
  1.3290 +
  1.3291 +    <sect2 id="sec:hook:commit">
  1.3292 +      <title><literal role="hook">commit</literal>&emdash;after a new
  1.3293 +	changeset is created</title>
  1.3294 +
  1.3295 +      <para id="x_297">This hook is run after a new changeset has been created.
  1.3296 +      </para>
  1.3297 +
  1.3298 +      <para id="x_298">Parameters to this hook:
  1.3299 +      </para>
  1.3300 +      <itemizedlist>
  1.3301 +	<listitem><para id="x_299"><literal>node</literal>: A changeset ID.  The
  1.3302 +	    changeset ID of the newly committed changeset.
  1.3303 +	  </para>
  1.3304 +	</listitem>
  1.3305 +	<listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID.
  1.3306 +	    The changeset ID of the first parent of the newly
  1.3307 +	    committed changeset.
  1.3308 +	  </para>
  1.3309 +	</listitem>
  1.3310 +	<listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID.
  1.3311 +	    The changeset ID of the second parent of the newly
  1.3312 +	    committed changeset.
  1.3313 +	  </para>
  1.3314 +	</listitem></itemizedlist>
  1.3315 +
  1.3316 +      <para id="x_29c">See also: <literal
  1.3317 +	  role="hook">precommit</literal> (<xref
  1.3318 +	  linkend="sec:hook:precommit"/>), <literal
  1.3319 +	  role="hook">pretxncommit</literal> (<xref
  1.3320 +	  linkend="sec:hook:pretxncommit"/>)
  1.3321 +      </para>
  1.3322 +    </sect2>
  1.3323 +
  1.3324 +    <sect2 id="sec:hook:incoming">
  1.3325 +      <title><literal role="hook">incoming</literal>&emdash;after one
  1.3326 +	remote changeset is added</title>
  1.3327 +
  1.3328 +      <para id="x_29d">This hook is run after a pre-existing changeset has been
  1.3329 +	added to the repository, for example via a <command
  1.3330 +	  role="hg-cmd">hg push</command>.  If a group of changesets
  1.3331 +	was added in a single operation, this hook is called once for
  1.3332 +	each added changeset.
  1.3333 +      </para>
  1.3334 +
  1.3335 +      <para id="x_29e">You can use this hook for the same purposes as
  1.3336 +	the <literal role="hook">changegroup</literal> hook (<xref
  1.3337 +	  linkend="sec:hook:changegroup"/>); it's simply more
  1.3338 +	convenient sometimes to run a hook once per group of
  1.3339 +	changesets, while other times it's handier once per changeset.
  1.3340 +      </para>
  1.3341 +
  1.3342 +      <para id="x_29f">Parameters to this hook:
  1.3343 +      </para>
  1.3344 +      <itemizedlist>
  1.3345 +	<listitem><para id="x_2a0"><literal>node</literal>: A changeset ID.  The
  1.3346 +	    ID of the newly added changeset.
  1.3347 +	  </para>
  1.3348 +	</listitem>
  1.3349 +	<listitem><para id="x_2a1"><literal>source</literal>: A
  1.3350 +	    string.  The source of these changes.  See <xref
  1.3351 +	      linkend="sec:hook:sources"/> for details.
  1.3352 +	  </para>
  1.3353 +	</listitem>
  1.3354 +	<listitem><para id="x_2a2"><literal>url</literal>: A URL.  The
  1.3355 +	    location of the remote repository, if known.  See <xref
  1.3356 +	      linkend="sec:hook:url"/> for more information.
  1.3357 +	  </para>
  1.3358 +	</listitem></itemizedlist>
  1.3359 +
  1.3360 +      <para id="x_2a3">See also: <literal
  1.3361 +	  role="hook">changegroup</literal> (<xref
  1.3362 +	  linkend="sec:hook:changegroup"/>) <literal
  1.3363 +	  role="hook">prechangegroup</literal> (<xref
  1.3364 +	  linkend="sec:hook:prechangegroup"/>), <literal
  1.3365 +	  role="hook">pretxnchangegroup</literal> (<xref
  1.3366 +	  linkend="sec:hook:pretxnchangegroup"/>)
  1.3367 +      </para>
  1.3368 +    </sect2>
  1.3369 +
  1.3370 +    <sect2 id="sec:hook:outgoing">
  1.3371 +      <title><literal role="hook">outgoing</literal>&emdash;after
  1.3372 +	changesets are propagated</title>
  1.3373 +
  1.3374 +      <para id="x_2a4">This hook is run after a group of changesets has been
  1.3375 +	propagated out of this repository, for example by a <command
  1.3376 +	  role="hg-cmd">hg push</command> or <command role="hg-cmd">hg
  1.3377 +	  bundle</command> command.
  1.3378 +      </para>
  1.3379 +
  1.3380 +      <para id="x_2a5">One possible use for this hook is to notify administrators
  1.3381 +	that changes have been pulled.
  1.3382 +      </para>
  1.3383 +
  1.3384 +      <para id="x_2a6">Parameters to this hook:
  1.3385 +      </para>
  1.3386 +      <itemizedlist>
  1.3387 +	<listitem><para id="x_2a7"><literal>node</literal>: A changeset ID.  The
  1.3388 +	    changeset ID of the first changeset of the group that was
  1.3389 +	    sent.
  1.3390 +	  </para>
  1.3391 +	</listitem>
  1.3392 +	<listitem><para id="x_2a8"><literal>source</literal>: A string.  The
  1.3393 +	    source of the of the operation (see <xref
  1.3394 +	      linkend="sec:hook:sources"/>).  If a remote
  1.3395 +	    client pulled changes from this repository,
  1.3396 +	    <literal>source</literal> will be
  1.3397 +	    <literal>serve</literal>.  If the client that obtained
  1.3398 +	    changes from this repository was local,
  1.3399 +	    <literal>source</literal> will be
  1.3400 +	    <literal>bundle</literal>, <literal>pull</literal>, or
  1.3401 +	    <literal>push</literal>, depending on the operation the
  1.3402 +	    client performed.
  1.3403 +	  </para>
  1.3404 +	</listitem>
  1.3405 +	<listitem><para id="x_2a9"><literal>url</literal>: A URL.  The
  1.3406 +	    location of the remote repository, if known.  See <xref
  1.3407 +	      linkend="sec:hook:url"/> for more information.
  1.3408 +	  </para>
  1.3409 +	</listitem></itemizedlist>
  1.3410 +
  1.3411 +      <para id="x_2aa">See also: <literal
  1.3412 +	  role="hook">preoutgoing</literal> (<xref
  1.3413 +	  linkend="sec:hook:preoutgoing"/>)
  1.3414 +      </para>
  1.3415 +    </sect2>
  1.3416 +
  1.3417 +    <sect2 id="sec:hook:prechangegroup">
  1.3418 +      <title><literal
  1.3419 +	  role="hook">prechangegroup</literal>&emdash;before starting
  1.3420 +	to add remote changesets</title>
  1.3421 +
  1.3422 +      <para id="x_2ab">This controlling hook is run before Mercurial begins to
  1.3423 +	add a group of changesets from another repository.
  1.3424 +      </para>
  1.3425 +
  1.3426 +      <para id="x_2ac">This hook does not have any information about the
  1.3427 +	changesets to be added, because it is run before transmission
  1.3428 +	of those changesets is allowed to begin.  If this hook fails,
  1.3429 +	the changesets will not be transmitted.
  1.3430 +      </para>
  1.3431 +
  1.3432 +      <para id="x_2ad">One use for this hook is to prevent external changes from
  1.3433 +	being added to a repository.  For example, you could use this
  1.3434 +	to <quote>freeze</quote> a server-hosted branch temporarily or
  1.3435 +	permanently so that users cannot push to it, while still
  1.3436 +	allowing a local administrator to modify the repository.
  1.3437 +      </para>
  1.3438 +
  1.3439 +      <para id="x_2ae">Parameters to this hook:
  1.3440 +      </para>
  1.3441 +      <itemizedlist>
  1.3442 +	<listitem><para id="x_2af"><literal>source</literal>: A string.  The
  1.3443 +	    source of these changes.  See <xref
  1.3444 +	      linkend="sec:hook:sources"/> for details.
  1.3445 +	  </para>
  1.3446 +	</listitem>
  1.3447 +	<listitem><para id="x_2b0"><literal>url</literal>: A URL.  The
  1.3448 +	    location of the remote repository, if known.  See <xref
  1.3449 +	      linkend="sec:hook:url"/> for more information.
  1.3450 +	  </para>
  1.3451 +	</listitem></itemizedlist>
  1.3452 +
  1.3453 +      <para id="x_2b1">See also: <literal
  1.3454 +	  role="hook">changegroup</literal> (<xref
  1.3455 +	  linkend="sec:hook:changegroup"/>), <literal
  1.3456 +	  role="hook">incoming</literal> (<xref
  1.3457 +	  linkend="sec:hook:incoming"/>), <literal
  1.3458 +	  role="hook">pretxnchangegroup</literal> (<xref
  1.3459 +	  linkend="sec:hook:pretxnchangegroup"/>)
  1.3460 +      </para>
  1.3461 +    </sect2>
  1.3462 +
  1.3463 +    <sect2 id="sec:hook:precommit">
  1.3464 +      <title><literal role="hook">precommit</literal>&emdash;before
  1.3465 +	starting to commit a changeset</title>
  1.3466 +
  1.3467 +      <para id="x_2b2">This hook is run before Mercurial begins to commit a new
  1.3468 +	changeset. It is run before Mercurial has any of the metadata
  1.3469 +	for the commit, such as the files to be committed, the commit
  1.3470 +	message, or the commit date.
  1.3471 +      </para>
  1.3472 +
  1.3473 +      <para id="x_2b3">One use for this hook is to disable the ability to commit
  1.3474 +	new changesets, while still allowing incoming changesets.
  1.3475 +	Another is to run a build or test, and only allow the commit
  1.3476 +	to begin if the build or test succeeds.
  1.3477 +      </para>
  1.3478 +
  1.3479 +      <para id="x_2b4">Parameters to this hook:
  1.3480 +      </para>
  1.3481 +      <itemizedlist>
  1.3482 +	<listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID.
  1.3483 +	    The changeset ID of the first parent of the working
  1.3484 +	    directory.
  1.3485 +	  </para>
  1.3486 +	</listitem>
  1.3487 +	<listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID.
  1.3488 +	    The changeset ID of the second parent of the working
  1.3489 +	    directory.
  1.3490 +	  </para>
  1.3491 +	</listitem></itemizedlist>
  1.3492 +      <para id="x_2b7">If the commit proceeds, the parents of the working
  1.3493 +	directory will become the parents of the new changeset.
  1.3494 +      </para>
  1.3495 +
  1.3496 +      <para id="x_2b8">See also: <literal role="hook">commit</literal>
  1.3497 +	(<xref linkend="sec:hook:commit"/>), <literal
  1.3498 +	  role="hook">pretxncommit</literal> (<xref
  1.3499 +	  linkend="sec:hook:pretxncommit"/>)
  1.3500 +      </para>
  1.3501 +    </sect2>
  1.3502 +
  1.3503 +    <sect2 id="sec:hook:preoutgoing">
  1.3504 +      <title><literal role="hook">preoutgoing</literal>&emdash;before
  1.3505 +	starting to propagate changesets</title>
  1.3506 +
  1.3507 +      <para id="x_2b9">This hook is invoked before Mercurial knows the identities
  1.3508 +	of the changesets to be transmitted.
  1.3509 +      </para>
  1.3510 +
  1.3511 +      <para id="x_2ba">One use for this hook is to prevent changes from being
  1.3512 +	transmitted to another repository.
  1.3513 +      </para>
  1.3514 +
  1.3515 +      <para id="x_2bb">Parameters to this hook:
  1.3516 +      </para>
  1.3517 +      <itemizedlist>
  1.3518 +	<listitem><para id="x_2bc"><literal>source</literal>: A
  1.3519 +	    string.  The source of the operation that is attempting to
  1.3520 +	    obtain changes from this repository (see <xref
  1.3521 +	      linkend="sec:hook:sources"/>).  See the documentation
  1.3522 +	    for the <literal>source</literal> parameter to the
  1.3523 +	    <literal role="hook">outgoing</literal> hook, in
  1.3524 +	    <xref linkend="sec:hook:outgoing"/>, for possible values
  1.3525 +	    of this parameter.
  1.3526 +	  </para>
  1.3527 +	</listitem>
  1.3528 +	<listitem><para id="x_2bd"><literal>url</literal>: A URL.  The
  1.3529 +	    location of the remote repository, if known.  See <xref
  1.3530 +	      linkend="sec:hook:url"/> for more information.
  1.3531 +	  </para>
  1.3532 +	</listitem></itemizedlist>
  1.3533 +
  1.3534 +      <para id="x_2be">See also: <literal
  1.3535 +	  role="hook">outgoing</literal> (<xref
  1.3536 +	  linkend="sec:hook:outgoing"/>)
  1.3537 +      </para>
  1.3538 +    </sect2>
  1.3539 +
  1.3540 +    <sect2 id="sec:hook:pretag">
  1.3541 +      <title><literal role="hook">pretag</literal>&emdash;before
  1.3542 +	tagging a changeset</title>
  1.3543 +
  1.3544 +      <para id="x_2bf">This controlling hook is run before a tag is created.  If
  1.3545 +	the hook succeeds, creation of the tag proceeds.  If the hook
  1.3546 +	fails, the tag is not created.
  1.3547 +      </para>
  1.3548 +
  1.3549 +      <para id="x_2c0">Parameters to this hook:
  1.3550 +      </para>
  1.3551 +      <itemizedlist>
  1.3552 +	<listitem><para id="x_2c1"><literal>local</literal>: A boolean.  Whether
  1.3553 +	    the tag is local to this repository instance (i.e. stored
  1.3554 +	    in <filename role="special">.hg/localtags</filename>) or
  1.3555 +	    managed by Mercurial (stored in <filename
  1.3556 +	      role="special">.hgtags</filename>).
  1.3557 +	  </para>
  1.3558 +	</listitem>
  1.3559 +	<listitem><para id="x_2c2"><literal>node</literal>: A changeset ID.  The
  1.3560 +	    ID of the changeset to be tagged.
  1.3561 +	  </para>
  1.3562 +	</listitem>
  1.3563 +	<listitem><para id="x_2c3"><literal>tag</literal>: A string.  The name of
  1.3564 +	    the tag to be created.
  1.3565 +	  </para>
  1.3566 +	</listitem></itemizedlist>
  1.3567 +
  1.3568 +      <para id="x_2c4">If the tag to be created is
  1.3569 +	revision-controlled, the <literal
  1.3570 +	  role="hook">precommit</literal> and <literal
  1.3571 +	  role="hook">pretxncommit</literal> hooks (<xref
  1.3572 +	  linkend="sec:hook:commit"/> and <xref
  1.3573 +	  linkend="sec:hook:pretxncommit"/>) will also be run.
  1.3574 +      </para>
  1.3575 +
  1.3576 +      <para id="x_2c5">See also: <literal role="hook">tag</literal>
  1.3577 +	(<xref linkend="sec:hook:tag"/>)
  1.3578 +      </para>
  1.3579 +    </sect2>
  1.3580 +
  1.3581 +    <sect2 id="sec:hook:pretxnchangegroup">
  1.3582 +      <title><literal
  1.3583 +	  role="hook">pretxnchangegroup</literal>&emdash;before
  1.3584 +	completing addition of remote changesets</title>
  1.3585 +
  1.3586 +      <para id="x_2c6">This controlling hook is run before a
  1.3587 +	transaction&emdash;that manages the addition of a group of new
  1.3588 +	changesets from outside the repository&emdash;completes.  If
  1.3589 +	the hook succeeds, the transaction completes, and all of the
  1.3590 +	changesets become permanent within this repository.  If the
  1.3591 +	hook fails, the transaction is rolled back, and the data for
  1.3592 +	the changesets is erased.
  1.3593 +      </para>
  1.3594 +
  1.3595 +      <para id="x_2c7">This hook can access the metadata associated with the
  1.3596 +	almost-added changesets, but it should not do anything
  1.3597 +	permanent with this data. It must also not modify the working
  1.3598 +	directory.
  1.3599 +      </para>
  1.3600 +
  1.3601 +      <para id="x_2c8">While this hook is running, if other Mercurial processes
  1.3602 +	access this repository, they will be able to see the
  1.3603 +	almost-added changesets as if they are permanent.  This may
  1.3604 +	lead to race conditions if you do not take steps to avoid
  1.3605 +	them.
  1.3606 +      </para>
  1.3607 +
  1.3608 +      <para id="x_2c9">This hook can be used to automatically vet a group of
  1.3609 +	changesets.  If the hook fails, all of the changesets are
  1.3610 +	<quote>rejected</quote> when the transaction rolls back.
  1.3611 +      </para>
  1.3612 +
  1.3613 +      <para id="x_2ca">Parameters to this hook:
  1.3614 +      </para>
  1.3615 +      <itemizedlist>
  1.3616 +	<listitem><para id="x_2cb"><literal>node</literal>: A changeset ID.  The
  1.3617 +	    changeset ID of the first changeset in the group that was
  1.3618 +	    added.  All changesets between this and
  1.3619 +	    <literal role="tag">tip</literal>,
  1.3620 +	    inclusive, were added by a single <command
  1.3621 +	      role="hg-cmd">hg pull</command>, <command
  1.3622 +	      role="hg-cmd">hg push</command> or <command
  1.3623 +	      role="hg-cmd">hg unbundle</command>.
  1.3624 +	  </para>
  1.3625 +	</listitem>
  1.3626 +	<listitem><para id="x_2cc"><literal>source</literal>: A
  1.3627 +	    string.  The source of these changes.  See <xref
  1.3628 +	      linkend="sec:hook:sources"/> for details.
  1.3629 +	  </para>
  1.3630 +	</listitem>
  1.3631 +	<listitem><para id="x_2cd"><literal>url</literal>: A URL.  The
  1.3632 +	    location of the remote repository, if known.  See <xref
  1.3633 +	      linkend="sec:hook:url"/> for more information.
  1.3634 +	  </para>
  1.3635 +	</listitem></itemizedlist>
  1.3636 +
  1.3637 +      <para id="x_2ce">See also: <literal
  1.3638 +	  role="hook">changegroup</literal> (<xref
  1.3639 +	  linkend="sec:hook:changegroup"/>), <literal
  1.3640 +	  role="hook">incoming</literal> (<xref
  1.3641 +	  linkend="sec:hook:incoming"/>), <literal
  1.3642 +	  role="hook">prechangegroup</literal> (<xref
  1.3643 +	  linkend="sec:hook:prechangegroup"/>)
  1.3644 +      </para>
  1.3645 +    </sect2>
  1.3646 +
  1.3647 +    <sect2 id="sec:hook:pretxncommit">
  1.3648 +      <title><literal role="hook">pretxncommit</literal>&emdash;before
  1.3649 +	completing commit of new changeset</title>
  1.3650 +
  1.3651 +      <para id="x_2cf">This controlling hook is run before a
  1.3652 +	transaction&emdash;that manages a new commit&emdash;completes.
  1.3653 +	If the hook succeeds, the transaction completes and the
  1.3654 +	changeset becomes permanent within this repository.  If the
  1.3655 +	hook fails, the transaction is rolled back, and the commit
  1.3656 +	data is erased.
  1.3657 +      </para>
  1.3658 +
  1.3659 +      <para id="x_2d0">This hook can access the metadata associated with the
  1.3660 +	almost-new changeset, but it should not do anything permanent
  1.3661 +	with this data.  It must also not modify the working
  1.3662 +	directory.
  1.3663 +      </para>
  1.3664 +
  1.3665 +      <para id="x_2d1">While this hook is running, if other Mercurial processes
  1.3666 +	access this repository, they will be able to see the
  1.3667 +	almost-new changeset as if it is permanent.  This may lead to
  1.3668 +	race conditions if you do not take steps to avoid them.
  1.3669 +      </para>
  1.3670 +
  1.3671 +      <para id="x_2d2">Parameters to this hook:</para>
  1.3672 +
  1.3673 +      <itemizedlist>
  1.3674 +	<listitem><para id="x_2d3"><literal>node</literal>: A changeset ID.  The
  1.3675 +	    changeset ID of the newly committed changeset.
  1.3676 +	  </para>
  1.3677 +	</listitem>
  1.3678 +	<listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID.
  1.3679 +	    The changeset ID of the first parent of the newly
  1.3680 +	    committed changeset.
  1.3681 +	  </para>
  1.3682 +	</listitem>
  1.3683 +	<listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID.
  1.3684 +	    The changeset ID of the second parent of the newly
  1.3685 +	    committed changeset.
  1.3686 +	  </para>
  1.3687 +	</listitem></itemizedlist>
  1.3688 +
  1.3689 +      <para id="x_2d6">See also: <literal
  1.3690 +	  role="hook">precommit</literal> (<xref
  1.3691 +	  linkend="sec:hook:precommit"/>)
  1.3692 +      </para>
  1.3693 +    </sect2>
  1.3694 +
  1.3695 +    <sect2 id="sec:hook:preupdate">
  1.3696 +      <title><literal role="hook">preupdate</literal>&emdash;before
  1.3697 +	updating or merging working directory</title>
  1.3698 +
  1.3699 +      <para id="x_2d7">This controlling hook is run before an update
  1.3700 +	or merge of the working directory begins.  It is run only if
  1.3701 +	Mercurial's normal pre-update checks determine that the update
  1.3702 +	or merge can proceed.  If the hook succeeds, the update or
  1.3703 +	merge may proceed; if it fails, the update or merge does not
  1.3704 +	start.
  1.3705 +      </para>
  1.3706 +
  1.3707 +      <para id="x_2d8">Parameters to this hook:
  1.3708 +      </para>
  1.3709 +      <itemizedlist>
  1.3710 +	<listitem><para id="x_2d9"><literal>parent1</literal>: A
  1.3711 +	    changeset ID. The ID of the parent that the working
  1.3712 +	    directory is to be updated to.  If the working directory
  1.3713 +	    is being merged, it will not change this parent.
  1.3714 +	  </para>
  1.3715 +	</listitem>
  1.3716 +	<listitem><para id="x_2da"><literal>parent2</literal>: A
  1.3717 +	    changeset ID. Only set if the working directory is being
  1.3718 +	    merged.  The ID of the revision that the working directory
  1.3719 +	    is being merged with.
  1.3720 +	  </para>
  1.3721 +	</listitem></itemizedlist>
  1.3722 +
  1.3723 +      <para id="x_2db">See also: <literal role="hook">update</literal>
  1.3724 +	(<xref linkend="sec:hook:update"/>)</para>
  1.3725 +    </sect2>
  1.3726 +
  1.3727 +    <sect2 id="sec:hook:tag">
  1.3728 +      <title><literal role="hook">tag</literal>&emdash;after tagging a
  1.3729 +	changeset</title>
  1.3730 +
  1.3731 +      <para id="x_2dc">This hook is run after a tag has been created.
  1.3732 +      </para>
  1.3733 +
  1.3734 +      <para id="x_2dd">Parameters to this hook:
  1.3735 +      </para>
  1.3736 +      <itemizedlist>
  1.3737 +	<listitem><para id="x_2de"><literal>local</literal>: A boolean.  Whether
  1.3738 +	    the new tag is local to this repository instance (i.e.
  1.3739 +	    stored in <filename
  1.3740 +	      role="special">.hg/localtags</filename>) or managed by
  1.3741 +	    Mercurial (stored in <filename
  1.3742 +	      role="special">.hgtags</filename>).
  1.3743 +	  </para>
  1.3744 +	</listitem>
  1.3745 +	<listitem><para id="x_2df"><literal>node</literal>: A changeset ID.  The
  1.3746 +	    ID of the changeset that was tagged.
  1.3747 +	  </para>
  1.3748 +	</listitem>
  1.3749 +	<listitem><para id="x_2e0"><literal>tag</literal>: A string.  The name of
  1.3750 +	    the tag that was created.
  1.3751 +	  </para>
  1.3752 +	</listitem></itemizedlist>
  1.3753 +
  1.3754 +      <para id="x_2e1">If the created tag is revision-controlled, the <literal
  1.3755 +	  role="hook">commit</literal> hook (section <xref
  1.3756 +	  linkend="sec:hook:commit"/>) is run before this hook.
  1.3757 +      </para>
  1.3758 +
  1.3759 +      <para id="x_2e2">See also: <literal role="hook">pretag</literal>
  1.3760 +	(<xref linkend="sec:hook:pretag"/>)
  1.3761 +      </para>
  1.3762 +    </sect2>
  1.3763 +
  1.3764 +    <sect2 id="sec:hook:update">
  1.3765 +      <title><literal role="hook">update</literal>&emdash;after
  1.3766 +	updating or merging working directory</title>
  1.3767 +
  1.3768 +      <para id="x_2e3">This hook is run after an update or merge of the working
  1.3769 +	directory completes.  Since a merge can fail (if the external
  1.3770 +	<command>hgmerge</command> command fails to resolve conflicts
  1.3771 +	in a file), this hook communicates whether the update or merge
  1.3772 +	completed cleanly.
  1.3773 +      </para>
  1.3774 +
  1.3775 +      <itemizedlist>
  1.3776 +	<listitem><para id="x_2e4"><literal>error</literal>: A boolean.
  1.3777 +	    Indicates whether the update or merge completed
  1.3778 +	    successfully.
  1.3779 +	  </para>
  1.3780 +	</listitem>
  1.3781 +	<listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID.
  1.3782 +	    The ID of the parent that the working directory was
  1.3783 +	    updated to.  If the working directory was merged, it will
  1.3784 +	    not have changed this parent.
  1.3785 +	  </para>
  1.3786 +	</listitem>
  1.3787 +	<listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID.
  1.3788 +	    Only set if the working directory was merged.  The ID of
  1.3789 +	    the revision that the working directory was merged with.
  1.3790 +	  </para>
  1.3791 +	</listitem></itemizedlist>
  1.3792 +
  1.3793 +      <para id="x_2e7">See also: <literal role="hook">preupdate</literal>
  1.3794 +	(<xref linkend="sec:hook:preupdate"/>)
  1.3795 +      </para>
  1.3796 +
  1.3797 +    </sect2>
  1.3798 +  </sect1>
  1.3799  </chapter>
  1.3800  
  1.3801  <!--
  1.3802  local variables: 
  1.3803  sgml-parent-document: ("00book.xml" "book" "chapter")
  1.3804  end:
  1.3805 --->
  1.3806 \ No newline at end of file
  1.3807 +-->