hgbook
diff en/ch10-hook.xml @ 559:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Feb 18 00:22:09 2009 -0800 (2009-02-18) |
parents | en/ch10-hook.tex@5cd47f721686 |
children | 21c62e09b99f |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch10-hook.xml Wed Feb 18 00:22:09 2009 -0800 1.3 @@ -0,0 +1,2067 @@ 1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 + 1.6 +<chapter id="chap:hook"> 1.7 + <title>Handling repository events with hooks</title> 1.8 + 1.9 + <para>Mercurial offers a powerful mechanism to let you perform 1.10 + automated actions in response to events that occur in a 1.11 + repository. In some cases, you can even control Mercurial's 1.12 + response to those events.</para> 1.13 + 1.14 + <para>The name Mercurial uses for one of these actions is a 1.15 + <emphasis>hook</emphasis>. Hooks are called 1.16 + <quote>triggers</quote> in some revision control systems, but the 1.17 + two names refer to the same idea.</para> 1.18 + 1.19 + <sect1> 1.20 + <title>An overview of hooks in Mercurial</title> 1.21 + 1.22 + <para>Here is a brief list of the hooks that Mercurial supports. 1.23 + We will revisit each of these hooks in more detail later, in 1.24 + section <xref linkend="sec:hook:ref"/>.</para> 1.25 + 1.26 + <itemizedlist> 1.27 + <listitem><para><literal role="hook">changegroup</literal>: This 1.28 + is run after a group of changesets has been brought into the 1.29 + repository from elsewhere.</para> 1.30 + </listitem> 1.31 + <listitem><para><literal role="hook">commit</literal>: This is 1.32 + run after a new changeset has been created in the local 1.33 + repository.</para> 1.34 + </listitem> 1.35 + <listitem><para><literal role="hook">incoming</literal>: This is 1.36 + run once for each new changeset that is brought into the 1.37 + repository from elsewhere. Notice the difference from 1.38 + <literal role="hook">changegroup</literal>, which is run 1.39 + once per <emphasis>group</emphasis> of changesets brought 1.40 + in.</para> 1.41 + </listitem> 1.42 + <listitem><para><literal role="hook">outgoing</literal>: This is 1.43 + run after a group of changesets has been transmitted from 1.44 + this repository.</para> 1.45 + </listitem> 1.46 + <listitem><para><literal role="hook">prechangegroup</literal>: 1.47 + This is run before starting to bring a group of changesets 1.48 + into the repository. 1.49 + </para> 1.50 + </listitem> 1.51 + <listitem><para><literal role="hook">precommit</literal>: 1.52 + Controlling. This is run before starting a commit. 1.53 + </para> 1.54 + </listitem> 1.55 + <listitem><para><literal role="hook">preoutgoing</literal>: 1.56 + Controlling. This is run before starting to transmit a group 1.57 + of changesets from this repository. 1.58 + </para> 1.59 + </listitem> 1.60 + <listitem><para><literal role="hook">pretag</literal>: 1.61 + Controlling. This is run before creating a tag. 1.62 + </para> 1.63 + </listitem> 1.64 + <listitem><para><literal 1.65 + role="hook">pretxnchangegroup</literal>: Controlling. This 1.66 + is run after a group of changesets has been brought into the 1.67 + local repository from another, but before the transaction 1.68 + completes that will make the changes permanent in the 1.69 + repository. 1.70 + </para> 1.71 + </listitem> 1.72 + <listitem><para><literal role="hook">pretxncommit</literal>: 1.73 + Controlling. This is run after a new changeset has been 1.74 + created in the local repository, but before the transaction 1.75 + completes that will make it permanent. 1.76 + </para> 1.77 + </listitem> 1.78 + <listitem><para><literal role="hook">preupdate</literal>: 1.79 + Controlling. This is run before starting an update or merge 1.80 + of the working directory. 1.81 + </para> 1.82 + </listitem> 1.83 + <listitem><para><literal role="hook">tag</literal>: This is run 1.84 + after a tag is created. 1.85 + </para> 1.86 + </listitem> 1.87 + <listitem><para><literal role="hook">update</literal>: This is 1.88 + run after an update or merge of the working directory has 1.89 + finished. 1.90 + </para> 1.91 + </listitem></itemizedlist> 1.92 + <para>Each of the hooks whose description begins with the word 1.93 + <quote>Controlling</quote> has the ability to determine whether 1.94 + an activity can proceed. If the hook succeeds, the activity may 1.95 + proceed; if it fails, the activity is either not permitted or 1.96 + undone, depending on the hook. 1.97 + </para> 1.98 + 1.99 + </sect1> 1.100 + <sect1> 1.101 + <title>Hooks and security</title> 1.102 + 1.103 + <sect2> 1.104 + <title>Hooks are run with your privileges</title> 1.105 + 1.106 + <para>When you run a Mercurial command in a repository, and the 1.107 + command causes a hook to run, that hook runs on 1.108 + <emphasis>your</emphasis> system, under 1.109 + <emphasis>your</emphasis> user account, with 1.110 + <emphasis>your</emphasis> privilege level. Since hooks are 1.111 + arbitrary pieces of executable code, you should treat them 1.112 + with an appropriate level of suspicion. Do not install a hook 1.113 + unless you are confident that you know who created it and what 1.114 + it does. 1.115 + </para> 1.116 + 1.117 + <para>In some cases, you may be exposed to hooks that you did 1.118 + not install yourself. If you work with Mercurial on an 1.119 + unfamiliar system, Mercurial will run hooks defined in that 1.120 + system's global <filename role="special"> /.hgrc</filename>\ 1.121 + file. 1.122 + </para> 1.123 + 1.124 + <para>If you are working with a repository owned by another 1.125 + user, Mercurial can run hooks defined in that user's 1.126 + repository, but it will still run them as <quote>you</quote>. 1.127 + For example, if you <command role="hg-cmd">hg pull</command> 1.128 + from that repository, and its <filename 1.129 + role="special">.hg/hgrc</filename> defines a local <literal 1.130 + role="hook">outgoing</literal> hook, that hook will run 1.131 + under your user account, even though you don't own that 1.132 + repository. 1.133 + </para> 1.134 + 1.135 + <note> 1.136 + <para> This only applies if you are pulling from a repository 1.137 + on a local or network filesystem. If you're pulling over 1.138 + http or ssh, any <literal role="hook">outgoing</literal> 1.139 + hook will run under whatever account is executing the server 1.140 + process, on the server. 1.141 + </para> 1.142 + </note> 1.143 + 1.144 + <para>XXX To see what hooks are defined in a repository, use the 1.145 + <command role="hg-cmd">hg config hooks</command> command. If 1.146 + you are working in one repository, but talking to another that 1.147 + you do not own (e.g. using <command role="hg-cmd">hg 1.148 + pull</command> or <command role="hg-cmd">hg 1.149 + incoming</command>), remember that it is the other 1.150 + repository's hooks you should be checking, not your own. 1.151 + </para> 1.152 + 1.153 + </sect2> 1.154 + <sect2> 1.155 + <title>Hooks do not propagate</title> 1.156 + 1.157 + <para>In Mercurial, hooks are not revision controlled, and do 1.158 + not propagate when you clone, or pull from, a repository. The 1.159 + reason for this is simple: a hook is a completely arbitrary 1.160 + piece of executable code. It runs under your user identity, 1.161 + with your privilege level, on your machine. 1.162 + </para> 1.163 + 1.164 + <para>It would be extremely reckless for any distributed 1.165 + revision control system to implement revision-controlled 1.166 + hooks, as this would offer an easily exploitable way to 1.167 + subvert the accounts of users of the revision control system. 1.168 + </para> 1.169 + 1.170 + <para>Since Mercurial does not propagate hooks, if you are 1.171 + collaborating with other people on a common project, you 1.172 + should not assume that they are using the same Mercurial hooks 1.173 + as you are, or that theirs are correctly configured. You 1.174 + should document the hooks you expect people to use. 1.175 + </para> 1.176 + 1.177 + <para>In a corporate intranet, this is somewhat easier to 1.178 + control, as you can for example provide a 1.179 + <quote>standard</quote> installation of Mercurial on an NFS 1.180 + filesystem, and use a site-wide <filename role="special"> 1.181 + /.hgrc</filename>\ file to define hooks that all users will 1.182 + see. However, this too has its limits; see below. 1.183 + </para> 1.184 + 1.185 + </sect2> 1.186 + <sect2> 1.187 + <title>Hooks can be overridden</title> 1.188 + 1.189 + <para>Mercurial allows you to override a hook definition by 1.190 + redefining the hook. You can disable it by setting its value 1.191 + to the empty string, or change its behaviour as you wish. 1.192 + </para> 1.193 + 1.194 + <para>If you deploy a system- or site-wide <filename 1.195 + role="special"> /.hgrc</filename>\ file that defines some 1.196 + hooks, you should thus understand that your users can disable 1.197 + or override those hooks. 1.198 + </para> 1.199 + 1.200 + </sect2> 1.201 + <sect2> 1.202 + <title>Ensuring that critical hooks are run</title> 1.203 + 1.204 + <para>Sometimes you may want to enforce a policy that you do not 1.205 + want others to be able to work around. For example, you may 1.206 + have a requirement that every changeset must pass a rigorous 1.207 + set of tests. Defining this requirement via a hook in a 1.208 + site-wide <filename role="special"> /.hgrc</filename>\ won't 1.209 + work for remote users on laptops, and of course local users 1.210 + can subvert it at will by overriding the hook. 1.211 + </para> 1.212 + 1.213 + <para>Instead, you can set up your policies for use of Mercurial 1.214 + so that people are expected to propagate changes through a 1.215 + well-known <quote>canonical</quote> server that you have 1.216 + locked down and configured appropriately. 1.217 + </para> 1.218 + 1.219 + <para>One way to do this is via a combination of social 1.220 + engineering and technology. Set up a restricted-access 1.221 + account; users can push changes over the network to 1.222 + repositories managed by this account, but they cannot log into 1.223 + the account and run normal shell commands. In this scenario, 1.224 + a user can commit a changeset that contains any old garbage 1.225 + they want. 1.226 + </para> 1.227 + 1.228 + <para>When someone pushes a changeset to the server that 1.229 + everyone pulls from, the server will test the changeset before 1.230 + it accepts it as permanent, and reject it if it fails to pass 1.231 + the test suite. If people only pull changes from this 1.232 + filtering server, it will serve to ensure that all changes 1.233 + that people pull have been automatically vetted. 1.234 + </para> 1.235 + 1.236 + </sect2> 1.237 + </sect1> 1.238 + <sect1> 1.239 + <title>Care with <literal>pretxn</literal> hooks in a 1.240 + shared-access repository</title> 1.241 + 1.242 + <para>If you want to use hooks to do some automated work in a 1.243 + repository that a number of people have shared access to, you 1.244 + need to be careful in how you do this. 1.245 + </para> 1.246 + 1.247 + <para>Mercurial only locks a repository when it is writing to the 1.248 + repository, and only the parts of Mercurial that write to the 1.249 + repository pay attention to locks. Write locks are necessary to 1.250 + prevent multiple simultaneous writers from scribbling on each 1.251 + other's work, corrupting the repository. 1.252 + </para> 1.253 + 1.254 + <para>Because Mercurial is careful with the order in which it 1.255 + reads and writes data, it does not need to acquire a lock when 1.256 + it wants to read data from the repository. The parts of 1.257 + Mercurial that read from the repository never pay attention to 1.258 + locks. This lockless reading scheme greatly increases 1.259 + performance and concurrency. 1.260 + </para> 1.261 + 1.262 + <para>With great performance comes a trade-off, though, one which 1.263 + has the potential to cause you trouble unless you're aware of 1.264 + it. To describe this requires a little detail about how 1.265 + Mercurial adds changesets to a repository and reads those 1.266 + changes. 1.267 + </para> 1.268 + 1.269 + <para>When Mercurial <emphasis>writes</emphasis> metadata, it 1.270 + writes it straight into the destination file. It writes file 1.271 + data first, then manifest data (which contains pointers to the 1.272 + new file data), then changelog data (which contains pointers to 1.273 + the new manifest data). Before the first write to each file, it 1.274 + stores a record of where the end of the file was in its 1.275 + transaction log. If the transaction must be rolled back, 1.276 + Mercurial simply truncates each file back to the size it was 1.277 + before the transaction began. 1.278 + </para> 1.279 + 1.280 + <para>When Mercurial <emphasis>reads</emphasis> metadata, it reads 1.281 + the changelog first, then everything else. Since a reader will 1.282 + only access parts of the manifest or file metadata that it can 1.283 + see in the changelog, it can never see partially written data. 1.284 + </para> 1.285 + 1.286 + <para>Some controlling hooks (<literal 1.287 + role="hook">pretxncommit</literal> and <literal 1.288 + role="hook">pretxnchangegroup</literal>) run when a 1.289 + transaction is almost complete. All of the metadata has been 1.290 + written, but Mercurial can still roll the transaction back and 1.291 + cause the newly-written data to disappear. 1.292 + </para> 1.293 + 1.294 + <para>If one of these hooks runs for long, it opens a window of 1.295 + time during which a reader can see the metadata for changesets 1.296 + that are not yet permanent, and should not be thought of as 1.297 + <quote>really there</quote>. The longer the hook runs, the 1.298 + longer that window is open. 1.299 + </para> 1.300 + 1.301 + <sect2> 1.302 + <title>The problem illustrated</title> 1.303 + 1.304 + <para>In principle, a good use for the <literal 1.305 + role="hook">pretxnchangegroup</literal> hook would be to 1.306 + automatically build and test incoming changes before they are 1.307 + accepted into a central repository. This could let you 1.308 + guarantee that nobody can push changes to this repository that 1.309 + <quote>break the build</quote>. But if a client can pull 1.310 + changes while they're being tested, the usefulness of the test 1.311 + is zero; an unsuspecting someone can pull untested changes, 1.312 + potentially breaking their build. 1.313 + </para> 1.314 + 1.315 + <para>The safest technological answer to this challenge is to 1.316 + set up such a <quote>gatekeeper</quote> repository as 1.317 + <emphasis>unidirectional</emphasis>. Let it take changes 1.318 + pushed in from the outside, but do not allow anyone to pull 1.319 + changes from it (use the <literal 1.320 + role="hook">preoutgoing</literal> hook to lock it down). 1.321 + Configure a <literal role="hook">changegroup</literal> hook so 1.322 + that if a build or test succeeds, the hook will push the new 1.323 + changes out to another repository that people 1.324 + <emphasis>can</emphasis> pull from. 1.325 + </para> 1.326 + 1.327 + <para>In practice, putting a centralised bottleneck like this in 1.328 + place is not often a good idea, and transaction visibility has 1.329 + nothing to do with the problem. As the size of a 1.330 + project&emdash;and the time it takes to build and 1.331 + test&emdash;grows, you rapidly run into a wall with this 1.332 + <quote>try before you buy</quote> approach, where you have 1.333 + more changesets to test than time in which to deal with them. 1.334 + The inevitable result is frustration on the part of all 1.335 + involved. 1.336 + </para> 1.337 + 1.338 + <para>An approach that scales better is to get people to build 1.339 + and test before they push, then run automated builds and tests 1.340 + centrally <emphasis>after</emphasis> a push, to be sure all is 1.341 + well. The advantage of this approach is that it does not 1.342 + impose a limit on the rate at which the repository can accept 1.343 + changes. 1.344 + </para> 1.345 + 1.346 + </sect2> 1.347 + </sect1> 1.348 + <sect1 id="sec:hook:simple"> 1.349 + <title>A short tutorial on using hooks</title> 1.350 + 1.351 + <para>It is easy to write a Mercurial hook. Let's start with a 1.352 + hook that runs when you finish a <command role="hg-cmd">hg 1.353 + commit</command>, and simply prints the hash of the changeset 1.354 + you just created. The hook is called <literal 1.355 + role="hook">commit</literal>. 1.356 + </para> 1.357 + 1.358 + <para>All hooks follow the pattern in this example.</para> 1.359 + 1.360 +<!-- &interaction.hook.simple.init; --> 1.361 + 1.362 + <para>You add an entry to the <literal 1.363 + role="rc-hooks">hooks</literal> section of your <filename 1.364 + role="special"> /.hgrc</filename>. On the left is the name of 1.365 + the event to trigger on; on the right is the action to take. As 1.366 + you can see, you can run an arbitrary shell command in a hook. 1.367 + Mercurial passes extra information to the hook using environment 1.368 + variables (look for <envar>HG_NODE</envar> in the example). 1.369 + </para> 1.370 + 1.371 + <sect2> 1.372 + <title>Performing multiple actions per event</title> 1.373 + 1.374 + <para>Quite often, you will want to define more than one hook 1.375 + for a particular kind of event, as shown below.</para> 1.376 + 1.377 +<!-- &interaction.hook.simple.ext; --> 1.378 + 1.379 + <para>Mercurial lets you do this by adding an 1.380 + <emphasis>extension</emphasis> to the end of a hook's name. 1.381 + You extend a hook's name by giving the name of the hook, 1.382 + followed by a full stop (the 1.383 + <quote><literal>.</literal></quote> character), followed by 1.384 + some more text of your choosing. For example, Mercurial will 1.385 + run both <literal>commit.foo</literal> and 1.386 + <literal>commit.bar</literal> when the 1.387 + <literal>commit</literal> event occurs. 1.388 + </para> 1.389 + 1.390 + <para>To give a well-defined order of execution when there are 1.391 + multiple hooks defined for an event, Mercurial sorts hooks by 1.392 + extension, and executes the hook commands in this sorted 1.393 + order. In the above example, it will execute 1.394 + <literal>commit.bar</literal> before 1.395 + <literal>commit.foo</literal>, and <literal>commit</literal> 1.396 + before both. 1.397 + </para> 1.398 + 1.399 + <para>It is a good idea to use a somewhat descriptive extension 1.400 + when you define a new hook. This will help you to remember 1.401 + what the hook was for. If the hook fails, you'll get an error 1.402 + message that contains the hook name and extension, so using a 1.403 + descriptive extension could give you an immediate hint as to 1.404 + why the hook failed (see section <xref 1.405 + linkend="sec:hook:perm"/> for an example). 1.406 + </para> 1.407 + 1.408 + </sect2> 1.409 + <sect2 id="sec:hook:perm"> 1.410 + <title>Controlling whether an activity can proceed</title> 1.411 + 1.412 + <para>In our earlier examples, we used the <literal 1.413 + role="hook">commit</literal> hook, which is run after a 1.414 + commit has completed. This is one of several Mercurial hooks 1.415 + that run after an activity finishes. Such hooks have no way 1.416 + of influencing the activity itself. 1.417 + </para> 1.418 + 1.419 + <para>Mercurial defines a number of events that occur before an 1.420 + activity starts; or after it starts, but before it finishes. 1.421 + Hooks that trigger on these events have the added ability to 1.422 + choose whether the activity can continue, or will abort. 1.423 + </para> 1.424 + 1.425 + <para>The <literal role="hook">pretxncommit</literal> hook runs 1.426 + after a commit has all but completed. In other words, the 1.427 + metadata representing the changeset has been written out to 1.428 + disk, but the transaction has not yet been allowed to 1.429 + complete. The <literal role="hook">pretxncommit</literal> 1.430 + hook has the ability to decide whether the transaction can 1.431 + complete, or must be rolled back. 1.432 + </para> 1.433 + 1.434 + <para>If the <literal role="hook">pretxncommit</literal> hook 1.435 + exits with a status code of zero, the transaction is allowed 1.436 + to complete; the commit finishes; and the <literal 1.437 + role="hook">commit</literal> hook is run. If the <literal 1.438 + role="hook">pretxncommit</literal> hook exits with a 1.439 + non-zero status code, the transaction is rolled back; the 1.440 + metadata representing the changeset is erased; and the 1.441 + <literal role="hook">commit</literal> hook is not run. 1.442 + </para> 1.443 + 1.444 +<!-- &interaction.hook.simple.pretxncommit; --> 1.445 + 1.446 + <para>The hook in the example above checks that a commit comment 1.447 + contains a bug ID. If it does, the commit can complete. If 1.448 + not, the commit is rolled back. 1.449 + </para> 1.450 + 1.451 + </sect2> 1.452 + </sect1> 1.453 + <sect1> 1.454 + <title>Writing your own hooks</title> 1.455 + 1.456 + <para>When you are writing a hook, you might find it useful to run 1.457 + Mercurial either with the <option 1.458 + role="hg-opt-global">-v</option> option, or the <envar 1.459 + role="rc-item-ui">verbose</envar> config item set to 1.460 + <quote>true</quote>. When you do so, Mercurial will print a 1.461 + message before it calls each hook. 1.462 + </para> 1.463 + 1.464 + <sect2 id="sec:hook:lang"> 1.465 + <title>Choosing how your hook should run</title> 1.466 + 1.467 + <para>You can write a hook either as a normal 1.468 + program&emdash;typically a shell script&emdash;or as a Python 1.469 + function that is executed within the Mercurial process. 1.470 + </para> 1.471 + 1.472 + <para>Writing a hook as an external program has the advantage 1.473 + that it requires no knowledge of Mercurial's internals. You 1.474 + can call normal Mercurial commands to get any added 1.475 + information you need. The trade-off is that external hooks 1.476 + are slower than in-process hooks. 1.477 + </para> 1.478 + 1.479 + <para>An in-process Python hook has complete access to the 1.480 + Mercurial API, and does not <quote>shell out</quote> to 1.481 + another process, so it is inherently faster than an external 1.482 + hook. It is also easier to obtain much of the information 1.483 + that a hook requires by using the Mercurial API than by 1.484 + running Mercurial commands. 1.485 + </para> 1.486 + 1.487 + <para>If you are comfortable with Python, or require high 1.488 + performance, writing your hooks in Python may be a good 1.489 + choice. However, when you have a straightforward hook to 1.490 + write and you don't need to care about performance (probably 1.491 + the majority of hooks), a shell script is perfectly fine. 1.492 + </para> 1.493 + 1.494 + </sect2> 1.495 + <sect2 id="sec:hook:param"> 1.496 + <title>Hook parameters</title> 1.497 + 1.498 + <para>Mercurial calls each hook with a set of well-defined 1.499 + parameters. In Python, a parameter is passed as a keyword 1.500 + argument to your hook function. For an external program, a 1.501 + parameter is passed as an environment variable. 1.502 + </para> 1.503 + 1.504 + <para>Whether your hook is written in Python or as a shell 1.505 + script, the hook-specific parameter names and values will be 1.506 + the same. A boolean parameter will be represented as a 1.507 + boolean value in Python, but as the number 1 (for 1.508 + <quote>true</quote>) or 0 (for <quote>false</quote>) as an 1.509 + environment variable for an external hook. If a hook 1.510 + parameter is named <literal>foo</literal>, the keyword 1.511 + argument for a Python hook will also be named 1.512 + <literal>foo</literal>, while the environment variable for an 1.513 + external hook will be named <literal>HG_FOO</literal>. 1.514 + </para> 1.515 + 1.516 + </sect2> 1.517 + <sect2> 1.518 + <title>Hook return values and activity control</title> 1.519 + 1.520 + <para>A hook that executes successfully must exit with a status 1.521 + of zero if external, or return boolean <quote>false</quote> if 1.522 + in-process. Failure is indicated with a non-zero exit status 1.523 + from an external hook, or an in-process hook returning boolean 1.524 + <quote>true</quote>. If an in-process hook raises an 1.525 + exception, the hook is considered to have failed. 1.526 + </para> 1.527 + 1.528 + <para>For a hook that controls whether an activity can proceed, 1.529 + zero/false means <quote>allow</quote>, while 1.530 + non-zero/true/exception means <quote>deny</quote>. 1.531 + </para> 1.532 + 1.533 + </sect2> 1.534 + <sect2> 1.535 + <title>Writing an external hook</title> 1.536 + 1.537 + <para>When you define an external hook in your <filename 1.538 + role="special"> /.hgrc</filename>\ and the hook is run, its 1.539 + value is passed to your shell, which interprets it. This 1.540 + means that you can use normal shell constructs in the body of 1.541 + the hook. 1.542 + </para> 1.543 + 1.544 + <para>An executable hook is always run with its current 1.545 + directory set to a repository's root directory. 1.546 + </para> 1.547 + 1.548 + <para>Each hook parameter is passed in as an environment 1.549 + variable; the name is upper-cased, and prefixed with the 1.550 + string <quote><literal>HG_</literal></quote>. 1.551 + </para> 1.552 + 1.553 + <para>With the exception of hook parameters, Mercurial does not 1.554 + set or modify any environment variables when running a hook. 1.555 + This is useful to remember if you are writing a site-wide hook 1.556 + that may be run by a number of different users with differing 1.557 + environment variables set. In multi-user situations, you 1.558 + should not rely on environment variables being set to the 1.559 + values you have in your environment when testing the hook. 1.560 + </para> 1.561 + 1.562 + </sect2> 1.563 + <sect2> 1.564 + <title>Telling Mercurial to use an in-process hook</title> 1.565 + 1.566 + <para>The <filename role="special"> /.hgrc</filename>\ syntax 1.567 + for defining an in-process hook is slightly different than for 1.568 + an executable hook. The value of the hook must start with the 1.569 + text <quote><literal>python:</literal></quote>, and continue 1.570 + with the fully-qualified name of a callable object to use as 1.571 + the hook's value. 1.572 + </para> 1.573 + 1.574 + <para>The module in which a hook lives is automatically imported 1.575 + when a hook is run. So long as you have the module name and 1.576 + <envar>PYTHONPATH</envar> right, it should <quote>just 1.577 + work</quote>. 1.578 + </para> 1.579 + 1.580 + <para>The following <filename role="special"> /.hgrc</filename>\ 1.581 + example snippet illustrates the syntax and meaning of the 1.582 + notions we just described. 1.583 + </para> 1.584 + <programlisting>[hooks] commit.example = 1.585 + python:mymodule.submodule.myhook</programlisting> 1.586 + <para>When Mercurial runs the <literal>commit.example</literal> 1.587 + hook, it imports <literal>mymodule.submodule</literal>, looks 1.588 + for the callable object named <literal>myhook</literal>, and 1.589 + calls it. 1.590 + </para> 1.591 + 1.592 + </sect2> 1.593 + <sect2> 1.594 + <title>Writing an in-process hook</title> 1.595 + 1.596 + <para>The simplest in-process hook does nothing, but illustrates 1.597 + the basic shape of the hook API: 1.598 + </para> 1.599 + <programlisting>def myhook(ui, repo, **kwargs): 1.600 + pass</programlisting> 1.601 + <para>The first argument to a Python hook is always a <literal 1.602 + role="py-mod-mercurial.ui">ui</literal> object. The second 1.603 + is a repository object; at the moment, it is always an 1.604 + instance of <literal 1.605 + role="py-mod-mercurial.localrepo">localrepository</literal>. 1.606 + Following these two arguments are other keyword arguments. 1.607 + Which ones are passed in depends on the hook being called, but 1.608 + a hook can ignore arguments it doesn't care about by dropping 1.609 + them into a keyword argument dict, as with 1.610 + <literal>**kwargs</literal> above. 1.611 + </para> 1.612 + 1.613 + </sect2> 1.614 + </sect1> 1.615 + <sect1> 1.616 + <title>Some hook examples</title> 1.617 + 1.618 + <sect2> 1.619 + <title>Writing meaningful commit messages</title> 1.620 + 1.621 + <para>It's hard to imagine a useful commit message being very 1.622 + short. The simple <literal role="hook">pretxncommit</literal> 1.623 + hook of the example below will prevent you from committing a 1.624 + changeset with a message that is less than ten bytes long. 1.625 + </para> 1.626 + 1.627 +<!-- &interaction.hook.msglen.go; --> 1.628 + 1.629 + </sect2> 1.630 + <sect2> 1.631 + <title>Checking for trailing whitespace</title> 1.632 + 1.633 + <para>An interesting use of a commit-related hook is to help you 1.634 + to write cleaner code. A simple example of <quote>cleaner 1.635 + code</quote> is the dictum that a change should not add any 1.636 + new lines of text that contain <quote>trailing 1.637 + whitespace</quote>. Trailing whitespace is a series of 1.638 + space and tab characters at the end of a line of text. In 1.639 + most cases, trailing whitespace is unnecessary, invisible 1.640 + noise, but it is occasionally problematic, and people often 1.641 + prefer to get rid of it. 1.642 + </para> 1.643 + 1.644 + <para>You can use either the <literal 1.645 + role="hook">precommit</literal> or <literal 1.646 + role="hook">pretxncommit</literal> hook to tell whether you 1.647 + have a trailing whitespace problem. If you use the <literal 1.648 + role="hook">precommit</literal> hook, the hook will not know 1.649 + which files you are committing, so it will have to check every 1.650 + modified file in the repository for trailing white space. If 1.651 + you want to commit a change to just the file 1.652 + <filename>foo</filename>, but the file 1.653 + <filename>bar</filename> contains trailing whitespace, doing a 1.654 + check in the <literal role="hook">precommit</literal> hook 1.655 + will prevent you from committing <filename>foo</filename> due 1.656 + to the problem with <filename>bar</filename>. This doesn't 1.657 + seem right. 1.658 + </para> 1.659 + 1.660 + <para>Should you choose the <literal 1.661 + role="hook">pretxncommit</literal> hook, the check won't 1.662 + occur until just before the transaction for the commit 1.663 + completes. This will allow you to check for problems only the 1.664 + exact files that are being committed. However, if you entered 1.665 + the commit message interactively and the hook fails, the 1.666 + transaction will roll back; you'll have to re-enter the commit 1.667 + message after you fix the trailing whitespace and run <command 1.668 + role="hg-cmd">hg commit</command> again. 1.669 + </para> 1.670 + 1.671 +<!-- &interaction.hook.ws.simple; --> 1.672 + 1.673 + <para>In this example, we introduce a simple <literal 1.674 + role="hook">pretxncommit</literal> hook that checks for 1.675 + trailing whitespace. This hook is short, but not very 1.676 + helpful. It exits with an error status if a change adds a 1.677 + line with trailing whitespace to any file, but does not print 1.678 + any information that might help us to identify the offending 1.679 + file or line. It also has the nice property of not paying 1.680 + attention to unmodified lines; only lines that introduce new 1.681 + trailing whitespace cause problems. 1.682 + </para> 1.683 + 1.684 + <para>The above version is much more complex, but also more 1.685 + useful. It parses a unified diff to see if any lines add 1.686 + trailing whitespace, and prints the name of the file and the 1.687 + line number of each such occurrence. Even better, if the 1.688 + change adds trailing whitespace, this hook saves the commit 1.689 + comment and prints the name of the save file before exiting 1.690 + and telling Mercurial to roll the transaction back, so you can 1.691 + use the <option role="hg-opt-commit">-l filename</option> 1.692 + option to <command role="hg-cmd">hg commit</command> to reuse 1.693 + the saved commit message once you've corrected the problem. 1.694 + </para> 1.695 + 1.696 +<!-- &interaction.hook.ws.better; --> 1.697 + 1.698 + <para>As a final aside, note in the example above the use of 1.699 + <command>perl</command>'s in-place editing feature to get rid 1.700 + of trailing whitespace from a file. This is concise and 1.701 + useful enough that I will reproduce it here. 1.702 + </para> 1.703 + <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> 1.704 + 1.705 + </sect2> 1.706 + </sect1> 1.707 + <sect1> 1.708 + <title>Bundled hooks</title> 1.709 + 1.710 + <para>Mercurial ships with several bundled hooks. You can find 1.711 + them in the <filename class="directory">hgext</filename> 1.712 + directory of a Mercurial source tree. If you are using a 1.713 + Mercurial binary package, the hooks will be located in the 1.714 + <filename class="directory">hgext</filename> directory of 1.715 + wherever your package installer put Mercurial. 1.716 + </para> 1.717 + 1.718 + <sect2> 1.719 + <title><literal role="hg-ext">acl</literal>&emdash;access 1.720 + control for parts of a repository</title> 1.721 + 1.722 + <para>The <literal role="hg-ext">acl</literal> extension lets 1.723 + you control which remote users are allowed to push changesets 1.724 + to a networked server. You can protect any portion of a 1.725 + repository (including the entire repo), so that a specific 1.726 + remote user can push changes that do not affect the protected 1.727 + portion. 1.728 + </para> 1.729 + 1.730 + <para>This extension implements access control based on the 1.731 + identity of the user performing a push, 1.732 + <emphasis>not</emphasis> on who committed the changesets 1.733 + they're pushing. It makes sense to use this hook only if you 1.734 + have a locked-down server environment that authenticates 1.735 + remote users, and you want to be sure that only specific users 1.736 + are allowed to push changes to that server. 1.737 + </para> 1.738 + 1.739 + <sect3> 1.740 + <title>Configuring the <literal role="hook">acl</literal> 1.741 + hook</title> 1.742 + 1.743 + <para>In order to manage incoming changesets, the <literal 1.744 + role="hg-ext">acl</literal> hook must be used as a 1.745 + <literal role="hook">pretxnchangegroup</literal> hook. This 1.746 + lets it see which files are modified by each incoming 1.747 + changeset, and roll back a group of changesets if they 1.748 + modify <quote>forbidden</quote> files. Example: 1.749 + </para> 1.750 + <programlisting>[hooks] pretxnchangegroup.acl = 1.751 + python:hgext.acl.hook</programlisting> 1.752 + 1.753 + <para>The <literal role="hg-ext">acl</literal> extension is 1.754 + configured using three sections. 1.755 + </para> 1.756 + 1.757 + <para>The <literal role="rc-acl">acl</literal> section has 1.758 + only one entry, <envar role="rc-item-acl">sources</envar>, 1.759 + which lists the sources of incoming changesets that the hook 1.760 + should pay attention to. You don't normally need to 1.761 + configure this section. 1.762 + </para> 1.763 + <itemizedlist> 1.764 + <listitem><para><envar role="rc-item-acl">serve</envar>: 1.765 + Control incoming changesets that are arriving from a 1.766 + remote repository over http or ssh. This is the default 1.767 + value of <envar role="rc-item-acl">sources</envar>, and 1.768 + usually the only setting you'll need for this 1.769 + configuration item. 1.770 + </para> 1.771 + </listitem> 1.772 + <listitem><para><envar role="rc-item-acl">pull</envar>: 1.773 + Control incoming changesets that are arriving via a pull 1.774 + from a local repository. 1.775 + </para> 1.776 + </listitem> 1.777 + <listitem><para><envar role="rc-item-acl">push</envar>: 1.778 + Control incoming changesets that are arriving via a push 1.779 + from a local repository. 1.780 + </para> 1.781 + </listitem> 1.782 + <listitem><para><envar role="rc-item-acl">bundle</envar>: 1.783 + Control incoming changesets that are arriving from 1.784 + another repository via a bundle. 1.785 + </para> 1.786 + </listitem></itemizedlist> 1.787 + 1.788 + <para>The <literal role="rc-acl.allow">acl.allow</literal> 1.789 + section controls the users that are allowed to add 1.790 + changesets to the repository. If this section is not 1.791 + present, all users that are not explicitly denied are 1.792 + allowed. If this section is present, all users that are not 1.793 + explicitly allowed are denied (so an empty section means 1.794 + that all users are denied). 1.795 + </para> 1.796 + 1.797 + <para>The <literal role="rc-acl.deny">acl.deny</literal> 1.798 + section determines which users are denied from adding 1.799 + changesets to the repository. If this section is not 1.800 + present or is empty, no users are denied. 1.801 + </para> 1.802 + 1.803 + <para>The syntaxes for the <literal 1.804 + role="rc-acl.allow">acl.allow</literal> and <literal 1.805 + role="rc-acl.deny">acl.deny</literal> sections are 1.806 + identical. On the left of each entry is a glob pattern that 1.807 + matches files or directories, relative to the root of the 1.808 + repository; on the right, a user name. 1.809 + </para> 1.810 + 1.811 + <para>In the following example, the user 1.812 + <literal>docwriter</literal> can only push changes to the 1.813 + <filename class="directory">docs</filename> subtree of the 1.814 + repository, while <literal>intern</literal> can push changes 1.815 + to any file or directory except <filename 1.816 + class="directory">source/sensitive</filename>. 1.817 + </para> 1.818 + <programlisting>[acl.allow] docs/** = docwriter [acl.deny] 1.819 + source/sensitive/** = intern</programlisting> 1.820 + 1.821 + </sect3> 1.822 + <sect3> 1.823 + <title>Testing and troubleshooting</title> 1.824 + 1.825 + <para>If you want to test the <literal 1.826 + role="hg-ext">acl</literal> hook, run it with Mercurial's 1.827 + debugging output enabled. Since you'll probably be running 1.828 + it on a server where it's not convenient (or sometimes 1.829 + possible) to pass in the <option 1.830 + role="hg-opt-global">--debug</option> option, don't forget 1.831 + that you can enable debugging output in your <filename 1.832 + role="special"> /.hgrc</filename>: 1.833 + </para> 1.834 + <programlisting>[ui] debug = true</programlisting> 1.835 + <para>With this enabled, the <literal 1.836 + role="hg-ext">acl</literal> hook will print enough 1.837 + information to let you figure out why it is allowing or 1.838 + forbidding pushes from specific users. 1.839 + </para> 1.840 + 1.841 + </sect3> 1.842 + </sect2> 1.843 + <sect2> 1.844 + <title><literal 1.845 + role="hg-ext">bugzilla</literal>&emdash;integration with 1.846 + Bugzilla</title> 1.847 + 1.848 + <para>The <literal role="hg-ext">bugzilla</literal> extension 1.849 + adds a comment to a Bugzilla bug whenever it finds a reference 1.850 + to that bug ID in a commit comment. You can install this hook 1.851 + on a shared server, so that any time a remote user pushes 1.852 + changes to this server, the hook gets run. 1.853 + </para> 1.854 + 1.855 + <para>It adds a comment to the bug that looks like this (you can 1.856 + configure the contents of the comment&emdash;see below): 1.857 + </para> 1.858 + <programlisting>Changeset aad8b264143a, made by Joe User 1.859 + <joe.user@domain.com> in the frobnitz repository, refers 1.860 + to this bug. For complete details, see 1.861 + http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 1.862 + Changeset description: Fix bug 10483 by guarding against some 1.863 + NULL pointers</programlisting> 1.864 + <para>The value of this hook is that it automates the process of 1.865 + updating a bug any time a changeset refers to it. If you 1.866 + configure the hook properly, it makes it easy for people to 1.867 + browse straight from a Bugzilla bug to a changeset that refers 1.868 + to that bug. 1.869 + </para> 1.870 + 1.871 + <para>You can use the code in this hook as a starting point for 1.872 + some more exotic Bugzilla integration recipes. Here are a few 1.873 + possibilities: 1.874 + </para> 1.875 + <itemizedlist> 1.876 + <listitem><para>Require that every changeset pushed to the 1.877 + server have a valid bug ID in its commit comment. In this 1.878 + case, you'd want to configure the hook as a <literal 1.879 + role="hook">pretxncommit</literal> hook. This would 1.880 + allow the hook to reject changes that didn't contain bug 1.881 + IDs. 1.882 + </para> 1.883 + </listitem> 1.884 + <listitem><para>Allow incoming changesets to automatically 1.885 + modify the <emphasis>state</emphasis> of a bug, as well as 1.886 + simply adding a comment. For example, the hook could 1.887 + recognise the string <quote>fixed bug 31337</quote> as 1.888 + indicating that it should update the state of bug 31337 to 1.889 + <quote>requires testing</quote>. 1.890 + </para> 1.891 + </listitem></itemizedlist> 1.892 + 1.893 + <sect3 id="sec:hook:bugzilla:config"> 1.894 + <title>Configuring the <literal role="hook">bugzilla</literal> 1.895 + hook</title> 1.896 + 1.897 + <para>You should configure this hook in your server's 1.898 + <filename role="special"> /.hgrc</filename>\ as an <literal 1.899 + role="hook">incoming</literal> hook, for example as 1.900 + follows: 1.901 + </para> 1.902 + <programlisting>[hooks] incoming.bugzilla = 1.903 + python:hgext.bugzilla.hook</programlisting> 1.904 + 1.905 + <para>Because of the specialised nature of this hook, and 1.906 + because Bugzilla was not written with this kind of 1.907 + integration in mind, configuring this hook is a somewhat 1.908 + involved process. 1.909 + </para> 1.910 + 1.911 + <para>Before you begin, you must install the MySQL bindings 1.912 + for Python on the host(s) where you'll be running the hook. 1.913 + If this is not available as a binary package for your 1.914 + system, you can download it from 1.915 + <citation>web:mysql-python</citation>. 1.916 + </para> 1.917 + 1.918 + <para>Configuration information for this hook lives in the 1.919 + <literal role="rc-bugzilla">bugzilla</literal> section of 1.920 + your <filename role="special"> /.hgrc</filename>. 1.921 + </para> 1.922 + <itemizedlist> 1.923 + <listitem><para><envar 1.924 + role="rc-item-bugzilla">version</envar>: The version 1.925 + of Bugzilla installed on the server. The database 1.926 + schema that Bugzilla uses changes occasionally, so this 1.927 + hook has to know exactly which schema to use. At the 1.928 + moment, the only version supported is 1.929 + <literal>2.16</literal>. 1.930 + </para> 1.931 + </listitem> 1.932 + <listitem><para><envar role="rc-item-bugzilla">host</envar>: 1.933 + The hostname of the MySQL server that stores your 1.934 + Bugzilla data. The database must be configured to allow 1.935 + connections from whatever host you are running the 1.936 + <literal role="hook">bugzilla</literal> hook on. 1.937 + </para> 1.938 + </listitem> 1.939 + <listitem><para><envar role="rc-item-bugzilla">user</envar>: 1.940 + The username with which to connect to the MySQL server. 1.941 + The database must be configured to allow this user to 1.942 + connect from whatever host you are running the <literal 1.943 + role="hook">bugzilla</literal> hook on. This user 1.944 + must be able to access and modify Bugzilla tables. The 1.945 + default value of this item is <literal>bugs</literal>, 1.946 + which is the standard name of the Bugzilla user in a 1.947 + MySQL database. 1.948 + </para> 1.949 + </listitem> 1.950 + <listitem><para><envar 1.951 + role="rc-item-bugzilla">password</envar>: The MySQL 1.952 + password for the user you configured above. This is 1.953 + stored as plain text, so you should make sure that 1.954 + unauthorised users cannot read the <filename 1.955 + role="special"> /.hgrc</filename>\ file where you 1.956 + store this information. 1.957 + </para> 1.958 + </listitem> 1.959 + <listitem><para><envar role="rc-item-bugzilla">db</envar>: 1.960 + The name of the Bugzilla database on the MySQL server. 1.961 + The default value of this item is 1.962 + <literal>bugs</literal>, which is the standard name of 1.963 + the MySQL database where Bugzilla stores its data. 1.964 + </para> 1.965 + </listitem> 1.966 + <listitem><para><envar 1.967 + role="rc-item-bugzilla">notify</envar>: If you want 1.968 + Bugzilla to send out a notification email to subscribers 1.969 + after this hook has added a comment to a bug, you will 1.970 + need this hook to run a command whenever it updates the 1.971 + database. The command to run depends on where you have 1.972 + installed Bugzilla, but it will typically look something 1.973 + like this, if you have Bugzilla installed in <filename 1.974 + class="directory">/var/www/html/bugzilla</filename>: 1.975 + </para> 1.976 + <programlisting>cd /var/www/html/bugzilla && 1.977 + ./processmail %s nobody@nowhere.com</programlisting> 1.978 + </listitem> 1.979 + <listitem><para> The Bugzilla 1.980 + <literal>processmail</literal> program expects to be 1.981 + given a bug ID (the hook replaces 1.982 + <quote><literal>%s</literal></quote> with the bug ID) 1.983 + and an email address. It also expects to be able to 1.984 + write to some files in the directory that it runs in. 1.985 + If Bugzilla and this hook are not installed on the same 1.986 + machine, you will need to find a way to run 1.987 + <literal>processmail</literal> on the server where 1.988 + Bugzilla is installed. 1.989 + </para> 1.990 + </listitem></itemizedlist> 1.991 + 1.992 + </sect3> 1.993 + <sect3> 1.994 + <title>Mapping committer names to Bugzilla user names</title> 1.995 + 1.996 + <para>By default, the <literal 1.997 + role="hg-ext">bugzilla</literal> hook tries to use the 1.998 + email address of a changeset's committer as the Bugzilla 1.999 + user name with which to update a bug. If this does not suit 1.1000 + your needs, you can map committer email addresses to 1.1001 + Bugzilla user names using a <literal 1.1002 + role="rc-usermap">usermap</literal> section. 1.1003 + </para> 1.1004 + 1.1005 + <para>Each item in the <literal 1.1006 + role="rc-usermap">usermap</literal> section contains an 1.1007 + email address on the left, and a Bugzilla user name on the 1.1008 + right. 1.1009 + </para> 1.1010 + <programlisting>[usermap] jane.user@example.com = 1.1011 + jane</programlisting> 1.1012 + <para>You can either keep the <literal 1.1013 + role="rc-usermap">usermap</literal> data in a normal 1.1014 + <filename role="special">~/.hgrc</filename>, or tell the 1.1015 + <literal role="hg-ext">bugzilla</literal> hook to read the 1.1016 + information from an external <filename>usermap</filename> 1.1017 + file. In the latter case, you can store 1.1018 + <filename>usermap</filename> data by itself in (for example) 1.1019 + a user-modifiable repository. This makes it possible to let 1.1020 + your users maintain their own <envar 1.1021 + role="rc-item-bugzilla">usermap</envar> entries. The main 1.1022 + <filename role="special"> /.hgrc</filename>\ file might look 1.1023 + like this: 1.1024 + </para> 1.1025 + <programlisting># regular hgrc file refers to external usermap 1.1026 + file [bugzilla] usermap = 1.1027 + /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 1.1028 + <para>While the <filename>usermap</filename> file that it 1.1029 + refers to might look like this: 1.1030 + </para> 1.1031 + <programlisting># bugzilla-usermap.conf - inside a hg 1.1032 + repository [usermap] stephanie@example.com = 1.1033 + steph</programlisting> 1.1034 + 1.1035 + </sect3> 1.1036 + <sect3> 1.1037 + <title>Configuring the text that gets added to a bug</title> 1.1038 + 1.1039 + <para>You can configure the text that this hook adds as a 1.1040 + comment; you specify it in the form of a Mercurial template. 1.1041 + Several <filename role="special"> /.hgrc</filename>\ entries 1.1042 + (still in the <literal role="rc-bugzilla">bugzilla</literal> 1.1043 + section) control this behaviour. 1.1044 + </para> 1.1045 + <itemizedlist> 1.1046 + <listitem><para><literal>strip</literal>: The number of 1.1047 + leading path elements to strip from a repository's path 1.1048 + name to construct a partial path for a URL. For example, 1.1049 + if the repositories on your server live under <filename 1.1050 + class="directory">/home/hg/repos</filename>, and you 1.1051 + have a repository whose path is <filename 1.1052 + class="directory">/home/hg/repos/app/tests</filename>, 1.1053 + then setting <literal>strip</literal> to 1.1054 + <literal>4</literal> will give a partial path of 1.1055 + <filename class="directory">app/tests</filename>. The 1.1056 + hook will make this partial path available when 1.1057 + expanding a template, as <literal>webroot</literal>. 1.1058 + </para> 1.1059 + </listitem> 1.1060 + <listitem><para><literal>template</literal>: The text of the 1.1061 + template to use. In addition to the usual 1.1062 + changeset-related variables, this template can use 1.1063 + <literal>hgweb</literal> (the value of the 1.1064 + <literal>hgweb</literal> configuration item above) and 1.1065 + <literal>webroot</literal> (the path constructed using 1.1066 + <literal>strip</literal> above). 1.1067 + </para> 1.1068 + </listitem></itemizedlist> 1.1069 + 1.1070 + <para>In addition, you can add a <envar 1.1071 + role="rc-item-web">baseurl</envar> item to the <literal 1.1072 + role="rc-web">web</literal> section of your <filename 1.1073 + role="special"> /.hgrc</filename>. The <literal 1.1074 + role="hg-ext">bugzilla</literal> hook will make this 1.1075 + available when expanding a template, as the base string to 1.1076 + use when constructing a URL that will let users browse from 1.1077 + a Bugzilla comment to view a changeset. Example: 1.1078 + </para> 1.1079 + <programlisting>[web] baseurl = 1.1080 + http://hg.domain.com/</programlisting> 1.1081 + 1.1082 + <para>Here is an example set of <literal 1.1083 + role="hg-ext">bugzilla</literal> hook config information. 1.1084 + </para> 1.1085 + <programlisting>[bugzilla] host = bugzilla.example.com 1.1086 + password = mypassword version = 2.16 # server-side repos 1.1087 + live in /home/hg/repos, so strip 4 leading # separators 1.1088 + strip = 4 hgweb = http://hg.example.com/ usermap = 1.1089 + /home/hg/repos/notify/bugzilla.conf template = Changeset 1.1090 + {node|short}, made by {author} in the {webroot} repo, refers 1.1091 + to this bug.\\nFor complete details, see 1.1092 + {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset 1.1093 + description:\\n\\t{desc|tabindent}</programlisting> 1.1094 + 1.1095 + </sect3> 1.1096 + <sect3> 1.1097 + <title>Testing and troubleshooting</title> 1.1098 + 1.1099 + <para>The most common problems with configuring the <literal 1.1100 + role="hg-ext">bugzilla</literal> hook relate to running 1.1101 + Bugzilla's <filename>processmail</filename> script and 1.1102 + mapping committer names to user names. 1.1103 + </para> 1.1104 + 1.1105 + <para>Recall from section <xref 1.1106 + linkend="sec:hook:bugzilla:config"/> above that the user 1.1107 + that runs the Mercurial process on the server is also the 1.1108 + one that will run the <filename>processmail</filename> 1.1109 + script. The <filename>processmail</filename> script 1.1110 + sometimes causes Bugzilla to write to files in its 1.1111 + configuration directory, and Bugzilla's configuration files 1.1112 + are usually owned by the user that your web server runs 1.1113 + under. 1.1114 + </para> 1.1115 + 1.1116 + <para>You can cause <filename>processmail</filename> to be run 1.1117 + with the suitable user's identity using the 1.1118 + <command>sudo</command> command. Here is an example entry 1.1119 + for a <filename>sudoers</filename> file. 1.1120 + </para> 1.1121 + <programlisting>hg_user = (httpd_user) NOPASSWD: 1.1122 + /var/www/html/bugzilla/processmail-wrapper 1.1123 + %s</programlisting> 1.1124 + <para>This allows the <literal>hg_user</literal> user to run a 1.1125 + <filename>processmail-wrapper</filename> program under the 1.1126 + identity of <literal>httpd_user</literal>. 1.1127 + </para> 1.1128 + 1.1129 + <para>This indirection through a wrapper script is necessary, 1.1130 + because <filename>processmail</filename> expects to be run 1.1131 + with its current directory set to wherever you installed 1.1132 + Bugzilla; you can't specify that kind of constraint in a 1.1133 + <filename>sudoers</filename> file. The contents of the 1.1134 + wrapper script are simple: 1.1135 + </para> 1.1136 + <programlisting>#!/bin/sh cd `dirname $0` && 1.1137 + ./processmail "$1" nobody@example.com</programlisting> 1.1138 + <para>It doesn't seem to matter what email address you pass to 1.1139 + <filename>processmail</filename>. 1.1140 + </para> 1.1141 + 1.1142 + <para>If your <literal role="rc-usermap">usermap</literal> is 1.1143 + not set up correctly, users will see an error message from 1.1144 + the <literal role="hg-ext">bugzilla</literal> hook when they 1.1145 + push changes to the server. The error message will look 1.1146 + like this: 1.1147 + </para> 1.1148 + <programlisting>cannot find bugzilla user id for 1.1149 + john.q.public@example.com</programlisting> 1.1150 + <para>What this means is that the committer's address, 1.1151 + <literal>john.q.public@example.com</literal>, is not a valid 1.1152 + Bugzilla user name, nor does it have an entry in your 1.1153 + <literal role="rc-usermap">usermap</literal> that maps it to 1.1154 + a valid Bugzilla user name. 1.1155 + </para> 1.1156 + 1.1157 + </sect3> 1.1158 + </sect2> 1.1159 + <sect2> 1.1160 + <title><literal role="hg-ext">notify</literal>&emdash;send email 1.1161 + notifications</title> 1.1162 + 1.1163 + <para>Although Mercurial's built-in web server provides RSS 1.1164 + feeds of changes in every repository, many people prefer to 1.1165 + receive change notifications via email. The <literal 1.1166 + role="hg-ext">notify</literal> hook lets you send out 1.1167 + notifications to a set of email addresses whenever changesets 1.1168 + arrive that those subscribers are interested in. 1.1169 + </para> 1.1170 + 1.1171 + <para>As with the <literal role="hg-ext">bugzilla</literal> 1.1172 + hook, the <literal role="hg-ext">notify</literal> hook is 1.1173 + template-driven, so you can customise the contents of the 1.1174 + notification messages that it sends. 1.1175 + </para> 1.1176 + 1.1177 + <para>By default, the <literal role="hg-ext">notify</literal> 1.1178 + hook includes a diff of every changeset that it sends out; you 1.1179 + can limit the size of the diff, or turn this feature off 1.1180 + entirely. It is useful for letting subscribers review changes 1.1181 + immediately, rather than clicking to follow a URL. 1.1182 + </para> 1.1183 + 1.1184 + <sect3> 1.1185 + <title>Configuring the <literal role="hg-ext">notify</literal> 1.1186 + hook</title> 1.1187 + 1.1188 + <para>You can set up the <literal 1.1189 + role="hg-ext">notify</literal> hook to send one email 1.1190 + message per incoming changeset, or one per incoming group of 1.1191 + changesets (all those that arrived in a single pull or 1.1192 + push). 1.1193 + </para> 1.1194 + <programlisting>[hooks] # send one email per group of changes 1.1195 + changegroup.notify = python:hgext.notify.hook # send one 1.1196 + email per change incoming.notify = 1.1197 + python:hgext.notify.hook</programlisting> 1.1198 + 1.1199 + <para>Configuration information for this hook lives in the 1.1200 + <literal role="rc-notify">notify</literal> section of a 1.1201 + <filename role="special"> /.hgrc</filename>\ file. 1.1202 + </para> 1.1203 + <itemizedlist> 1.1204 + <listitem><para><envar role="rc-item-notify">test</envar>: 1.1205 + By default, this hook does not send out email at all; 1.1206 + instead, it prints the message that it 1.1207 + <emphasis>would</emphasis> send. Set this item to 1.1208 + <literal>false</literal> to allow email to be sent. The 1.1209 + reason that sending of email is turned off by default is 1.1210 + that it takes several tries to configure this extension 1.1211 + exactly as you would like, and it would be bad form to 1.1212 + spam subscribers with a number of <quote>broken</quote> 1.1213 + notifications while you debug your configuration. 1.1214 + </para> 1.1215 + </listitem> 1.1216 + <listitem><para><envar role="rc-item-notify">config</envar>: 1.1217 + The path to a configuration file that contains 1.1218 + subscription information. This is kept separate from 1.1219 + the main <filename role="special"> /.hgrc</filename>\ so 1.1220 + that you can maintain it in a repository of its own. 1.1221 + People can then clone that repository, update their 1.1222 + subscriptions, and push the changes back to your server. 1.1223 + </para> 1.1224 + </listitem> 1.1225 + <listitem><para><envar role="rc-item-notify">strip</envar>: 1.1226 + The number of leading path separator characters to strip 1.1227 + from a repository's path, when deciding whether a 1.1228 + repository has subscribers. For example, if the 1.1229 + repositories on your server live in <filename 1.1230 + class="directory">/home/hg/repos</filename>, and 1.1231 + <literal role="hg-ext">notify</literal> is considering a 1.1232 + repository named <filename 1.1233 + class="directory">/home/hg/repos/shared/test</filename>, 1.1234 + setting <envar role="rc-item-notify">strip</envar> to 1.1235 + <literal>4</literal> will cause <literal 1.1236 + role="hg-ext">notify</literal> to trim the path it 1.1237 + considers down to <filename 1.1238 + class="directory">shared/test</filename>, and it will 1.1239 + match subscribers against that. 1.1240 + </para> 1.1241 + </listitem> 1.1242 + <listitem><para><envar 1.1243 + role="rc-item-notify">template</envar>: The template 1.1244 + text to use when sending messages. This specifies both 1.1245 + the contents of the message header and its body. 1.1246 + </para> 1.1247 + </listitem> 1.1248 + <listitem><para><envar 1.1249 + role="rc-item-notify">maxdiff</envar>: The maximum 1.1250 + number of lines of diff data to append to the end of a 1.1251 + message. If a diff is longer than this, it is 1.1252 + truncated. By default, this is set to 300. Set this to 1.1253 + <literal>0</literal> to omit diffs from notification 1.1254 + emails. 1.1255 + </para> 1.1256 + </listitem> 1.1257 + <listitem><para><envar 1.1258 + role="rc-item-notify">sources</envar>: A list of 1.1259 + sources of changesets to consider. This lets you limit 1.1260 + <literal role="hg-ext">notify</literal> to only sending 1.1261 + out email about changes that remote users pushed into 1.1262 + this repository via a server, for example. See section 1.1263 + <xref 1.1264 + linkend="sec:hook:sources"/> for the sources you can 1.1265 + specify here. 1.1266 + </para> 1.1267 + </listitem></itemizedlist> 1.1268 + 1.1269 + <para>If you set the <envar role="rc-item-web">baseurl</envar> 1.1270 + item in the <literal role="rc-web">web</literal> section, 1.1271 + you can use it in a template; it will be available as 1.1272 + <literal>webroot</literal>. 1.1273 + </para> 1.1274 + 1.1275 + <para>Here is an example set of <literal 1.1276 + role="hg-ext">notify</literal> configuration information. 1.1277 + </para> 1.1278 + <programlisting> 1.1279 + [notify] # really send email test = false # subscriber data 1.1280 + lives in the notify repo config = 1.1281 + /home/hg/repos/notify/notify.conf # repos live in 1.1282 + /home/hg/repos on server, so strip 4 "/" chars strip = 4 1.1283 + template = X-Hg-Repo: {webroot} Subject: {webroot}: 1.1284 + {desc|firstline|strip} From: {author} changeset {node|short} 1.1285 + in {root} details: 1.1286 + {baseurl}{webroot}?cmd=changeset;node={node|short} 1.1287 + description: {desc|tabindent|strip} [web] baseurl = 1.1288 + http://hg.example.com/ 1.1289 + </programlisting> 1.1290 + 1.1291 + <para>This will produce a message that looks like the 1.1292 + following: 1.1293 + </para> 1.1294 + <programlisting> 1.1295 + X-Hg-Repo: tests/slave Subject: tests/slave: Handle error 1.1296 + case when slave has no buffers Date: Wed, 2 Aug 2006 1.1297 + 15:25:46 -0700 (PDT) changeset 3cba9bfe74b5 in 1.1298 + /home/hg/repos/tests/slave details: 1.1299 + http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 1.1300 + description: Handle error case when slave has no buffers 1.1301 + diffs (54 lines): diff -r 9d95df7cf2ad -r 3cba9bfe74b5 1.1302 + include/tests.h --- a/include/tests.h Wed Aug 02 1.1303 + 15:19:52 2006 -0700 +++ b/include/tests.h Wed Aug 02 1.1304 + 15:25:26 2006 -0700 @@ -212,6 +212,15 @@ static __inline__ 1.1305 + void test_headers(void *h) [...snip...] 1.1306 + </programlisting> 1.1307 + 1.1308 + </sect3> 1.1309 + <sect3> 1.1310 + <title>Testing and troubleshooting</title> 1.1311 + 1.1312 + <para>Do not forget that by default, the <literal 1.1313 + role="hg-ext">notify</literal> extension \emph{will not 1.1314 + send any mail} until you explicitly configure it to do so, 1.1315 + by setting <envar role="rc-item-notify">test</envar> to 1.1316 + <literal>false</literal>. Until you do that, it simply 1.1317 + prints the message it <emphasis>would</emphasis> send. 1.1318 + </para> 1.1319 + 1.1320 + </sect3> 1.1321 + </sect2> 1.1322 + </sect1> 1.1323 + <sect1 id="sec:hook:ref"> 1.1324 + <title>Information for writers of hooks</title> 1.1325 + 1.1326 + <sect2> 1.1327 + <title>In-process hook execution</title> 1.1328 + 1.1329 + <para>An in-process hook is called with arguments of the 1.1330 + following form: 1.1331 + </para> 1.1332 + <programlisting> 1.1333 + def myhook(ui, repo, **kwargs): pass 1.1334 + </programlisting> 1.1335 + <para>The <literal>ui</literal> parameter is a <literal 1.1336 + role="py-mod-mercurial.ui">ui</literal> object. The 1.1337 + <literal>repo</literal> parameter is a <literal 1.1338 + role="py-mod-mercurial.localrepo">localrepository</literal> 1.1339 + object. The names and values of the 1.1340 + <literal>**kwargs</literal> parameters depend on the hook 1.1341 + being invoked, with the following common features: 1.1342 + </para> 1.1343 + <itemizedlist> 1.1344 + <listitem><para>If a parameter is named 1.1345 + <literal>node</literal> or <literal>parentN</literal>, it 1.1346 + will contain a hexadecimal changeset ID. The empty string 1.1347 + is used to represent <quote>null changeset ID</quote> 1.1348 + instead of a string of zeroes. 1.1349 + </para> 1.1350 + </listitem> 1.1351 + <listitem><para>If a parameter is named 1.1352 + <literal>url</literal>, it will contain the URL of a 1.1353 + remote repository, if that can be determined. 1.1354 + </para> 1.1355 + </listitem> 1.1356 + <listitem><para>Boolean-valued parameters are represented as 1.1357 + Python <literal>bool</literal> objects. 1.1358 + </para> 1.1359 + </listitem></itemizedlist> 1.1360 + 1.1361 + <para>An in-process hook is called without a change to the 1.1362 + process's working directory (unlike external hooks, which are 1.1363 + run in the root of the repository). It must not change the 1.1364 + process's working directory, or it will cause any calls it 1.1365 + makes into the Mercurial API to fail. 1.1366 + </para> 1.1367 + 1.1368 + <para>If a hook returns a boolean <quote>false</quote> value, it 1.1369 + is considered to have succeeded. If it returns a boolean 1.1370 + <quote>true</quote> value or raises an exception, it is 1.1371 + considered to have failed. A useful way to think of the 1.1372 + calling convention is <quote>tell me if you fail</quote>. 1.1373 + </para> 1.1374 + 1.1375 + <para>Note that changeset IDs are passed into Python hooks as 1.1376 + hexadecimal strings, not the binary hashes that Mercurial's 1.1377 + APIs normally use. To convert a hash from hex to binary, use 1.1378 + the \pymodfunc{mercurial.node}{bin} function. 1.1379 + </para> 1.1380 + 1.1381 + </sect2> 1.1382 + <sect2> 1.1383 + <title>External hook execution</title> 1.1384 + 1.1385 + <para>An external hook is passed to the shell of the user 1.1386 + running Mercurial. Features of that shell, such as variable 1.1387 + substitution and command redirection, are available. The hook 1.1388 + is run in the root directory of the repository (unlike 1.1389 + in-process hooks, which are run in the same directory that 1.1390 + Mercurial was run in). 1.1391 + </para> 1.1392 + 1.1393 + <para>Hook parameters are passed to the hook as environment 1.1394 + variables. Each environment variable's name is converted in 1.1395 + upper case and prefixed with the string 1.1396 + <quote><literal>HG_</literal></quote>. For example, if the 1.1397 + name of a parameter is <quote><literal>node</literal></quote>, 1.1398 + the name of the environment variable representing that 1.1399 + parameter will be <quote><literal>HG_NODE</literal></quote>. 1.1400 + </para> 1.1401 + 1.1402 + <para>A boolean parameter is represented as the string 1.1403 + <quote><literal>1</literal></quote> for <quote>true</quote>, 1.1404 + <quote><literal>0</literal></quote> for <quote>false</quote>. 1.1405 + If an environment variable is named <envar>HG_NODE</envar>, 1.1406 + <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 1.1407 + contains a changeset ID represented as a hexadecimal string. 1.1408 + The empty string is used to represent <quote>null changeset 1.1409 + ID</quote> instead of a string of zeroes. If an environment 1.1410 + variable is named <envar>HG_URL</envar>, it will contain the 1.1411 + URL of a remote repository, if that can be determined. 1.1412 + </para> 1.1413 + 1.1414 + <para>If a hook exits with a status of zero, it is considered to 1.1415 + have succeeded. If it exits with a non-zero status, it is 1.1416 + considered to have failed. 1.1417 + </para> 1.1418 + 1.1419 + </sect2> 1.1420 + <sect2> 1.1421 + <title>Finding out where changesets come from</title> 1.1422 + 1.1423 + <para>A hook that involves the transfer of changesets between a 1.1424 + local repository and another may be able to find out 1.1425 + information about the <quote>far side</quote>. Mercurial 1.1426 + knows <emphasis>how</emphasis> changes are being transferred, 1.1427 + and in many cases <emphasis>where</emphasis> they are being 1.1428 + transferred to or from. 1.1429 + </para> 1.1430 + 1.1431 + <sect3 id="sec:hook:sources"> 1.1432 + <title>Sources of changesets</title> 1.1433 + 1.1434 + <para>Mercurial will tell a hook what means are, or were, used 1.1435 + to transfer changesets between repositories. This is 1.1436 + provided by Mercurial in a Python parameter named 1.1437 + <literal>source</literal>, or an environment variable named 1.1438 + <envar>HG_SOURCE</envar>. 1.1439 + </para> 1.1440 + 1.1441 + <itemizedlist> 1.1442 + <listitem><para><literal>serve</literal>: Changesets are 1.1443 + transferred to or from a remote repository over http or 1.1444 + ssh. 1.1445 + </para> 1.1446 + </listitem> 1.1447 + <listitem><para><literal>pull</literal>: Changesets are 1.1448 + being transferred via a pull from one repository into 1.1449 + another. 1.1450 + </para> 1.1451 + </listitem> 1.1452 + <listitem><para><literal>push</literal>: Changesets are 1.1453 + being transferred via a push from one repository into 1.1454 + another. 1.1455 + </para> 1.1456 + </listitem> 1.1457 + <listitem><para><literal>bundle</literal>: Changesets are 1.1458 + being transferred to or from a bundle. 1.1459 + </para> 1.1460 + </listitem></itemizedlist> 1.1461 + 1.1462 + </sect3> 1.1463 + <sect3 id="sec:hook:url"> 1.1464 + <title>Where changes are going&emdash;remote repository 1.1465 + URLs</title> 1.1466 + 1.1467 + <para>When possible, Mercurial will tell a hook the location 1.1468 + of the <quote>far side</quote> of an activity that transfers 1.1469 + changeset data between repositories. This is provided by 1.1470 + Mercurial in a Python parameter named 1.1471 + <literal>url</literal>, or an environment variable named 1.1472 + <envar>HG_URL</envar>. 1.1473 + </para> 1.1474 + 1.1475 + <para>This information is not always known. If a hook is 1.1476 + invoked in a repository that is being served via http or 1.1477 + ssh, Mercurial cannot tell where the remote repository is, 1.1478 + but it may know where the client is connecting from. In 1.1479 + such cases, the URL will take one of the following forms: 1.1480 + </para> 1.1481 + <itemizedlist> 1.1482 + <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 1.1483 + ssh client, at the IP address 1.1484 + <literal>1.2.3.4</literal>. 1.1485 + </para> 1.1486 + </listitem> 1.1487 + <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote 1.1488 + http client, at the IP address 1.1489 + <literal>1.2.3.4</literal>. If the client is using SSL, 1.1490 + this will be of the form 1.1491 + <literal>remote:https:1.2.3.4</literal>. 1.1492 + </para> 1.1493 + </listitem> 1.1494 + <listitem><para>Empty&emdash;no information could be 1.1495 + discovered about the remote client. 1.1496 + </para> 1.1497 + </listitem></itemizedlist> 1.1498 + 1.1499 + </sect3> 1.1500 + </sect2> 1.1501 + </sect1> 1.1502 + <sect1> 1.1503 + <title>Hook reference</title> 1.1504 + 1.1505 + <sect2 id="sec:hook:changegroup"> 1.1506 + <title><literal role="hook">changegroup</literal>&emdash;after 1.1507 + remote changesets added</title> 1.1508 + 1.1509 + <para>This hook is run after a group of pre-existing changesets 1.1510 + has been added to the repository, for example via a <command 1.1511 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 1.1512 + unbundle</command>. This hook is run once per operation 1.1513 + that added one or more changesets. This is in contrast to the 1.1514 + <literal role="hook">incoming</literal> hook, which is run 1.1515 + once per changeset, regardless of whether the changesets 1.1516 + arrive in a group. 1.1517 + </para> 1.1518 + 1.1519 + <para>Some possible uses for this hook include kicking off an 1.1520 + automated build or test of the added changesets, updating a 1.1521 + bug database, or notifying subscribers that a repository 1.1522 + contains new changes. 1.1523 + </para> 1.1524 + 1.1525 + <para>Parameters to this hook: 1.1526 + </para> 1.1527 + <itemizedlist> 1.1528 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1529 + changeset ID of the first changeset in the group that was 1.1530 + added. All changesets between this and 1.1531 + \index{tags!<literal>tip</literal>}<literal>tip</literal>, 1.1532 + inclusive, were added by a single <command 1.1533 + role="hg-cmd">hg pull</command>, <command 1.1534 + role="hg-cmd">hg push</command> or <command 1.1535 + role="hg-cmd">hg unbundle</command>. 1.1536 + </para> 1.1537 + </listitem> 1.1538 + <listitem><para><literal>source</literal>: A string. The 1.1539 + source of these changes. See section <xref 1.1540 + linkend="sec:hook:sources"/> for details. 1.1541 + </para> 1.1542 + </listitem> 1.1543 + <listitem><para><literal>url</literal>: A URL. The location 1.1544 + of the remote repository, if known. See section <xref 1.1545 + linkend="sec:hook:url"/> for more 1.1546 + information. 1.1547 + </para> 1.1548 + </listitem></itemizedlist> 1.1549 + 1.1550 + <para>See also: <literal role="hook">incoming</literal> (section 1.1551 + <xref linkend="sec:hook:incoming"/>), <literal 1.1552 + role="hook">prechangegroup</literal> (section <xref 1.1553 + linkend="sec:hook:prechangegroup"/>), <literal 1.1554 + role="hook">pretxnchangegroup</literal> (section <xref 1.1555 + linkend="sec:hook:pretxnchangegroup"/>) 1.1556 + </para> 1.1557 + 1.1558 + </sect2> 1.1559 + <sect2 id="sec:hook:commit"> 1.1560 + <title><literal role="hook">commit</literal>&emdash;after a new 1.1561 + changeset is created</title> 1.1562 + 1.1563 + <para>This hook is run after a new changeset has been created. 1.1564 + </para> 1.1565 + 1.1566 + <para>Parameters to this hook: 1.1567 + </para> 1.1568 + <itemizedlist> 1.1569 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1570 + changeset ID of the newly committed changeset. 1.1571 + </para> 1.1572 + </listitem> 1.1573 + <listitem><para><literal>parent1</literal>: A changeset ID. 1.1574 + The changeset ID of the first parent of the newly 1.1575 + committed changeset. 1.1576 + </para> 1.1577 + </listitem> 1.1578 + <listitem><para><literal>parent2</literal>: A changeset ID. 1.1579 + The changeset ID of the second parent of the newly 1.1580 + committed changeset. 1.1581 + </para> 1.1582 + </listitem></itemizedlist> 1.1583 + 1.1584 + <para>See also: <literal role="hook">precommit</literal> 1.1585 + (section <xref linkend="sec:hook:precommit"/>), <literal 1.1586 + role="hook">pretxncommit</literal> (section <xref 1.1587 + linkend="sec:hook:pretxncommit"/>) 1.1588 + </para> 1.1589 + 1.1590 + </sect2> 1.1591 + <sect2 id="sec:hook:incoming"> 1.1592 + <title><literal role="hook">incoming</literal>&emdash;after one 1.1593 + remote changeset is added</title> 1.1594 + 1.1595 + <para>This hook is run after a pre-existing changeset has been 1.1596 + added to the repository, for example via a <command 1.1597 + role="hg-cmd">hg push</command>. If a group of changesets 1.1598 + was added in a single operation, this hook is called once for 1.1599 + each added changeset. 1.1600 + </para> 1.1601 + 1.1602 + <para>You can use this hook for the same purposes as the 1.1603 + <literal role="hook">changegroup</literal> hook (section <xref 1.1604 + linkend="sec:hook:changegroup"/>); it's simply 1.1605 + more convenient sometimes to run a hook once per group of 1.1606 + changesets, while other times it's handier once per changeset. 1.1607 + </para> 1.1608 + 1.1609 + <para>Parameters to this hook: 1.1610 + </para> 1.1611 + <itemizedlist> 1.1612 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1613 + ID of the newly added changeset. 1.1614 + </para> 1.1615 + </listitem> 1.1616 + <listitem><para><literal>source</literal>: A string. The 1.1617 + source of these changes. See section <xref 1.1618 + linkend="sec:hook:sources"/> for details. 1.1619 + </para> 1.1620 + </listitem> 1.1621 + <listitem><para><literal>url</literal>: A URL. The location 1.1622 + of the remote repository, if known. See section <xref 1.1623 + linkend="sec:hook:url"/> for more 1.1624 + information. 1.1625 + </para> 1.1626 + </listitem></itemizedlist> 1.1627 + 1.1628 + <para>See also: <literal role="hook">changegroup</literal> 1.1629 + (section <xref linkend="sec:hook:changegroup"/>) <literal 1.1630 + role="hook">prechangegroup</literal> (section <xref 1.1631 + linkend="sec:hook:prechangegroup"/>), <literal 1.1632 + role="hook">pretxnchangegroup</literal> (section <xref 1.1633 + linkend="sec:hook:pretxnchangegroup"/>) 1.1634 + </para> 1.1635 + 1.1636 + </sect2> 1.1637 + <sect2 id="sec:hook:outgoing"> 1.1638 + <title><literal role="hook">outgoing</literal>&emdash;after 1.1639 + changesets are propagated</title> 1.1640 + 1.1641 + <para>This hook is run after a group of changesets has been 1.1642 + propagated out of this repository, for example by a <command 1.1643 + role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 1.1644 + bundle</command> command. 1.1645 + </para> 1.1646 + 1.1647 + <para>One possible use for this hook is to notify administrators 1.1648 + that changes have been pulled. 1.1649 + </para> 1.1650 + 1.1651 + <para>Parameters to this hook: 1.1652 + </para> 1.1653 + <itemizedlist> 1.1654 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1655 + changeset ID of the first changeset of the group that was 1.1656 + sent. 1.1657 + </para> 1.1658 + </listitem> 1.1659 + <listitem><para><literal>source</literal>: A string. The 1.1660 + source of the of the operation (see section <xref 1.1661 + linkend="sec:hook:sources"/>). If a remote 1.1662 + client pulled changes from this repository, 1.1663 + <literal>source</literal> will be 1.1664 + <literal>serve</literal>. If the client that obtained 1.1665 + changes from this repository was local, 1.1666 + <literal>source</literal> will be 1.1667 + <literal>bundle</literal>, <literal>pull</literal>, or 1.1668 + <literal>push</literal>, depending on the operation the 1.1669 + client performed. 1.1670 + </para> 1.1671 + </listitem> 1.1672 + <listitem><para><literal>url</literal>: A URL. The location 1.1673 + of the remote repository, if known. See section <xref 1.1674 + linkend="sec:hook:url"/> for more 1.1675 + information. 1.1676 + </para> 1.1677 + </listitem></itemizedlist> 1.1678 + 1.1679 + <para>See also: <literal role="hook">preoutgoing</literal> 1.1680 + (section <xref linkend="sec:hook:preoutgoing"/>) 1.1681 + </para> 1.1682 + 1.1683 + </sect2> 1.1684 + <sect2 id="sec:hook:prechangegroup"> 1.1685 + <title><literal 1.1686 + role="hook">prechangegroup</literal>&emdash;before starting 1.1687 + to add remote changesets</title> 1.1688 + 1.1689 + <para>This controlling hook is run before Mercurial begins to 1.1690 + add a group of changesets from another repository. 1.1691 + </para> 1.1692 + 1.1693 + <para>This hook does not have any information about the 1.1694 + changesets to be added, because it is run before transmission 1.1695 + of those changesets is allowed to begin. If this hook fails, 1.1696 + the changesets will not be transmitted. 1.1697 + </para> 1.1698 + 1.1699 + <para>One use for this hook is to prevent external changes from 1.1700 + being added to a repository. For example, you could use this 1.1701 + to <quote>freeze</quote> a server-hosted branch temporarily or 1.1702 + permanently so that users cannot push to it, while still 1.1703 + allowing a local administrator to modify the repository. 1.1704 + </para> 1.1705 + 1.1706 + <para>Parameters to this hook: 1.1707 + </para> 1.1708 + <itemizedlist> 1.1709 + <listitem><para><literal>source</literal>: A string. The 1.1710 + source of these changes. See section <xref 1.1711 + linkend="sec:hook:sources"/> for details. 1.1712 + </para> 1.1713 + </listitem> 1.1714 + <listitem><para><literal>url</literal>: A URL. The location 1.1715 + of the remote repository, if known. See section <xref 1.1716 + linkend="sec:hook:url"/> for more 1.1717 + information. 1.1718 + </para> 1.1719 + </listitem></itemizedlist> 1.1720 + 1.1721 + <para>See also: <literal role="hook">changegroup</literal> 1.1722 + (section <xref linkend="sec:hook:changegroup"/>), <literal 1.1723 + role="hook">incoming</literal> (section <xref 1.1724 + linkend="sec:hook:incoming"/>), , <literal 1.1725 + role="hook">pretxnchangegroup</literal> (section <xref 1.1726 + linkend="sec:hook:pretxnchangegroup"/>) 1.1727 + </para> 1.1728 + 1.1729 + </sect2> 1.1730 + <sect2 id="sec:hook:precommit"> 1.1731 + <title><literal role="hook">precommit</literal>&emdash;before 1.1732 + starting to commit a changeset</title> 1.1733 + 1.1734 + <para>This hook is run before Mercurial begins to commit a new 1.1735 + changeset. It is run before Mercurial has any of the metadata 1.1736 + for the commit, such as the files to be committed, the commit 1.1737 + message, or the commit date. 1.1738 + </para> 1.1739 + 1.1740 + <para>One use for this hook is to disable the ability to commit 1.1741 + new changesets, while still allowing incoming changesets. 1.1742 + Another is to run a build or test, and only allow the commit 1.1743 + to begin if the build or test succeeds. 1.1744 + </para> 1.1745 + 1.1746 + <para>Parameters to this hook: 1.1747 + </para> 1.1748 + <itemizedlist> 1.1749 + <listitem><para><literal>parent1</literal>: A changeset ID. 1.1750 + The changeset ID of the first parent of the working 1.1751 + directory. 1.1752 + </para> 1.1753 + </listitem> 1.1754 + <listitem><para><literal>parent2</literal>: A changeset ID. 1.1755 + The changeset ID of the second parent of the working 1.1756 + directory. 1.1757 + </para> 1.1758 + </listitem></itemizedlist> 1.1759 + <para>If the commit proceeds, the parents of the working 1.1760 + directory will become the parents of the new changeset. 1.1761 + </para> 1.1762 + 1.1763 + <para>See also: <literal role="hook">commit</literal> (section 1.1764 + <xref linkend="sec:hook:commit"/>), <literal 1.1765 + role="hook">pretxncommit</literal> (section <xref 1.1766 + linkend="sec:hook:pretxncommit"/>) 1.1767 + </para> 1.1768 + 1.1769 + </sect2> 1.1770 + <sect2 id="sec:hook:preoutgoing"> 1.1771 + <title><literal role="hook">preoutgoing</literal>&emdash;before 1.1772 + starting to propagate changesets</title> 1.1773 + 1.1774 + <para>This hook is invoked before Mercurial knows the identities 1.1775 + of the changesets to be transmitted. 1.1776 + </para> 1.1777 + 1.1778 + <para>One use for this hook is to prevent changes from being 1.1779 + transmitted to another repository. 1.1780 + </para> 1.1781 + 1.1782 + <para>Parameters to this hook: 1.1783 + </para> 1.1784 + <itemizedlist> 1.1785 + <listitem><para><literal>source</literal>: A string. The 1.1786 + source of the operation that is attempting to obtain 1.1787 + changes from this repository (see section <xref 1.1788 + linkend="sec:hook:sources"/>). See the documentation 1.1789 + for the <literal>source</literal> parameter to the 1.1790 + <literal role="hook">outgoing</literal> hook, in section 1.1791 + <xref linkend="sec:hook:outgoing"/>, for possible values 1.1792 + of 1.1793 + this parameter. 1.1794 + </para> 1.1795 + </listitem> 1.1796 + <listitem><para><literal>url</literal>: A URL. The location 1.1797 + of the remote repository, if known. See section <xref 1.1798 + linkend="sec:hook:url"/> for more 1.1799 + information. 1.1800 + </para> 1.1801 + </listitem></itemizedlist> 1.1802 + 1.1803 + <para>See also: <literal role="hook">outgoing</literal> (section 1.1804 + <xref linkend="sec:hook:outgoing"/>) 1.1805 + </para> 1.1806 + 1.1807 + </sect2> 1.1808 + <sect2 id="sec:hook:pretag"> 1.1809 + <title><literal role="hook">pretag</literal>&emdash;before 1.1810 + tagging a changeset</title> 1.1811 + 1.1812 + <para>This controlling hook is run before a tag is created. If 1.1813 + the hook succeeds, creation of the tag proceeds. If the hook 1.1814 + fails, the tag is not created. 1.1815 + </para> 1.1816 + 1.1817 + <para>Parameters to this hook: 1.1818 + </para> 1.1819 + <itemizedlist> 1.1820 + <listitem><para><literal>local</literal>: A boolean. Whether 1.1821 + the tag is local to this repository instance (i.e. stored 1.1822 + in <filename role="special">.hg/localtags</filename>) or 1.1823 + managed by Mercurial (stored in <filename 1.1824 + role="special">.hgtags</filename>). 1.1825 + </para> 1.1826 + </listitem> 1.1827 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1828 + ID of the changeset to be tagged. 1.1829 + </para> 1.1830 + </listitem> 1.1831 + <listitem><para><literal>tag</literal>: A string. The name of 1.1832 + the tag to be created. 1.1833 + </para> 1.1834 + </listitem></itemizedlist> 1.1835 + 1.1836 + <para>If the tag to be created is revision-controlled, the 1.1837 + <literal role="hook">precommit</literal> and <literal 1.1838 + role="hook">pretxncommit</literal> hooks (sections <xref 1.1839 + linkend="sec:hook:commit"/> and <xref 1.1840 + linkend="sec:hook:pretxncommit"/>) will also be run. 1.1841 + </para> 1.1842 + 1.1843 + <para>See also: <literal role="hook">tag</literal> (section 1.1844 + <xref linkend="sec:hook:tag"/>) 1.1845 + </para> 1.1846 + </sect2> 1.1847 + <sect2 id="sec:hook:pretxnchangegroup"> 1.1848 + <title><literal 1.1849 + role="hook">pretxnchangegroup</literal>&emdash;before 1.1850 + completing addition of remote changesets</title> 1.1851 + 1.1852 + <para>This controlling hook is run before a 1.1853 + transaction&emdash;that manages the addition of a group of new 1.1854 + changesets from outside the repository&emdash;completes. If 1.1855 + the hook succeeds, the transaction completes, and all of the 1.1856 + changesets become permanent within this repository. If the 1.1857 + hook fails, the transaction is rolled back, and the data for 1.1858 + the changesets is erased. 1.1859 + </para> 1.1860 + 1.1861 + <para>This hook can access the metadata associated with the 1.1862 + almost-added changesets, but it should not do anything 1.1863 + permanent with this data. It must also not modify the working 1.1864 + directory. 1.1865 + </para> 1.1866 + 1.1867 + <para>While this hook is running, if other Mercurial processes 1.1868 + access this repository, they will be able to see the 1.1869 + almost-added changesets as if they are permanent. This may 1.1870 + lead to race conditions if you do not take steps to avoid 1.1871 + them. 1.1872 + </para> 1.1873 + 1.1874 + <para>This hook can be used to automatically vet a group of 1.1875 + changesets. If the hook fails, all of the changesets are 1.1876 + <quote>rejected</quote> when the transaction rolls back. 1.1877 + </para> 1.1878 + 1.1879 + <para>Parameters to this hook: 1.1880 + </para> 1.1881 + <itemizedlist> 1.1882 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1883 + changeset ID of the first changeset in the group that was 1.1884 + added. All changesets between this and 1.1885 + \index{tags!<literal>tip</literal>}<literal>tip</literal>, 1.1886 + inclusive, were added by a single <command 1.1887 + role="hg-cmd">hg pull</command>, <command 1.1888 + role="hg-cmd">hg push</command> or <command 1.1889 + role="hg-cmd">hg unbundle</command>. 1.1890 + </para> 1.1891 + </listitem> 1.1892 + <listitem><para><literal>source</literal>: A string. The 1.1893 + source of these changes. See section <xref 1.1894 + linkend="sec:hook:sources"/> for details. 1.1895 + </para> 1.1896 + </listitem> 1.1897 + <listitem><para><literal>url</literal>: A URL. The location 1.1898 + of the remote repository, if known. See section <xref 1.1899 + linkend="sec:hook:url"/> for more 1.1900 + information. 1.1901 + </para> 1.1902 + </listitem></itemizedlist> 1.1903 + 1.1904 + <para>See also: <literal role="hook">changegroup</literal> 1.1905 + (section <xref linkend="sec:hook:changegroup"/>), <literal 1.1906 + role="hook">incoming</literal> (section <xref 1.1907 + linkend="sec:hook:incoming"/>), <literal 1.1908 + role="hook">prechangegroup</literal> (section <xref 1.1909 + linkend="sec:hook:prechangegroup"/>) 1.1910 + </para> 1.1911 + 1.1912 + </sect2> 1.1913 + <sect2 id="sec:hook:pretxncommit"> 1.1914 + <title><literal role="hook">pretxncommit</literal>&emdash;before 1.1915 + completing commit of new changeset</title> 1.1916 + 1.1917 + <para>This controlling hook is run before a 1.1918 + transaction&emdash;that manages a new commit&emdash;completes. 1.1919 + If the hook succeeds, the transaction completes and the 1.1920 + changeset becomes permanent within this repository. If the 1.1921 + hook fails, the transaction is rolled back, and the commit 1.1922 + data is erased. 1.1923 + </para> 1.1924 + 1.1925 + <para>This hook can access the metadata associated with the 1.1926 + almost-new changeset, but it should not do anything permanent 1.1927 + with this data. It must also not modify the working 1.1928 + directory. 1.1929 + </para> 1.1930 + 1.1931 + <para>While this hook is running, if other Mercurial processes 1.1932 + access this repository, they will be able to see the 1.1933 + almost-new changeset as if it is permanent. This may lead to 1.1934 + race conditions if you do not take steps to avoid them. 1.1935 + </para> 1.1936 + 1.1937 + <para>Parameters to this hook: 1.1938 + </para> 1.1939 + <itemizedlist> 1.1940 + <listitem><para><literal>node</literal>: A changeset ID. The 1.1941 + changeset ID of the newly committed changeset. 1.1942 + </para> 1.1943 + </listitem> 1.1944 + <listitem><para><literal>parent1</literal>: A changeset ID. 1.1945 + The changeset ID of the first parent of the newly 1.1946 + committed changeset. 1.1947 + </para> 1.1948 + </listitem> 1.1949 + <listitem><para><literal>parent2</literal>: A changeset ID. 1.1950 + The changeset ID of the second parent of the newly 1.1951 + committed changeset. 1.1952 + </para> 1.1953 + </listitem></itemizedlist> 1.1954 + 1.1955 + <para>See also: <literal role="hook">precommit</literal> 1.1956 + (section <xref linkend="sec:hook:precommit"/>) 1.1957 + </para> 1.1958 + 1.1959 + </sect2> 1.1960 + <sect2 id="sec:hook:preupdate"> 1.1961 + <title><literal role="hook">preupdate</literal>&emdash;before 1.1962 + updating or merging working directory</title> 1.1963 + 1.1964 + <para>This controlling hook is run before an update or merge of 1.1965 + the working directory begins. It is run only if Mercurial's 1.1966 + normal pre-update checks determine that the update or merge 1.1967 + can proceed. If the hook succeeds, the update or merge may 1.1968 + proceed; if it fails, the update or merge does not start. 1.1969 + </para> 1.1970 + 1.1971 + <para>Parameters to this hook: 1.1972 + </para> 1.1973 + <itemizedlist> 1.1974 + <listitem><para><literal>parent1</literal>: A changeset ID. 1.1975 + The ID of the parent that the working directory is to be 1.1976 + updated to. If the working directory is being merged, it 1.1977 + will not change this parent. 1.1978 + </para> 1.1979 + </listitem> 1.1980 + <listitem><para><literal>parent2</literal>: A changeset ID. 1.1981 + Only set if the working directory is being merged. The ID 1.1982 + of the revision that the working directory is being merged 1.1983 + with. 1.1984 + </para> 1.1985 + </listitem></itemizedlist> 1.1986 + 1.1987 + <para>See also: <literal role="hook">update</literal> (section 1.1988 + <xref linkend="sec:hook:update"/>) 1.1989 + </para> 1.1990 + 1.1991 + </sect2> 1.1992 + <sect2 id="sec:hook:tag"> 1.1993 + <title><literal role="hook">tag</literal>&emdash;after tagging a 1.1994 + changeset</title> 1.1995 + 1.1996 + <para>This hook is run after a tag has been created. 1.1997 + </para> 1.1998 + 1.1999 + <para>Parameters to this hook: 1.2000 + </para> 1.2001 + <itemizedlist> 1.2002 + <listitem><para><literal>local</literal>: A boolean. Whether 1.2003 + the new tag is local to this repository instance (i.e. 1.2004 + stored in <filename 1.2005 + role="special">.hg/localtags</filename>) or managed by 1.2006 + Mercurial (stored in <filename 1.2007 + role="special">.hgtags</filename>). 1.2008 + </para> 1.2009 + </listitem> 1.2010 + <listitem><para><literal>node</literal>: A changeset ID. The 1.2011 + ID of the changeset that was tagged. 1.2012 + </para> 1.2013 + </listitem> 1.2014 + <listitem><para><literal>tag</literal>: A string. The name of 1.2015 + the tag that was created. 1.2016 + </para> 1.2017 + </listitem></itemizedlist> 1.2018 + 1.2019 + <para>If the created tag is revision-controlled, the <literal 1.2020 + role="hook">commit</literal> hook (section <xref 1.2021 + linkend="sec:hook:commit"/>) is run before this hook. 1.2022 + </para> 1.2023 + 1.2024 + <para>See also: <literal role="hook">pretag</literal> (section 1.2025 + <xref linkend="sec:hook:pretag"/>) 1.2026 + </para> 1.2027 + 1.2028 + </sect2> 1.2029 + <sect2 id="sec:hook:update"> 1.2030 + <title><literal role="hook">update</literal>&emdash;after 1.2031 + updating or merging working directory</title> 1.2032 + 1.2033 + <para>This hook is run after an update or merge of the working 1.2034 + directory completes. Since a merge can fail (if the external 1.2035 + <command>hgmerge</command> command fails to resolve conflicts 1.2036 + in a file), this hook communicates whether the update or merge 1.2037 + completed cleanly. 1.2038 + </para> 1.2039 + 1.2040 + <itemizedlist> 1.2041 + <listitem><para><literal>error</literal>: A boolean. 1.2042 + Indicates whether the update or merge completed 1.2043 + successfully. 1.2044 + </para> 1.2045 + </listitem> 1.2046 + <listitem><para><literal>parent1</literal>: A changeset ID. 1.2047 + The ID of the parent that the working directory was 1.2048 + updated to. If the working directory was merged, it will 1.2049 + not have changed this parent. 1.2050 + </para> 1.2051 + </listitem> 1.2052 + <listitem><para><literal>parent2</literal>: A changeset ID. 1.2053 + Only set if the working directory was merged. The ID of 1.2054 + the revision that the working directory was merged with. 1.2055 + </para> 1.2056 + </listitem></itemizedlist> 1.2057 + 1.2058 + <para>See also: <literal role="hook">preupdate</literal> 1.2059 + (section <xref linkend="sec:hook:preupdate"/>) 1.2060 + </para> 1.2061 + 1.2062 + </sect2> 1.2063 + </sect1> 1.2064 +</chapter> 1.2065 + 1.2066 +<!-- 1.2067 +local variables: 1.2068 +sgml-parent-document: ("00book.xml" "book" "chapter") 1.2069 +end: 1.2070 +-->