1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch10-hook.xml	Sun Aug 16 04:58:01 2009 +0200
     1.3 @@ -0,0 +1,1883 @@
     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>
  1.1881 +
  1.1882 +<!--
  1.1883 +local variables: 
  1.1884 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1885 +end:
  1.1886 +-->
  1.1887 \ No newline at end of file