1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch09-hook.xml	Fri Mar 20 16:43:35 2009 +0800
     1.3 @@ -0,0 +1,2037 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="chap.hook">
     1.7 +  <?dbhtml filename="handling-repository-events-with-hooks.html"?>
     1.8 +  <title>Handling repository events with hooks</title>
     1.9 +
    1.10 +  <para>Mercurial offers a powerful mechanism to let you perform
    1.11 +    automated actions in response to events that occur in a
    1.12 +    repository.  In some cases, you can even control Mercurial's
    1.13 +    response to those events.</para>
    1.14 +
    1.15 +  <para>The name Mercurial uses for one of these actions is a
    1.16 +    <emphasis>hook</emphasis>. Hooks are called
    1.17 +    <quote>triggers</quote> in some revision control systems, but the
    1.18 +    two names refer to the same idea.</para>
    1.19 +
    1.20 +  <sect1>
    1.21 +    <title>An overview of hooks in Mercurial</title>
    1.22 +
    1.23 +    <para>Here is a brief list of the hooks that Mercurial supports.
    1.24 +      We will revisit each of these hooks in more detail later, in
    1.25 +      section <xref linkend="sec.hook.ref"/>.</para>
    1.26 +
    1.27 +    <itemizedlist>
    1.28 +      <listitem><para><literal role="hook">changegroup</literal>: This
    1.29 +	  is run after a group of changesets has been brought into the
    1.30 +	  repository from elsewhere.</para>
    1.31 +      </listitem>
    1.32 +      <listitem><para><literal role="hook">commit</literal>: This is
    1.33 +	  run after a new changeset has been created in the local
    1.34 +	  repository.</para>
    1.35 +      </listitem>
    1.36 +      <listitem><para><literal role="hook">incoming</literal>: This is
    1.37 +	  run once for each new changeset that is brought into the
    1.38 +	  repository from elsewhere.  Notice the difference from
    1.39 +	  <literal role="hook">changegroup</literal>, which is run
    1.40 +	  once per <emphasis>group</emphasis> of changesets brought
    1.41 +	  in.</para>
    1.42 +      </listitem>
    1.43 +      <listitem><para><literal role="hook">outgoing</literal>: This is
    1.44 +	  run after a group of changesets has been transmitted from
    1.45 +	  this repository.</para>
    1.46 +      </listitem>
    1.47 +      <listitem><para><literal role="hook">prechangegroup</literal>:
    1.48 +	  This is run before starting to bring a group of changesets
    1.49 +	  into the repository.
    1.50 +	</para>
    1.51 +      </listitem>
    1.52 +      <listitem><para><literal role="hook">precommit</literal>:
    1.53 +	  Controlling. This is run before starting a commit.
    1.54 +	</para>
    1.55 +      </listitem>
    1.56 +      <listitem><para><literal role="hook">preoutgoing</literal>:
    1.57 +	  Controlling. This is run before starting to transmit a group
    1.58 +	  of changesets from this repository.
    1.59 +	</para>
    1.60 +      </listitem>
    1.61 +      <listitem><para><literal role="hook">pretag</literal>:
    1.62 +	  Controlling. This is run before creating a tag.
    1.63 +	</para>
    1.64 +      </listitem>
    1.65 +      <listitem><para><literal
    1.66 +	    role="hook">pretxnchangegroup</literal>: Controlling. This
    1.67 +	  is run after a group of changesets has been brought into the
    1.68 +	  local repository from another, but before the transaction
    1.69 +	  completes that will make the changes permanent in the
    1.70 +	  repository.
    1.71 +	</para>
    1.72 +      </listitem>
    1.73 +      <listitem><para><literal role="hook">pretxncommit</literal>:
    1.74 +	  Controlling. This is run after a new changeset has been
    1.75 +	  created in the local repository, but before the transaction
    1.76 +	  completes that will make it permanent.
    1.77 +	</para>
    1.78 +      </listitem>
    1.79 +      <listitem><para><literal role="hook">preupdate</literal>:
    1.80 +	  Controlling. This is run before starting an update or merge
    1.81 +	  of the working directory.
    1.82 +	</para>
    1.83 +      </listitem>
    1.84 +      <listitem><para><literal role="hook">tag</literal>: This is run
    1.85 +	  after a tag is created.
    1.86 +	</para>
    1.87 +      </listitem>
    1.88 +      <listitem><para><literal role="hook">update</literal>: This is
    1.89 +	  run after an update or merge of the working directory has
    1.90 +	  finished.
    1.91 +	</para>
    1.92 +      </listitem></itemizedlist>
    1.93 +    <para>Each of the hooks whose description begins with the word
    1.94 +      <quote>Controlling</quote> has the ability to determine whether
    1.95 +      an activity can proceed.  If the hook succeeds, the activity may
    1.96 +      proceed; if it fails, the activity is either not permitted or
    1.97 +      undone, depending on the hook.
    1.98 +    </para>
    1.99 +
   1.100 +  </sect1>
   1.101 +  <sect1>
   1.102 +    <title>Hooks and security</title>
   1.103 +
   1.104 +    <sect2>
   1.105 +      <title>Hooks are run with your privileges</title>
   1.106 +
   1.107 +      <para>When you run a Mercurial command in a repository, and the
   1.108 +	command causes a hook to run, that hook runs on
   1.109 +	<emphasis>your</emphasis> system, under
   1.110 +	<emphasis>your</emphasis> user account, with
   1.111 +	<emphasis>your</emphasis> privilege level.  Since hooks are
   1.112 +	arbitrary pieces of executable code, you should treat them
   1.113 +	with an appropriate level of suspicion.  Do not install a hook
   1.114 +	unless you are confident that you know who created it and what
   1.115 +	it does.
   1.116 +      </para>
   1.117 +
   1.118 +      <para>In some cases, you may be exposed to hooks that you did
   1.119 +	not install yourself.  If you work with Mercurial on an
   1.120 +	unfamiliar system, Mercurial will run hooks defined in that
   1.121 +	system's global <filename role="special">~/.hgrc</filename>
   1.122 +	file.
   1.123 +      </para>
   1.124 +
   1.125 +      <para>If you are working with a repository owned by another
   1.126 +	user, Mercurial can run hooks defined in that user's
   1.127 +	repository, but it will still run them as <quote>you</quote>.
   1.128 +	For example, if you <command role="hg-cmd">hg pull</command>
   1.129 +	from that repository, and its <filename
   1.130 +	  role="special">.hg/hgrc</filename> defines a local <literal
   1.131 +	  role="hook">outgoing</literal> hook, that hook will run
   1.132 +	under your user account, even though you don't own that
   1.133 +	repository.
   1.134 +      </para>
   1.135 +
   1.136 +      <note>
   1.137 +	<para>  This only applies if you are pulling from a repository
   1.138 +	  on a local or network filesystem.  If you're pulling over
   1.139 +	  http or ssh, any <literal role="hook">outgoing</literal>
   1.140 +	  hook will run under whatever account is executing the server
   1.141 +	  process, on the server.
   1.142 +	</para>
   1.143 +      </note>
   1.144 +
   1.145 +      <para>XXX To see what hooks are defined in a repository, use the
   1.146 +	<command role="hg-cmd">hg config hooks</command> command.  If
   1.147 +	you are working in one repository, but talking to another that
   1.148 +	you do not own (e.g. using <command role="hg-cmd">hg
   1.149 +	  pull</command> or <command role="hg-cmd">hg
   1.150 +	  incoming</command>), remember that it is the other
   1.151 +	repository's hooks you should be checking, not your own.
   1.152 +      </para>
   1.153 +
   1.154 +    </sect2>
   1.155 +    <sect2>
   1.156 +      <title>Hooks do not propagate</title>
   1.157 +
   1.158 +      <para>In Mercurial, hooks are not revision controlled, and do
   1.159 +	not propagate when you clone, or pull from, a repository.  The
   1.160 +	reason for this is simple: a hook is a completely arbitrary
   1.161 +	piece of executable code.  It runs under your user identity,
   1.162 +	with your privilege level, on your machine.
   1.163 +      </para>
   1.164 +
   1.165 +      <para>It would be extremely reckless for any distributed
   1.166 +	revision control system to implement revision-controlled
   1.167 +	hooks, as this would offer an easily exploitable way to
   1.168 +	subvert the accounts of users of the revision control system.
   1.169 +      </para>
   1.170 +
   1.171 +      <para>Since Mercurial does not propagate hooks, if you are
   1.172 +	collaborating with other people on a common project, you
   1.173 +	should not assume that they are using the same Mercurial hooks
   1.174 +	as you are, or that theirs are correctly configured.  You
   1.175 +	should document the hooks you expect people to use.
   1.176 +      </para>
   1.177 +
   1.178 +      <para>In a corporate intranet, this is somewhat easier to
   1.179 +	control, as you can for example provide a
   1.180 +	<quote>standard</quote> installation of Mercurial on an NFS
   1.181 +	filesystem, and use a site-wide <filename role="special">~/.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]
   1.585 +commit.example = 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]
   1.751 +pretxnchangegroup.acl = 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]
   1.819 +docs/** = docwriter
   1.820 +[acl.deny]
   1.821 +source/sensitive/** = intern</programlisting>
   1.822 +
   1.823 +      </sect3>
   1.824 +      <sect3>
   1.825 +	<title>Testing and troubleshooting</title>
   1.826 +
   1.827 +	<para>If you want to test the <literal
   1.828 +	    role="hg-ext">acl</literal> hook, run it with Mercurial's
   1.829 +	  debugging output enabled.  Since you'll probably be running
   1.830 +	  it on a server where it's not convenient (or sometimes
   1.831 +	  possible) to pass in the <option
   1.832 +	    role="hg-opt-global">--debug</option> option, don't forget
   1.833 +	  that you can enable debugging output in your <filename
   1.834 +	    role="special">~/.hgrc</filename>:
   1.835 +	</para>
   1.836 +	<programlisting>[ui]
   1.837 +debug = true</programlisting>
   1.838 +	<para>With this enabled, the <literal
   1.839 +	    role="hg-ext">acl</literal> hook will print enough
   1.840 +	  information to let you figure out why it is allowing or
   1.841 +	  forbidding pushes from specific users.
   1.842 +	</para>
   1.843 +
   1.844 +      </sect3>
   1.845 +    </sect2>
   1.846 +    <sect2>
   1.847 +      <title><literal
   1.848 +	  role="hg-ext">bugzilla</literal>&emdash;integration with
   1.849 +	Bugzilla</title>
   1.850 +
   1.851 +      <para>The <literal role="hg-ext">bugzilla</literal> extension
   1.852 +	adds a comment to a Bugzilla bug whenever it finds a reference
   1.853 +	to that bug ID in a commit comment.  You can install this hook
   1.854 +	on a shared server, so that any time a remote user pushes
   1.855 +	changes to this server, the hook gets run.
   1.856 +      </para>
   1.857 +
   1.858 +      <para>It adds a comment to the bug that looks like this (you can
   1.859 +	configure the contents of the comment&emdash;see below):
   1.860 +      </para>
   1.861 +      <programlisting>Changeset aad8b264143a, made by Joe User
   1.862 +	&lt;joe.user@domain.com&gt; in the frobnitz repository, refers
   1.863 +	to this bug. For complete details, see
   1.864 +	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
   1.865 +	Changeset description: Fix bug 10483 by guarding against some
   1.866 +	NULL pointers</programlisting>
   1.867 +      <para>The value of this hook is that it automates the process of
   1.868 +	updating a bug any time a changeset refers to it.  If you
   1.869 +	configure the hook properly, it makes it easy for people to
   1.870 +	browse straight from a Bugzilla bug to a changeset that refers
   1.871 +	to that bug.
   1.872 +      </para>
   1.873 +
   1.874 +      <para>You can use the code in this hook as a starting point for
   1.875 +	some more exotic Bugzilla integration recipes.  Here are a few
   1.876 +	possibilities:
   1.877 +      </para>
   1.878 +      <itemizedlist>
   1.879 +	<listitem><para>Require that every changeset pushed to the
   1.880 +	    server have a valid bug ID in its commit comment.  In this
   1.881 +	    case, you'd want to configure the hook as a <literal
   1.882 +	      role="hook">pretxncommit</literal> hook.  This would
   1.883 +	    allow the hook to reject changes that didn't contain bug
   1.884 +	    IDs.
   1.885 +	  </para>
   1.886 +	</listitem>
   1.887 +	<listitem><para>Allow incoming changesets to automatically
   1.888 +	    modify the <emphasis>state</emphasis> of a bug, as well as
   1.889 +	    simply adding a comment.  For example, the hook could
   1.890 +	    recognise the string <quote>fixed bug 31337</quote> as
   1.891 +	    indicating that it should update the state of bug 31337 to
   1.892 +	    <quote>requires testing</quote>.
   1.893 +	  </para>
   1.894 +	</listitem></itemizedlist>
   1.895 +
   1.896 +      <sect3 id="sec.hook.bugzilla.config">
   1.897 +	<title>Configuring the <literal role="hook">bugzilla</literal>
   1.898 +	  hook</title>
   1.899 +
   1.900 +	<para>You should configure this hook in your server's
   1.901 +	  <filename role="special">~/.hgrc</filename> as an <literal
   1.902 +	    role="hook">incoming</literal> hook, for example as
   1.903 +	  follows:
   1.904 +	</para>
   1.905 +	<programlisting>[hooks]
   1.906 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
   1.907 +
   1.908 +	<para>Because of the specialised nature of this hook, and
   1.909 +	  because Bugzilla was not written with this kind of
   1.910 +	  integration in mind, configuring this hook is a somewhat
   1.911 +	  involved process.
   1.912 +	</para>
   1.913 +
   1.914 +	<para>Before you begin, you must install the MySQL bindings
   1.915 +	  for Python on the host(s) where you'll be running the hook.
   1.916 +	  If this is not available as a binary package for your
   1.917 +	  system, you can download it from
   1.918 +	  <citation>web:mysql-python</citation>.
   1.919 +	</para>
   1.920 +
   1.921 +	<para>Configuration information for this hook lives in the
   1.922 +	  <literal role="rc-bugzilla">bugzilla</literal> section of
   1.923 +	  your <filename role="special">~/.hgrc</filename>.
   1.924 +	</para>
   1.925 +	<itemizedlist>
   1.926 +	  <listitem><para><envar
   1.927 +		role="rc-item-bugzilla">version</envar>: The version
   1.928 +	      of Bugzilla installed on the server.  The database
   1.929 +	      schema that Bugzilla uses changes occasionally, so this
   1.930 +	      hook has to know exactly which schema to use. At the
   1.931 +	      moment, the only version supported is
   1.932 +	      <literal>2.16</literal>.
   1.933 +	    </para>
   1.934 +	  </listitem>
   1.935 +	  <listitem><para><envar role="rc-item-bugzilla">host</envar>:
   1.936 +	      The hostname of the MySQL server that stores your
   1.937 +	      Bugzilla data.  The database must be configured to allow
   1.938 +	      connections from whatever host you are running the
   1.939 +	      <literal role="hook">bugzilla</literal> hook on.
   1.940 +	    </para>
   1.941 +	  </listitem>
   1.942 +	  <listitem><para><envar role="rc-item-bugzilla">user</envar>:
   1.943 +	      The username with which to connect to the MySQL server.
   1.944 +	      The database must be configured to allow this user to
   1.945 +	      connect from whatever host you are running the <literal
   1.946 +		role="hook">bugzilla</literal> hook on.  This user
   1.947 +	      must be able to access and modify Bugzilla tables.  The
   1.948 +	      default value of this item is <literal>bugs</literal>,
   1.949 +	      which is the standard name of the Bugzilla user in a
   1.950 +	      MySQL database.
   1.951 +	    </para>
   1.952 +	  </listitem>
   1.953 +	  <listitem><para><envar
   1.954 +		role="rc-item-bugzilla">password</envar>: The MySQL
   1.955 +	      password for the user you configured above.  This is
   1.956 +	      stored as plain text, so you should make sure that
   1.957 +	      unauthorised users cannot read the <filename
   1.958 +		role="special">~/.hgrc</filename> file where you
   1.959 +	      store this information.
   1.960 +	    </para>
   1.961 +	  </listitem>
   1.962 +	  <listitem><para><envar role="rc-item-bugzilla">db</envar>:
   1.963 +	      The name of the Bugzilla database on the MySQL server.
   1.964 +	      The default value of this item is
   1.965 +	      <literal>bugs</literal>, which is the standard name of
   1.966 +	      the MySQL database where Bugzilla stores its data.
   1.967 +	    </para>
   1.968 +	  </listitem>
   1.969 +	  <listitem><para><envar
   1.970 +		role="rc-item-bugzilla">notify</envar>: If you want
   1.971 +	      Bugzilla to send out a notification email to subscribers
   1.972 +	      after this hook has added a comment to a bug, you will
   1.973 +	      need this hook to run a command whenever it updates the
   1.974 +	      database.  The command to run depends on where you have
   1.975 +	      installed Bugzilla, but it will typically look something
   1.976 +	      like this, if you have Bugzilla installed in <filename
   1.977 +		class="directory">/var/www/html/bugzilla</filename>:
   1.978 +	    </para>
   1.979 +	    <programlisting>cd /var/www/html/bugzilla &amp;&amp;
   1.980 +	      ./processmail %s nobody@nowhere.com</programlisting>
   1.981 +	  </listitem>
   1.982 +	  <listitem><para>  The Bugzilla
   1.983 +	      <literal>processmail</literal> program expects to be
   1.984 +	      given a bug ID (the hook replaces
   1.985 +	      <quote><literal>%s</literal></quote> with the bug ID)
   1.986 +	      and an email address.  It also expects to be able to
   1.987 +	      write to some files in the directory that it runs in.
   1.988 +	      If Bugzilla and this hook are not installed on the same
   1.989 +	      machine, you will need to find a way to run
   1.990 +	      <literal>processmail</literal> on the server where
   1.991 +	      Bugzilla is installed.
   1.992 +	    </para>
   1.993 +	  </listitem></itemizedlist>
   1.994 +
   1.995 +      </sect3>
   1.996 +      <sect3>
   1.997 +	<title>Mapping committer names to Bugzilla user names</title>
   1.998 +
   1.999 +	<para>By default, the <literal
  1.1000 +	    role="hg-ext">bugzilla</literal> hook tries to use the
  1.1001 +	  email address of a changeset's committer as the Bugzilla
  1.1002 +	  user name with which to update a bug.  If this does not suit
  1.1003 +	  your needs, you can map committer email addresses to
  1.1004 +	  Bugzilla user names using a <literal
  1.1005 +	    role="rc-usermap">usermap</literal> section.
  1.1006 +	</para>
  1.1007 +
  1.1008 +	<para>Each item in the <literal
  1.1009 +	    role="rc-usermap">usermap</literal> section contains an
  1.1010 +	  email address on the left, and a Bugzilla user name on the
  1.1011 +	  right.
  1.1012 +	</para>
  1.1013 +	<programlisting>[usermap]
  1.1014 +jane.user@example.com = jane</programlisting>
  1.1015 +	<para>You can either keep the <literal
  1.1016 +	    role="rc-usermap">usermap</literal> data in a normal
  1.1017 +	  <filename role="special">~/.hgrc</filename>, or tell the
  1.1018 +	  <literal role="hg-ext">bugzilla</literal> hook to read the
  1.1019 +	  information from an external <filename>usermap</filename>
  1.1020 +	  file.  In the latter case, you can store
  1.1021 +	  <filename>usermap</filename> data by itself in (for example)
  1.1022 +	  a user-modifiable repository.  This makes it possible to let
  1.1023 +	  your users maintain their own <envar
  1.1024 +	    role="rc-item-bugzilla">usermap</envar> entries.  The main
  1.1025 +	  <filename role="special">~/.hgrc</filename> file might look
  1.1026 +	  like this:
  1.1027 +	</para>
  1.1028 +	<programlisting># regular hgrc file refers to external usermap file
  1.1029 +[bugzilla]
  1.1030 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
  1.1031 +	<para>While the <filename>usermap</filename> file that it
  1.1032 +	  refers to might look like this:
  1.1033 +	</para>
  1.1034 +	<programlisting># bugzilla-usermap.conf - inside a hg repository
  1.1035 +[usermap] stephanie@example.com = steph</programlisting>
  1.1036 +
  1.1037 +      </sect3>
  1.1038 +      <sect3>
  1.1039 +	<title>Configuring the text that gets added to a bug</title>
  1.1040 +
  1.1041 +	<para>You can configure the text that this hook adds as a
  1.1042 +	  comment; you specify it in the form of a Mercurial template.
  1.1043 +	  Several <filename role="special">~/.hgrc</filename> entries
  1.1044 +	  (still in the <literal role="rc-bugzilla">bugzilla</literal>
  1.1045 +	  section) control this behaviour.
  1.1046 +	</para>
  1.1047 +	<itemizedlist>
  1.1048 +	  <listitem><para><literal>strip</literal>: The number of
  1.1049 +	      leading path elements to strip from a repository's path
  1.1050 +	      name to construct a partial path for a URL. For example,
  1.1051 +	      if the repositories on your server live under <filename
  1.1052 +		class="directory">/home/hg/repos</filename>, and you
  1.1053 +	      have a repository whose path is <filename
  1.1054 +		class="directory">/home/hg/repos/app/tests</filename>,
  1.1055 +	      then setting <literal>strip</literal> to
  1.1056 +	      <literal>4</literal> will give a partial path of
  1.1057 +	      <filename class="directory">app/tests</filename>.  The
  1.1058 +	      hook will make this partial path available when
  1.1059 +	      expanding a template, as <literal>webroot</literal>.
  1.1060 +	    </para>
  1.1061 +	  </listitem>
  1.1062 +	  <listitem><para><literal>template</literal>: The text of the
  1.1063 +	      template to use.  In addition to the usual
  1.1064 +	      changeset-related variables, this template can use
  1.1065 +	      <literal>hgweb</literal> (the value of the
  1.1066 +	      <literal>hgweb</literal> configuration item above) and
  1.1067 +	      <literal>webroot</literal> (the path constructed using
  1.1068 +	      <literal>strip</literal> above).
  1.1069 +	    </para>
  1.1070 +	  </listitem></itemizedlist>
  1.1071 +
  1.1072 +	<para>In addition, you can add a <envar
  1.1073 +	    role="rc-item-web">baseurl</envar> item to the <literal
  1.1074 +	    role="rc-web">web</literal> section of your <filename
  1.1075 +	    role="special">~/.hgrc</filename>.  The <literal
  1.1076 +	    role="hg-ext">bugzilla</literal> hook will make this
  1.1077 +	  available when expanding a template, as the base string to
  1.1078 +	  use when constructing a URL that will let users browse from
  1.1079 +	  a Bugzilla comment to view a changeset.  Example:
  1.1080 +	</para>
  1.1081 +	<programlisting>[web]
  1.1082 +baseurl = http://hg.domain.com/</programlisting>
  1.1083 +
  1.1084 +	<para>Here is an example set of <literal
  1.1085 +	    role="hg-ext">bugzilla</literal> hook config information.
  1.1086 +	</para>
  1.1087 +
  1.1088 +	<programlisting>&ch10-bugzilla-config.lst;</programlisting>
  1.1089 +
  1.1090 +      </sect3>
  1.1091 +      <sect3>
  1.1092 +	<title>Testing and troubleshooting</title>
  1.1093 +
  1.1094 +	<para>The most common problems with configuring the <literal
  1.1095 +	    role="hg-ext">bugzilla</literal> hook relate to running
  1.1096 +	  Bugzilla's <filename>processmail</filename> script and
  1.1097 +	  mapping committer names to user names.
  1.1098 +	</para>
  1.1099 +
  1.1100 +	<para>Recall from section <xref
  1.1101 +	    linkend="sec.hook.bugzilla.config"/> above that the user
  1.1102 +	  that runs the Mercurial process on the server is also the
  1.1103 +	  one that will run the <filename>processmail</filename>
  1.1104 +	  script.  The <filename>processmail</filename> script
  1.1105 +	  sometimes causes Bugzilla to write to files in its
  1.1106 +	  configuration directory, and Bugzilla's configuration files
  1.1107 +	  are usually owned by the user that your web server runs
  1.1108 +	  under.
  1.1109 +	</para>
  1.1110 +
  1.1111 +	<para>You can cause <filename>processmail</filename> to be run
  1.1112 +	  with the suitable user's identity using the
  1.1113 +	  <command>sudo</command> command.  Here is an example entry
  1.1114 +	  for a <filename>sudoers</filename> file.
  1.1115 +	</para>
  1.1116 +	<programlisting>hg_user = (httpd_user)
  1.1117 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
  1.1118 +	<para>This allows the <literal>hg_user</literal> user to run a
  1.1119 +	  <filename>processmail-wrapper</filename> program under the
  1.1120 +	  identity of <literal>httpd_user</literal>.
  1.1121 +	</para>
  1.1122 +
  1.1123 +	<para>This indirection through a wrapper script is necessary,
  1.1124 +	  because <filename>processmail</filename> expects to be run
  1.1125 +	  with its current directory set to wherever you installed
  1.1126 +	  Bugzilla; you can't specify that kind of constraint in a
  1.1127 +	  <filename>sudoers</filename> file.  The contents of the
  1.1128 +	  wrapper script are simple:
  1.1129 +	</para>
  1.1130 +	<programlisting>#!/bin/sh
  1.1131 +cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
  1.1132 +	<para>It doesn't seem to matter what email address you pass to
  1.1133 +	  <filename>processmail</filename>.
  1.1134 +	</para>
  1.1135 +
  1.1136 +	<para>If your <literal role="rc-usermap">usermap</literal> is
  1.1137 +	  not set up correctly, users will see an error message from
  1.1138 +	  the <literal role="hg-ext">bugzilla</literal> hook when they
  1.1139 +	  push changes to the server.  The error message will look
  1.1140 +	  like this:
  1.1141 +	</para>
  1.1142 +	<programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting>
  1.1143 +	<para>What this means is that the committer's address,
  1.1144 +	  <literal>john.q.public@example.com</literal>, is not a valid
  1.1145 +	  Bugzilla user name, nor does it have an entry in your
  1.1146 +	  <literal role="rc-usermap">usermap</literal> that maps it to
  1.1147 +	  a valid Bugzilla user name.
  1.1148 +	</para>
  1.1149 +
  1.1150 +      </sect3>
  1.1151 +    </sect2>
  1.1152 +    <sect2>
  1.1153 +      <title><literal role="hg-ext">notify</literal>&emdash;send email
  1.1154 +	notifications</title>
  1.1155 +
  1.1156 +      <para>Although Mercurial's built-in web server provides RSS
  1.1157 +	feeds of changes in every repository, many people prefer to
  1.1158 +	receive change notifications via email.  The <literal
  1.1159 +	  role="hg-ext">notify</literal> hook lets you send out
  1.1160 +	notifications to a set of email addresses whenever changesets
  1.1161 +	arrive that those subscribers are interested in.
  1.1162 +      </para>
  1.1163 +
  1.1164 +      <para>As with the <literal role="hg-ext">bugzilla</literal>
  1.1165 +	hook, the <literal role="hg-ext">notify</literal> hook is
  1.1166 +	template-driven, so you can customise the contents of the
  1.1167 +	notification messages that it sends.
  1.1168 +      </para>
  1.1169 +
  1.1170 +      <para>By default, the <literal role="hg-ext">notify</literal>
  1.1171 +	hook includes a diff of every changeset that it sends out; you
  1.1172 +	can limit the size of the diff, or turn this feature off
  1.1173 +	entirely.  It is useful for letting subscribers review changes
  1.1174 +	immediately, rather than clicking to follow a URL.
  1.1175 +      </para>
  1.1176 +
  1.1177 +      <sect3>
  1.1178 +	<title>Configuring the <literal role="hg-ext">notify</literal>
  1.1179 +	  hook</title>
  1.1180 +
  1.1181 +	<para>You can set up the <literal
  1.1182 +	    role="hg-ext">notify</literal> hook to send one email
  1.1183 +	  message per incoming changeset, or one per incoming group of
  1.1184 +	  changesets (all those that arrived in a single pull or
  1.1185 +	  push).
  1.1186 +	</para>
  1.1187 +	<programlisting>[hooks]
  1.1188 +# send one email per group of changes
  1.1189 +changegroup.notify = python:hgext.notify.hook
  1.1190 +# send one email per change
  1.1191 +incoming.notify = python:hgext.notify.hook</programlisting>
  1.1192 +
  1.1193 +	<para>Configuration information for this hook lives in the
  1.1194 +	  <literal role="rc-notify">notify</literal> section of a
  1.1195 +	  <filename role="special">~/.hgrc</filename> file.
  1.1196 +	</para>
  1.1197 +	<itemizedlist>
  1.1198 +	  <listitem><para><envar role="rc-item-notify">test</envar>:
  1.1199 +	      By default, this hook does not send out email at all;
  1.1200 +	      instead, it prints the message that it
  1.1201 +	      <emphasis>would</emphasis> send.  Set this item to
  1.1202 +	      <literal>false</literal> to allow email to be sent. The
  1.1203 +	      reason that sending of email is turned off by default is
  1.1204 +	      that it takes several tries to configure this extension
  1.1205 +	      exactly as you would like, and it would be bad form to
  1.1206 +	      spam subscribers with a number of <quote>broken</quote>
  1.1207 +	      notifications while you debug your configuration.
  1.1208 +	    </para>
  1.1209 +	  </listitem>
  1.1210 +	  <listitem><para><envar role="rc-item-notify">config</envar>:
  1.1211 +	      The path to a configuration file that contains
  1.1212 +	      subscription information.  This is kept separate from
  1.1213 +	      the main <filename role="special">~/.hgrc</filename> so
  1.1214 +	      that you can maintain it in a repository of its own.
  1.1215 +	      People can then clone that repository, update their
  1.1216 +	      subscriptions, and push the changes back to your server.
  1.1217 +	    </para>
  1.1218 +	  </listitem>
  1.1219 +	  <listitem><para><envar role="rc-item-notify">strip</envar>:
  1.1220 +	      The number of leading path separator characters to strip
  1.1221 +	      from a repository's path, when deciding whether a
  1.1222 +	      repository has subscribers.  For example, if the
  1.1223 +	      repositories on your server live in <filename
  1.1224 +		class="directory">/home/hg/repos</filename>, and
  1.1225 +	      <literal role="hg-ext">notify</literal> is considering a
  1.1226 +	      repository named <filename
  1.1227 +		class="directory">/home/hg/repos/shared/test</filename>, 
  1.1228 +	      setting <envar role="rc-item-notify">strip</envar> to
  1.1229 +	      <literal>4</literal> will cause <literal
  1.1230 +		role="hg-ext">notify</literal> to trim the path it
  1.1231 +	      considers down to <filename
  1.1232 +		class="directory">shared/test</filename>, and it will
  1.1233 +	      match subscribers against that.
  1.1234 +	    </para>
  1.1235 +	  </listitem>
  1.1236 +	  <listitem><para><envar
  1.1237 +		role="rc-item-notify">template</envar>: The template
  1.1238 +	      text to use when sending messages.  This specifies both
  1.1239 +	      the contents of the message header and its body.
  1.1240 +	    </para>
  1.1241 +	  </listitem>
  1.1242 +	  <listitem><para><envar
  1.1243 +		role="rc-item-notify">maxdiff</envar>: The maximum
  1.1244 +	      number of lines of diff data to append to the end of a
  1.1245 +	      message.  If a diff is longer than this, it is
  1.1246 +	      truncated.  By default, this is set to 300.  Set this to
  1.1247 +	      <literal>0</literal> to omit diffs from notification
  1.1248 +	      emails.
  1.1249 +	    </para>
  1.1250 +	  </listitem>
  1.1251 +	  <listitem><para><envar
  1.1252 +		role="rc-item-notify">sources</envar>: A list of
  1.1253 +	      sources of changesets to consider.  This lets you limit
  1.1254 +	      <literal role="hg-ext">notify</literal> to only sending
  1.1255 +	      out email about changes that remote users pushed into
  1.1256 +	      this repository via a server, for example.  See section
  1.1257 +	      <xref
  1.1258 +		linkend="sec.hook.sources"/> for the sources you can
  1.1259 +	      specify here.
  1.1260 +	    </para>
  1.1261 +	  </listitem></itemizedlist>
  1.1262 +
  1.1263 +	<para>If you set the <envar role="rc-item-web">baseurl</envar>
  1.1264 +	  item in the <literal role="rc-web">web</literal> section,
  1.1265 +	  you can use it in a template; it will be available as
  1.1266 +	  <literal>webroot</literal>.
  1.1267 +	</para>
  1.1268 +
  1.1269 +	<para>Here is an example set of <literal
  1.1270 +	    role="hg-ext">notify</literal> configuration information.
  1.1271 +	</para>
  1.1272 +
  1.1273 +	<programlisting>&ch10-notify-config.lst;</programlisting>
  1.1274 +
  1.1275 +	<para>This will produce a message that looks like the
  1.1276 +	  following:
  1.1277 +	</para>
  1.1278 +
  1.1279 +	<programlisting>&ch10-notify-config-mail.lst;</programlisting>
  1.1280 +
  1.1281 +      </sect3>
  1.1282 +      <sect3>
  1.1283 +	<title>Testing and troubleshooting</title>
  1.1284 +
  1.1285 +	<para>Do not forget that by default, the <literal
  1.1286 +		role="hg-ext">notify</literal> extension <emphasis>will not
  1.1287 +	  send any mail</emphasis> until you explicitly configure it to do so,
  1.1288 +	  by setting <envar role="rc-item-notify">test</envar> to
  1.1289 +	  <literal>false</literal>.  Until you do that, it simply
  1.1290 +	  prints the message it <emphasis>would</emphasis> send.
  1.1291 +	</para>
  1.1292 +
  1.1293 +      </sect3>
  1.1294 +    </sect2>
  1.1295 +  </sect1>
  1.1296 +  <sect1 id="sec.hook.ref">
  1.1297 +    <title>Information for writers of hooks</title>
  1.1298 +
  1.1299 +    <sect2>
  1.1300 +      <title>In-process hook execution</title>
  1.1301 +
  1.1302 +      <para>An in-process hook is called with arguments of the
  1.1303 +	following form:
  1.1304 +      </para>
  1.1305 +      <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting>
  1.1306 +      <para>The <literal>ui</literal> parameter is a <literal
  1.1307 +	  role="py-mod-mercurial.ui">ui</literal> object. The
  1.1308 +	<literal>repo</literal> parameter is a <literal
  1.1309 +	  role="py-mod-mercurial.localrepo">localrepository</literal>
  1.1310 +	object.  The names and values of the
  1.1311 +	<literal>**kwargs</literal> parameters depend on the hook
  1.1312 +	being invoked, with the following common features:
  1.1313 +      </para>
  1.1314 +      <itemizedlist>
  1.1315 +	<listitem><para>If a parameter is named
  1.1316 +	    <literal>node</literal> or <literal>parentN</literal>, it
  1.1317 +	    will contain a hexadecimal changeset ID. The empty string
  1.1318 +	    is used to represent <quote>null changeset ID</quote>
  1.1319 +	    instead of a string of zeroes.
  1.1320 +	  </para>
  1.1321 +	</listitem>
  1.1322 +	<listitem><para>If a parameter is named
  1.1323 +	    <literal>url</literal>, it will contain the URL of a
  1.1324 +	    remote repository, if that can be determined.
  1.1325 +	  </para>
  1.1326 +	</listitem>
  1.1327 +	<listitem><para>Boolean-valued parameters are represented as
  1.1328 +	    Python <literal>bool</literal> objects.
  1.1329 +	  </para>
  1.1330 +	</listitem></itemizedlist>
  1.1331 +
  1.1332 +      <para>An in-process hook is called without a change to the
  1.1333 +	process's working directory (unlike external hooks, which are
  1.1334 +	run in the root of the repository).  It must not change the
  1.1335 +	process's working directory, or it will cause any calls it
  1.1336 +	makes into the Mercurial API to fail.
  1.1337 +      </para>
  1.1338 +
  1.1339 +      <para>If a hook returns a boolean <quote>false</quote> value, it
  1.1340 +	is considered to have succeeded.  If it returns a boolean
  1.1341 +	<quote>true</quote> value or raises an exception, it is
  1.1342 +	considered to have failed.  A useful way to think of the
  1.1343 +	calling convention is <quote>tell me if you fail</quote>.
  1.1344 +      </para>
  1.1345 +
  1.1346 +      <para>Note that changeset IDs are passed into Python hooks as
  1.1347 +	hexadecimal strings, not the binary hashes that Mercurial's
  1.1348 +	APIs normally use.  To convert a hash from hex to binary, use
  1.1349 +	the <literal>bin</literal> function.
  1.1350 +      </para>
  1.1351 +
  1.1352 +    </sect2>
  1.1353 +    <sect2>
  1.1354 +      <title>External hook execution</title>
  1.1355 +
  1.1356 +      <para>An external hook is passed to the shell of the user
  1.1357 +	running Mercurial. Features of that shell, such as variable
  1.1358 +	substitution and command redirection, are available.  The hook
  1.1359 +	is run in the root directory of the repository (unlike
  1.1360 +	in-process hooks, which are run in the same directory that
  1.1361 +	Mercurial was run in).
  1.1362 +      </para>
  1.1363 +
  1.1364 +      <para>Hook parameters are passed to the hook as environment
  1.1365 +	variables.  Each environment variable's name is converted in
  1.1366 +	upper case and prefixed with the string
  1.1367 +	<quote><literal>HG_</literal></quote>.  For example, if the
  1.1368 +	name of a parameter is <quote><literal>node</literal></quote>,
  1.1369 +	the name of the environment variable representing that
  1.1370 +	parameter will be <quote><literal>HG_NODE</literal></quote>.
  1.1371 +      </para>
  1.1372 +
  1.1373 +      <para>A boolean parameter is represented as the string
  1.1374 +	<quote><literal>1</literal></quote> for <quote>true</quote>,
  1.1375 +	<quote><literal>0</literal></quote> for <quote>false</quote>.
  1.1376 +	If an environment variable is named <envar>HG_NODE</envar>,
  1.1377 +	<envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
  1.1378 +	contains a changeset ID represented as a hexadecimal string.
  1.1379 +	The empty string is used to represent <quote>null changeset
  1.1380 +	  ID</quote> instead of a string of zeroes.  If an environment
  1.1381 +	variable is named <envar>HG_URL</envar>, it will contain the
  1.1382 +	URL of a remote repository, if that can be determined.
  1.1383 +      </para>
  1.1384 +
  1.1385 +      <para>If a hook exits with a status of zero, it is considered to
  1.1386 +	have succeeded.  If it exits with a non-zero status, it is
  1.1387 +	considered to have failed.
  1.1388 +      </para>
  1.1389 +
  1.1390 +    </sect2>
  1.1391 +    <sect2>
  1.1392 +      <title>Finding out where changesets come from</title>
  1.1393 +
  1.1394 +      <para>A hook that involves the transfer of changesets between a
  1.1395 +	local repository and another may be able to find out
  1.1396 +	information about the <quote>far side</quote>.  Mercurial
  1.1397 +	knows <emphasis>how</emphasis> changes are being transferred,
  1.1398 +	and in many cases <emphasis>where</emphasis> they are being
  1.1399 +	transferred to or from.
  1.1400 +      </para>
  1.1401 +
  1.1402 +      <sect3 id="sec.hook.sources">
  1.1403 +	<title>Sources of changesets</title>
  1.1404 +
  1.1405 +	<para>Mercurial will tell a hook what means are, or were, used
  1.1406 +	  to transfer changesets between repositories.  This is
  1.1407 +	  provided by Mercurial in a Python parameter named
  1.1408 +	  <literal>source</literal>, or an environment variable named
  1.1409 +	  <envar>HG_SOURCE</envar>.
  1.1410 +	</para>
  1.1411 +
  1.1412 +	<itemizedlist>
  1.1413 +	  <listitem><para><literal>serve</literal>: Changesets are
  1.1414 +	      transferred to or from a remote repository over http or
  1.1415 +	      ssh.
  1.1416 +	    </para>
  1.1417 +	  </listitem>
  1.1418 +	  <listitem><para><literal>pull</literal>: Changesets are
  1.1419 +	      being transferred via a pull from one repository into
  1.1420 +	      another.
  1.1421 +	    </para>
  1.1422 +	  </listitem>
  1.1423 +	  <listitem><para><literal>push</literal>: Changesets are
  1.1424 +	      being transferred via a push from one repository into
  1.1425 +	      another.
  1.1426 +	    </para>
  1.1427 +	  </listitem>
  1.1428 +	  <listitem><para><literal>bundle</literal>: Changesets are
  1.1429 +	      being transferred to or from a bundle.
  1.1430 +	    </para>
  1.1431 +	  </listitem></itemizedlist>
  1.1432 +
  1.1433 +      </sect3>
  1.1434 +      <sect3 id="sec.hook.url">
  1.1435 +	<title>Where changes are going&emdash;remote repository
  1.1436 +	  URLs</title>
  1.1437 +
  1.1438 +	<para>When possible, Mercurial will tell a hook the location
  1.1439 +	  of the <quote>far side</quote> of an activity that transfers
  1.1440 +	  changeset data between repositories.  This is provided by
  1.1441 +	  Mercurial in a Python parameter named
  1.1442 +	  <literal>url</literal>, or an environment variable named
  1.1443 +	  <envar>HG_URL</envar>.
  1.1444 +	</para>
  1.1445 +
  1.1446 +	<para>This information is not always known.  If a hook is
  1.1447 +	  invoked in a repository that is being served via http or
  1.1448 +	  ssh, Mercurial cannot tell where the remote repository is,
  1.1449 +	  but it may know where the client is connecting from.  In
  1.1450 +	  such cases, the URL will take one of the following forms:
  1.1451 +	</para>
  1.1452 +	<itemizedlist>
  1.1453 +	  <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 
  1.1454 +	      ssh client, at the IP address
  1.1455 +	      <literal>1.2.3.4</literal>.
  1.1456 +	    </para>
  1.1457 +	  </listitem>
  1.1458 +	  <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote 
  1.1459 +	      http client, at the IP address
  1.1460 +	      <literal>1.2.3.4</literal>.  If the client is using SSL,
  1.1461 +	      this will be of the form
  1.1462 +	      <literal>remote:https:1.2.3.4</literal>.
  1.1463 +	    </para>
  1.1464 +	  </listitem>
  1.1465 +	  <listitem><para>Empty&emdash;no information could be
  1.1466 +	      discovered about the remote client.
  1.1467 +	    </para>
  1.1468 +	  </listitem></itemizedlist>
  1.1469 +
  1.1470 +      </sect3>
  1.1471 +    </sect2>
  1.1472 +  </sect1>
  1.1473 +  <sect1>
  1.1474 +    <title>Hook reference</title>
  1.1475 +
  1.1476 +    <sect2 id="sec.hook.changegroup">
  1.1477 +      <title><literal role="hook">changegroup</literal>&emdash;after
  1.1478 +	remote changesets added</title>
  1.1479 +
  1.1480 +      <para>This hook is run after a group of pre-existing changesets
  1.1481 +	has been added to the repository, for example via a <command
  1.1482 +	  role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg
  1.1483 +	  unbundle</command>.  This hook is run once per operation
  1.1484 +	that added one or more changesets.  This is in contrast to the
  1.1485 +	<literal role="hook">incoming</literal> hook, which is run
  1.1486 +	once per changeset, regardless of whether the changesets
  1.1487 +	arrive in a group.
  1.1488 +      </para>
  1.1489 +
  1.1490 +      <para>Some possible uses for this hook include kicking off an
  1.1491 +	automated build or test of the added changesets, updating a
  1.1492 +	bug database, or notifying subscribers that a repository
  1.1493 +	contains new changes.
  1.1494 +      </para>
  1.1495 +
  1.1496 +      <para>Parameters to this hook:
  1.1497 +      </para>
  1.1498 +      <itemizedlist>
  1.1499 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1500 +	    changeset ID of the first changeset in the group that was
  1.1501 +	    added.  All changesets between this and
  1.1502 +	    <literal role="tag">tip</literal>, inclusive, were added by a single
  1.1503 +	    <command role="hg-cmd">hg pull</command>, <command
  1.1504 +	      role="hg-cmd">hg push</command> or <command
  1.1505 +	      role="hg-cmd">hg unbundle</command>.
  1.1506 +	  </para>
  1.1507 +	</listitem>
  1.1508 +	<listitem><para><literal>source</literal>: A string.  The
  1.1509 +	    source of these changes.  See section <xref
  1.1510 +	      linkend="sec.hook.sources"/> for details.
  1.1511 +	  </para>
  1.1512 +	</listitem>
  1.1513 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1514 +	    of the remote repository, if known.  See section <xref
  1.1515 +	      linkend="sec.hook.url"/> for more
  1.1516 +	    information.
  1.1517 +	  </para>
  1.1518 +	</listitem></itemizedlist>
  1.1519 +
  1.1520 +      <para>See also: <literal role="hook">incoming</literal> (section
  1.1521 +	<xref linkend="sec.hook.incoming"/>), <literal
  1.1522 +	  role="hook">prechangegroup</literal> (section <xref
  1.1523 +	  linkend="sec.hook.prechangegroup"/>), <literal
  1.1524 +	  role="hook">pretxnchangegroup</literal> (section <xref
  1.1525 +	  linkend="sec.hook.pretxnchangegroup"/>)
  1.1526 +      </para>
  1.1527 +
  1.1528 +    </sect2>
  1.1529 +    <sect2 id="sec.hook.commit">
  1.1530 +      <title><literal role="hook">commit</literal>&emdash;after a new
  1.1531 +	changeset is created</title>
  1.1532 +
  1.1533 +      <para>This hook is run after a new changeset has been created.
  1.1534 +      </para>
  1.1535 +
  1.1536 +      <para>Parameters to this hook:
  1.1537 +      </para>
  1.1538 +      <itemizedlist>
  1.1539 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1540 +	    changeset ID of the newly committed changeset.
  1.1541 +	  </para>
  1.1542 +	</listitem>
  1.1543 +	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1544 +	    The changeset ID of the first parent of the newly
  1.1545 +	    committed changeset.
  1.1546 +	  </para>
  1.1547 +	</listitem>
  1.1548 +	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1549 +	    The changeset ID of the second parent of the newly
  1.1550 +	    committed changeset.
  1.1551 +	  </para>
  1.1552 +	</listitem></itemizedlist>
  1.1553 +
  1.1554 +      <para>See also: <literal role="hook">precommit</literal>
  1.1555 +	(section <xref linkend="sec.hook.precommit"/>), <literal
  1.1556 +	  role="hook">pretxncommit</literal> (section <xref
  1.1557 +	  linkend="sec.hook.pretxncommit"/>)
  1.1558 +      </para>
  1.1559 +
  1.1560 +    </sect2>
  1.1561 +    <sect2 id="sec.hook.incoming">
  1.1562 +      <title><literal role="hook">incoming</literal>&emdash;after one
  1.1563 +	remote changeset is added</title>
  1.1564 +
  1.1565 +      <para>This hook is run after a pre-existing changeset has been
  1.1566 +	added to the repository, for example via a <command
  1.1567 +	  role="hg-cmd">hg push</command>.  If a group of changesets
  1.1568 +	was added in a single operation, this hook is called once for
  1.1569 +	each added changeset.
  1.1570 +      </para>
  1.1571 +
  1.1572 +      <para>You can use this hook for the same purposes as the
  1.1573 +	<literal role="hook">changegroup</literal> hook (section <xref
  1.1574 +	  linkend="sec.hook.changegroup"/>); it's simply
  1.1575 +	more convenient sometimes to run a hook once per group of
  1.1576 +	changesets, while other times it's handier once per changeset.
  1.1577 +      </para>
  1.1578 +
  1.1579 +      <para>Parameters to this hook:
  1.1580 +      </para>
  1.1581 +      <itemizedlist>
  1.1582 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1583 +	    ID of the newly added changeset.
  1.1584 +	  </para>
  1.1585 +	</listitem>
  1.1586 +	<listitem><para><literal>source</literal>: A string.  The
  1.1587 +	    source of these changes.  See section <xref
  1.1588 +	      linkend="sec.hook.sources"/> for details.
  1.1589 +	  </para>
  1.1590 +	</listitem>
  1.1591 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1592 +	    of the remote repository, if known.  See section <xref
  1.1593 +	      linkend="sec.hook.url"/> for more
  1.1594 +	    information.
  1.1595 +	  </para>
  1.1596 +	</listitem></itemizedlist>
  1.1597 +
  1.1598 +      <para>See also: <literal role="hook">changegroup</literal>
  1.1599 +	(section <xref linkend="sec.hook.changegroup"/>) <literal
  1.1600 +	  role="hook">prechangegroup</literal> (section <xref
  1.1601 +	  linkend="sec.hook.prechangegroup"/>), <literal
  1.1602 +	  role="hook">pretxnchangegroup</literal> (section <xref
  1.1603 +	  linkend="sec.hook.pretxnchangegroup"/>)
  1.1604 +      </para>
  1.1605 +
  1.1606 +    </sect2>
  1.1607 +    <sect2 id="sec.hook.outgoing">
  1.1608 +      <title><literal role="hook">outgoing</literal>&emdash;after
  1.1609 +	changesets are propagated</title>
  1.1610 +
  1.1611 +      <para>This hook is run after a group of changesets has been
  1.1612 +	propagated out of this repository, for example by a <command
  1.1613 +	  role="hg-cmd">hg push</command> or <command role="hg-cmd">hg
  1.1614 +	  bundle</command> command.
  1.1615 +      </para>
  1.1616 +
  1.1617 +      <para>One possible use for this hook is to notify administrators
  1.1618 +	that changes have been pulled.
  1.1619 +      </para>
  1.1620 +
  1.1621 +      <para>Parameters to this hook:
  1.1622 +      </para>
  1.1623 +      <itemizedlist>
  1.1624 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1625 +	    changeset ID of the first changeset of the group that was
  1.1626 +	    sent.
  1.1627 +	  </para>
  1.1628 +	</listitem>
  1.1629 +	<listitem><para><literal>source</literal>: A string.  The
  1.1630 +	    source of the of the operation (see section <xref
  1.1631 +	      linkend="sec.hook.sources"/>).  If a remote
  1.1632 +	    client pulled changes from this repository,
  1.1633 +	    <literal>source</literal> will be
  1.1634 +	    <literal>serve</literal>.  If the client that obtained
  1.1635 +	    changes from this repository was local,
  1.1636 +	    <literal>source</literal> will be
  1.1637 +	    <literal>bundle</literal>, <literal>pull</literal>, or
  1.1638 +	    <literal>push</literal>, depending on the operation the
  1.1639 +	    client performed.
  1.1640 +	  </para>
  1.1641 +	</listitem>
  1.1642 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1643 +	    of the remote repository, if known.  See section <xref
  1.1644 +	      linkend="sec.hook.url"/> for more
  1.1645 +	    information.
  1.1646 +	  </para>
  1.1647 +	</listitem></itemizedlist>
  1.1648 +
  1.1649 +      <para>See also: <literal role="hook">preoutgoing</literal>
  1.1650 +	(section <xref linkend="sec.hook.preoutgoing"/>)
  1.1651 +      </para>
  1.1652 +
  1.1653 +    </sect2>
  1.1654 +    <sect2 id="sec.hook.prechangegroup">
  1.1655 +      <title><literal
  1.1656 +	  role="hook">prechangegroup</literal>&emdash;before starting
  1.1657 +	to add remote changesets</title>
  1.1658 +
  1.1659 +      <para>This controlling hook is run before Mercurial begins to
  1.1660 +	add a group of changesets from another repository.
  1.1661 +      </para>
  1.1662 +
  1.1663 +      <para>This hook does not have any information about the
  1.1664 +	changesets to be added, because it is run before transmission
  1.1665 +	of those changesets is allowed to begin.  If this hook fails,
  1.1666 +	the changesets will not be transmitted.
  1.1667 +      </para>
  1.1668 +
  1.1669 +      <para>One use for this hook is to prevent external changes from
  1.1670 +	being added to a repository.  For example, you could use this
  1.1671 +	to <quote>freeze</quote> a server-hosted branch temporarily or
  1.1672 +	permanently so that users cannot push to it, while still
  1.1673 +	allowing a local administrator to modify the repository.
  1.1674 +      </para>
  1.1675 +
  1.1676 +      <para>Parameters to this hook:
  1.1677 +      </para>
  1.1678 +      <itemizedlist>
  1.1679 +	<listitem><para><literal>source</literal>: A string.  The
  1.1680 +	    source of these changes.  See section <xref
  1.1681 +	      linkend="sec.hook.sources"/> for details.
  1.1682 +	  </para>
  1.1683 +	</listitem>
  1.1684 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1685 +	    of the remote repository, if known.  See section <xref
  1.1686 +	      linkend="sec.hook.url"/> for more
  1.1687 +	    information.
  1.1688 +	  </para>
  1.1689 +	</listitem></itemizedlist>
  1.1690 +
  1.1691 +      <para>See also: <literal role="hook">changegroup</literal>
  1.1692 +	(section <xref linkend="sec.hook.changegroup"/>), <literal
  1.1693 +	  role="hook">incoming</literal> (section <xref
  1.1694 +	  linkend="sec.hook.incoming"/>), , <literal
  1.1695 +	  role="hook">pretxnchangegroup</literal> (section <xref
  1.1696 +	  linkend="sec.hook.pretxnchangegroup"/>)
  1.1697 +      </para>
  1.1698 +
  1.1699 +    </sect2>
  1.1700 +    <sect2 id="sec.hook.precommit">
  1.1701 +      <title><literal role="hook">precommit</literal>&emdash;before
  1.1702 +	starting to commit a changeset</title>
  1.1703 +
  1.1704 +      <para>This hook is run before Mercurial begins to commit a new
  1.1705 +	changeset. It is run before Mercurial has any of the metadata
  1.1706 +	for the commit, such as the files to be committed, the commit
  1.1707 +	message, or the commit date.
  1.1708 +      </para>
  1.1709 +
  1.1710 +      <para>One use for this hook is to disable the ability to commit
  1.1711 +	new changesets, while still allowing incoming changesets.
  1.1712 +	Another is to run a build or test, and only allow the commit
  1.1713 +	to begin if the build or test succeeds.
  1.1714 +      </para>
  1.1715 +
  1.1716 +      <para>Parameters to this hook:
  1.1717 +      </para>
  1.1718 +      <itemizedlist>
  1.1719 +	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1720 +	    The changeset ID of the first parent of the working
  1.1721 +	    directory.
  1.1722 +	  </para>
  1.1723 +	</listitem>
  1.1724 +	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1725 +	    The changeset ID of the second parent of the working
  1.1726 +	    directory.
  1.1727 +	  </para>
  1.1728 +	</listitem></itemizedlist>
  1.1729 +      <para>If the commit proceeds, the parents of the working
  1.1730 +	directory will become the parents of the new changeset.
  1.1731 +      </para>
  1.1732 +
  1.1733 +      <para>See also: <literal role="hook">commit</literal> (section
  1.1734 +	<xref linkend="sec.hook.commit"/>), <literal
  1.1735 +	  role="hook">pretxncommit</literal> (section <xref
  1.1736 +	  linkend="sec.hook.pretxncommit"/>)
  1.1737 +      </para>
  1.1738 +
  1.1739 +    </sect2>
  1.1740 +    <sect2 id="sec.hook.preoutgoing">
  1.1741 +      <title><literal role="hook">preoutgoing</literal>&emdash;before
  1.1742 +	starting to propagate changesets</title>
  1.1743 +
  1.1744 +      <para>This hook is invoked before Mercurial knows the identities
  1.1745 +	of the changesets to be transmitted.
  1.1746 +      </para>
  1.1747 +
  1.1748 +      <para>One use for this hook is to prevent changes from being
  1.1749 +	transmitted to another repository.
  1.1750 +      </para>
  1.1751 +
  1.1752 +      <para>Parameters to this hook:
  1.1753 +      </para>
  1.1754 +      <itemizedlist>
  1.1755 +	<listitem><para><literal>source</literal>: A string.  The
  1.1756 +	    source of the operation that is attempting to obtain
  1.1757 +	    changes from this repository (see section <xref
  1.1758 +	      linkend="sec.hook.sources"/>).  See the documentation
  1.1759 +	    for the <literal>source</literal> parameter to the
  1.1760 +	    <literal role="hook">outgoing</literal> hook, in section
  1.1761 +	    <xref linkend="sec.hook.outgoing"/>, for possible values
  1.1762 +	    of
  1.1763 +	    this parameter.
  1.1764 +	  </para>
  1.1765 +	</listitem>
  1.1766 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1767 +	    of the remote repository, if known.  See section <xref
  1.1768 +	      linkend="sec.hook.url"/> for more
  1.1769 +	    information.
  1.1770 +	  </para>
  1.1771 +	</listitem></itemizedlist>
  1.1772 +
  1.1773 +      <para>See also: <literal role="hook">outgoing</literal> (section
  1.1774 +	<xref linkend="sec.hook.outgoing"/>)
  1.1775 +      </para>
  1.1776 +
  1.1777 +    </sect2>
  1.1778 +    <sect2 id="sec.hook.pretag">
  1.1779 +      <title><literal role="hook">pretag</literal>&emdash;before
  1.1780 +	tagging a changeset</title>
  1.1781 +
  1.1782 +      <para>This controlling hook is run before a tag is created.  If
  1.1783 +	the hook succeeds, creation of the tag proceeds.  If the hook
  1.1784 +	fails, the tag is not created.
  1.1785 +      </para>
  1.1786 +
  1.1787 +      <para>Parameters to this hook:
  1.1788 +      </para>
  1.1789 +      <itemizedlist>
  1.1790 +	<listitem><para><literal>local</literal>: A boolean.  Whether
  1.1791 +	    the tag is local to this repository instance (i.e. stored
  1.1792 +	    in <filename role="special">.hg/localtags</filename>) or
  1.1793 +	    managed by Mercurial (stored in <filename
  1.1794 +	      role="special">.hgtags</filename>).
  1.1795 +	  </para>
  1.1796 +	</listitem>
  1.1797 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1798 +	    ID of the changeset to be tagged.
  1.1799 +	  </para>
  1.1800 +	</listitem>
  1.1801 +	<listitem><para><literal>tag</literal>: A string.  The name of
  1.1802 +	    the tag to be created.
  1.1803 +	  </para>
  1.1804 +	</listitem></itemizedlist>
  1.1805 +
  1.1806 +      <para>If the tag to be created is revision-controlled, the
  1.1807 +	<literal role="hook">precommit</literal> and <literal
  1.1808 +	  role="hook">pretxncommit</literal> hooks (sections <xref
  1.1809 +	  linkend="sec.hook.commit"/> and <xref
  1.1810 +	  linkend="sec.hook.pretxncommit"/>) will also be run.
  1.1811 +      </para>
  1.1812 +
  1.1813 +      <para>See also: <literal role="hook">tag</literal> (section
  1.1814 +	<xref linkend="sec.hook.tag"/>)
  1.1815 +      </para>
  1.1816 +    </sect2>
  1.1817 +    <sect2 id="sec.hook.pretxnchangegroup">
  1.1818 +      <title><literal
  1.1819 +	  role="hook">pretxnchangegroup</literal>&emdash;before
  1.1820 +	completing addition of remote changesets</title>
  1.1821 +
  1.1822 +      <para>This controlling hook is run before a
  1.1823 +	transaction&emdash;that manages the addition of a group of new
  1.1824 +	changesets from outside the repository&emdash;completes.  If
  1.1825 +	the hook succeeds, the transaction completes, and all of the
  1.1826 +	changesets become permanent within this repository.  If the
  1.1827 +	hook fails, the transaction is rolled back, and the data for
  1.1828 +	the changesets is erased.
  1.1829 +      </para>
  1.1830 +
  1.1831 +      <para>This hook can access the metadata associated with the
  1.1832 +	almost-added changesets, but it should not do anything
  1.1833 +	permanent with this data. It must also not modify the working
  1.1834 +	directory.
  1.1835 +      </para>
  1.1836 +
  1.1837 +      <para>While this hook is running, if other Mercurial processes
  1.1838 +	access this repository, they will be able to see the
  1.1839 +	almost-added changesets as if they are permanent.  This may
  1.1840 +	lead to race conditions if you do not take steps to avoid
  1.1841 +	them.
  1.1842 +      </para>
  1.1843 +
  1.1844 +      <para>This hook can be used to automatically vet a group of
  1.1845 +	changesets.  If the hook fails, all of the changesets are
  1.1846 +	<quote>rejected</quote> when the transaction rolls back.
  1.1847 +      </para>
  1.1848 +
  1.1849 +      <para>Parameters to this hook:
  1.1850 +      </para>
  1.1851 +      <itemizedlist>
  1.1852 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1853 +	    changeset ID of the first changeset in the group that was
  1.1854 +	    added.  All changesets between this and
  1.1855 +	    <literal role="tag">tip</literal>,
  1.1856 +	    inclusive, were added by a single <command
  1.1857 +	      role="hg-cmd">hg pull</command>, <command
  1.1858 +	      role="hg-cmd">hg push</command> or <command
  1.1859 +	      role="hg-cmd">hg unbundle</command>.
  1.1860 +	  </para>
  1.1861 +	</listitem>
  1.1862 +	<listitem><para><literal>source</literal>: A string.  The
  1.1863 +	    source of these changes.  See section <xref
  1.1864 +	      linkend="sec.hook.sources"/> for details.
  1.1865 +	  </para>
  1.1866 +	</listitem>
  1.1867 +	<listitem><para><literal>url</literal>: A URL.  The location
  1.1868 +	    of the remote repository, if known.  See section <xref
  1.1869 +	      linkend="sec.hook.url"/> for more
  1.1870 +	    information.
  1.1871 +	  </para>
  1.1872 +	</listitem></itemizedlist>
  1.1873 +
  1.1874 +      <para>See also: <literal role="hook">changegroup</literal>
  1.1875 +	(section <xref linkend="sec.hook.changegroup"/>), <literal
  1.1876 +	  role="hook">incoming</literal> (section <xref
  1.1877 +	  linkend="sec.hook.incoming"/>), <literal
  1.1878 +	  role="hook">prechangegroup</literal> (section <xref
  1.1879 +	  linkend="sec.hook.prechangegroup"/>)
  1.1880 +      </para>
  1.1881 +
  1.1882 +    </sect2>
  1.1883 +    <sect2 id="sec.hook.pretxncommit">
  1.1884 +      <title><literal role="hook">pretxncommit</literal>&emdash;before
  1.1885 +	completing commit of new changeset</title>
  1.1886 +
  1.1887 +      <para>This controlling hook is run before a
  1.1888 +	transaction&emdash;that manages a new commit&emdash;completes.
  1.1889 +	If the hook succeeds, the transaction completes and the
  1.1890 +	changeset becomes permanent within this repository.  If the
  1.1891 +	hook fails, the transaction is rolled back, and the commit
  1.1892 +	data is erased.
  1.1893 +      </para>
  1.1894 +
  1.1895 +      <para>This hook can access the metadata associated with the
  1.1896 +	almost-new changeset, but it should not do anything permanent
  1.1897 +	with this data.  It must also not modify the working
  1.1898 +	directory.
  1.1899 +      </para>
  1.1900 +
  1.1901 +      <para>While this hook is running, if other Mercurial processes
  1.1902 +	access this repository, they will be able to see the
  1.1903 +	almost-new changeset as if it is permanent.  This may lead to
  1.1904 +	race conditions if you do not take steps to avoid them.
  1.1905 +      </para>
  1.1906 +
  1.1907 +      <para>Parameters to this hook:
  1.1908 +      </para>
  1.1909 +      <itemizedlist>
  1.1910 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1911 +	    changeset ID of the newly committed changeset.
  1.1912 +	  </para>
  1.1913 +	</listitem>
  1.1914 +	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1915 +	    The changeset ID of the first parent of the newly
  1.1916 +	    committed changeset.
  1.1917 +	  </para>
  1.1918 +	</listitem>
  1.1919 +	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1920 +	    The changeset ID of the second parent of the newly
  1.1921 +	    committed changeset.
  1.1922 +	  </para>
  1.1923 +	</listitem></itemizedlist>
  1.1924 +
  1.1925 +      <para>See also: <literal role="hook">precommit</literal>
  1.1926 +	(section <xref linkend="sec.hook.precommit"/>)
  1.1927 +      </para>
  1.1928 +
  1.1929 +    </sect2>
  1.1930 +    <sect2 id="sec.hook.preupdate">
  1.1931 +      <title><literal role="hook">preupdate</literal>&emdash;before
  1.1932 +	updating or merging working directory</title>
  1.1933 +
  1.1934 +      <para>This controlling hook is run before an update or merge of
  1.1935 +	the working directory begins.  It is run only if Mercurial's
  1.1936 +	normal pre-update checks determine that the update or merge
  1.1937 +	can proceed.  If the hook succeeds, the update or merge may
  1.1938 +	proceed; if it fails, the update or merge does not start.
  1.1939 +      </para>
  1.1940 +
  1.1941 +      <para>Parameters to this hook:
  1.1942 +      </para>
  1.1943 +      <itemizedlist>
  1.1944 +	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.1945 +	    The ID of the parent that the working directory is to be
  1.1946 +	    updated to.  If the working directory is being merged, it
  1.1947 +	    will not change this parent.
  1.1948 +	  </para>
  1.1949 +	</listitem>
  1.1950 +	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.1951 +	    Only set if the working directory is being merged.  The ID
  1.1952 +	    of the revision that the working directory is being merged
  1.1953 +	    with.
  1.1954 +	  </para>
  1.1955 +	</listitem></itemizedlist>
  1.1956 +
  1.1957 +      <para>See also: <literal role="hook">update</literal> (section
  1.1958 +	<xref linkend="sec.hook.update"/>)
  1.1959 +      </para>
  1.1960 +
  1.1961 +    </sect2>
  1.1962 +    <sect2 id="sec.hook.tag">
  1.1963 +      <title><literal role="hook">tag</literal>&emdash;after tagging a
  1.1964 +	changeset</title>
  1.1965 +
  1.1966 +      <para>This hook is run after a tag has been created.
  1.1967 +      </para>
  1.1968 +
  1.1969 +      <para>Parameters to this hook:
  1.1970 +      </para>
  1.1971 +      <itemizedlist>
  1.1972 +	<listitem><para><literal>local</literal>: A boolean.  Whether
  1.1973 +	    the new tag is local to this repository instance (i.e.
  1.1974 +	    stored in <filename
  1.1975 +	      role="special">.hg/localtags</filename>) or managed by
  1.1976 +	    Mercurial (stored in <filename
  1.1977 +	      role="special">.hgtags</filename>).
  1.1978 +	  </para>
  1.1979 +	</listitem>
  1.1980 +	<listitem><para><literal>node</literal>: A changeset ID.  The
  1.1981 +	    ID of the changeset that was tagged.
  1.1982 +	  </para>
  1.1983 +	</listitem>
  1.1984 +	<listitem><para><literal>tag</literal>: A string.  The name of
  1.1985 +	    the tag that was created.
  1.1986 +	  </para>
  1.1987 +	</listitem></itemizedlist>
  1.1988 +
  1.1989 +      <para>If the created tag is revision-controlled, the <literal
  1.1990 +	  role="hook">commit</literal> hook (section <xref
  1.1991 +	  linkend="sec.hook.commit"/>) is run before this hook.
  1.1992 +      </para>
  1.1993 +
  1.1994 +      <para>See also: <literal role="hook">pretag</literal> (section
  1.1995 +	<xref linkend="sec.hook.pretag"/>)
  1.1996 +      </para>
  1.1997 +
  1.1998 +    </sect2>
  1.1999 +    <sect2 id="sec.hook.update">
  1.2000 +      <title><literal role="hook">update</literal>&emdash;after
  1.2001 +	updating or merging working directory</title>
  1.2002 +
  1.2003 +      <para>This hook is run after an update or merge of the working
  1.2004 +	directory completes.  Since a merge can fail (if the external
  1.2005 +	<command>hgmerge</command> command fails to resolve conflicts
  1.2006 +	in a file), this hook communicates whether the update or merge
  1.2007 +	completed cleanly.
  1.2008 +      </para>
  1.2009 +
  1.2010 +      <itemizedlist>
  1.2011 +	<listitem><para><literal>error</literal>: A boolean.
  1.2012 +	    Indicates whether the update or merge completed
  1.2013 +	    successfully.
  1.2014 +	  </para>
  1.2015 +	</listitem>
  1.2016 +	<listitem><para><literal>parent1</literal>: A changeset ID.
  1.2017 +	    The ID of the parent that the working directory was
  1.2018 +	    updated to.  If the working directory was merged, it will
  1.2019 +	    not have changed this parent.
  1.2020 +	  </para>
  1.2021 +	</listitem>
  1.2022 +	<listitem><para><literal>parent2</literal>: A changeset ID.
  1.2023 +	    Only set if the working directory was merged.  The ID of
  1.2024 +	    the revision that the working directory was merged with.
  1.2025 +	  </para>
  1.2026 +	</listitem></itemizedlist>
  1.2027 +
  1.2028 +      <para>See also: <literal role="hook">preupdate</literal>
  1.2029 +	(section <xref linkend="sec.hook.preupdate"/>)
  1.2030 +      </para>
  1.2031 +
  1.2032 +    </sect2>
  1.2033 +  </sect1>
  1.2034 +</chapter>
  1.2035 +
  1.2036 +<!--
  1.2037 +local variables: 
  1.2038 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.2039 +end:
  1.2040 +-->