1.1 --- a/es/hook.tex	Sat Oct 18 07:48:21 2008 -0500
     1.2 +++ b/es/hook.tex	Mon Oct 20 04:01:59 2008 -0500
     1.3 @@ -0,0 +1,1413 @@
     1.4 +\chapter{Handling repository events with hooks}
     1.5 +\label{chap:hook}
     1.6 +
     1.7 +Mercurial offers a powerful mechanism to let you perform automated
     1.8 +actions in response to events that occur in a repository.  In some
     1.9 +cases, you can even control Mercurial's response to those events.
    1.10 +
    1.11 +The name Mercurial uses for one of these actions is a \emph{hook}.
    1.12 +Hooks are called ``triggers'' in some revision control systems, but
    1.13 +the two names refer to the same idea.
    1.14 +
    1.15 +\section{An overview of hooks in Mercurial}
    1.16 +
    1.17 +Here is a brief list of the hooks that Mercurial supports.  We will
    1.18 +revisit each of these hooks in more detail later, in
    1.19 +section~\ref{sec:hook:ref}.
    1.20 +
    1.21 +\begin{itemize}
    1.22 +\item[\small\hook{changegroup}] This is run after a group of
    1.23 +  changesets has been brought into the repository from elsewhere.
    1.24 +\item[\small\hook{commit}] This is run after a new changeset has been
    1.25 +  created in the local repository.
    1.26 +\item[\small\hook{incoming}] This is run once for each new changeset
    1.27 +  that is brought into the repository from elsewhere.  Notice the
    1.28 +  difference from \hook{changegroup}, which is run once per
    1.29 +  \emph{group} of changesets brought in.
    1.30 +\item[\small\hook{outgoing}] This is run after a group of changesets
    1.31 +  has been transmitted from this repository.
    1.32 +\item[\small\hook{prechangegroup}] This is run before starting to
    1.33 +  bring a group of changesets into the repository.
    1.34 +\item[\small\hook{precommit}] Controlling. This is run before starting
    1.35 +  a commit.
    1.36 +\item[\small\hook{preoutgoing}] Controlling. This is run before
    1.37 +  starting to transmit a group of changesets from this repository.
    1.38 +\item[\small\hook{pretag}] Controlling. This is run before creating a tag.
    1.39 +\item[\small\hook{pretxnchangegroup}] Controlling. This is run after a
    1.40 +  group of changesets has been brought into the local repository from
    1.41 +  another, but before the transaction completes that will make the
    1.42 +  changes permanent in the repository.
    1.43 +\item[\small\hook{pretxncommit}] Controlling. This is run after a new
    1.44 +  changeset has been created in the local repository, but before the
    1.45 +  transaction completes that will make it permanent.
    1.46 +\item[\small\hook{preupdate}] Controlling. This is run before starting
    1.47 +  an update or merge of the working directory.
    1.48 +\item[\small\hook{tag}] This is run after a tag is created.
    1.49 +\item[\small\hook{update}] This is run after an update or merge of the
    1.50 +  working directory has finished.
    1.51 +\end{itemize}
    1.52 +Each of the hooks whose description begins with the word
    1.53 +``Controlling'' has the ability to determine whether an activity can
    1.54 +proceed.  If the hook succeeds, the activity may proceed; if it fails,
    1.55 +the activity is either not permitted or undone, depending on the hook.
    1.56 +
    1.57 +\section{Hooks and security}
    1.58 +
    1.59 +\subsection{Hooks are run with your privileges}
    1.60 +
    1.61 +When you run a Mercurial command in a repository, and the command
    1.62 +causes a hook to run, that hook runs on \emph{your} system, under
    1.63 +\emph{your} user account, with \emph{your} privilege level.  Since
    1.64 +hooks are arbitrary pieces of executable code, you should treat them
    1.65 +with an appropriate level of suspicion.  Do not install a hook unless
    1.66 +you are confident that you know who created it and what it does.
    1.67 +
    1.68 +In some cases, you may be exposed to hooks that you did not install
    1.69 +yourself.  If you work with Mercurial on an unfamiliar system,
    1.70 +Mercurial will run hooks defined in that system's global \hgrc\ file.
    1.71 +
    1.72 +If you are working with a repository owned by another user, Mercurial
    1.73 +can run hooks defined in that user's repository, but it will still run
    1.74 +them as ``you''.  For example, if you \hgcmd{pull} from that
    1.75 +repository, and its \sfilename{.hg/hgrc} defines a local
    1.76 +\hook{outgoing} hook, that hook will run under your user account, even
    1.77 +though you don't own that repository.
    1.78 +
    1.79 +\begin{note}
    1.80 +  This only applies if you are pulling from a repository on a local or
    1.81 +  network filesystem.  If you're pulling over http or ssh, any
    1.82 +  \hook{outgoing} hook will run under whatever account is executing
    1.83 +  the server process, on the server.
    1.84 +\end{note}
    1.85 +
    1.86 +XXX To see what hooks are defined in a repository, use the
    1.87 +\hgcmdargs{config}{hooks} command.  If you are working in one
    1.88 +repository, but talking to another that you do not own (e.g.~using
    1.89 +\hgcmd{pull} or \hgcmd{incoming}), remember that it is the other
    1.90 +repository's hooks you should be checking, not your own.
    1.91 +
    1.92 +\subsection{Hooks do not propagate}
    1.93 +
    1.94 +In Mercurial, hooks are not revision controlled, and do not propagate
    1.95 +when you clone, or pull from, a repository.  The reason for this is
    1.96 +simple: a hook is a completely arbitrary piece of executable code.  It
    1.97 +runs under your user identity, with your privilege level, on your
    1.98 +machine.
    1.99 +
   1.100 +It would be extremely reckless for any distributed revision control
   1.101 +system to implement revision-controlled hooks, as this would offer an
   1.102 +easily exploitable way to subvert the accounts of users of the
   1.103 +revision control system.
   1.104 +
   1.105 +Since Mercurial does not propagate hooks, if you are collaborating
   1.106 +with other people on a common project, you should not assume that they
   1.107 +are using the same Mercurial hooks as you are, or that theirs are
   1.108 +correctly configured.  You should document the hooks you expect people
   1.109 +to use.
   1.110 +
   1.111 +In a corporate intranet, this is somewhat easier to control, as you
   1.112 +can for example provide a ``standard'' installation of Mercurial on an
   1.113 +NFS filesystem, and use a site-wide \hgrc\ file to define hooks that
   1.114 +all users will see.  However, this too has its limits; see below.
   1.115 +
   1.116 +\subsection{Hooks can be overridden}
   1.117 +
   1.118 +Mercurial allows you to override a hook definition by redefining the
   1.119 +hook.  You can disable it by setting its value to the empty string, or
   1.120 +change its behaviour as you wish.
   1.121 +
   1.122 +If you deploy a system-~or site-wide \hgrc\ file that defines some
   1.123 +hooks, you should thus understand that your users can disable or
   1.124 +override those hooks.
   1.125 +
   1.126 +\subsection{Ensuring that critical hooks are run}
   1.127 +
   1.128 +Sometimes you may want to enforce a policy that you do not want others
   1.129 +to be able to work around.  For example, you may have a requirement
   1.130 +that every changeset must pass a rigorous set of tests.  Defining this
   1.131 +requirement via a hook in a site-wide \hgrc\ won't work for remote
   1.132 +users on laptops, and of course local users can subvert it at will by
   1.133 +overriding the hook.
   1.134 +
   1.135 +Instead, you can set up your policies for use of Mercurial so that
   1.136 +people are expected to propagate changes through a well-known
   1.137 +``canonical'' server that you have locked down and configured
   1.138 +appropriately.
   1.139 +
   1.140 +One way to do this is via a combination of social engineering and
   1.141 +technology.  Set up a restricted-access account; users can push
   1.142 +changes over the network to repositories managed by this account, but
   1.143 +they cannot log into the account and run normal shell commands.  In
   1.144 +this scenario, a user can commit a changeset that contains any old
   1.145 +garbage they want.
   1.146 +
   1.147 +When someone pushes a changeset to the server that everyone pulls
   1.148 +from, the server will test the changeset before it accepts it as
   1.149 +permanent, and reject it if it fails to pass the test suite.  If
   1.150 +people only pull changes from this filtering server, it will serve to
   1.151 +ensure that all changes that people pull have been automatically
   1.152 +vetted.
   1.153 +
   1.154 +\section{Care with \texttt{pretxn} hooks in a shared-access repository}
   1.155 +
   1.156 +If you want to use hooks to do some automated work in a repository
   1.157 +that a number of people have shared access to, you need to be careful
   1.158 +in how you do this.
   1.159 +
   1.160 +Mercurial only locks a repository when it is writing to the
   1.161 +repository, and only the parts of Mercurial that write to the
   1.162 +repository pay attention to locks.  Write locks are necessary to
   1.163 +prevent multiple simultaneous writers from scribbling on each other's
   1.164 +work, corrupting the repository.
   1.165 +
   1.166 +Because Mercurial is careful with the order in which it reads and
   1.167 +writes data, it does not need to acquire a lock when it wants to read
   1.168 +data from the repository.  The parts of Mercurial that read from the
   1.169 +repository never pay attention to locks.  This lockless reading scheme
   1.170 +greatly increases performance and concurrency.
   1.171 +
   1.172 +With great performance comes a trade-off, though, one which has the
   1.173 +potential to cause you trouble unless you're aware of it.  To describe
   1.174 +this requires a little detail about how Mercurial adds changesets to a
   1.175 +repository and reads those changes.
   1.176 +
   1.177 +When Mercurial \emph{writes} metadata, it writes it straight into the
   1.178 +destination file.  It writes file data first, then manifest data
   1.179 +(which contains pointers to the new file data), then changelog data
   1.180 +(which contains pointers to the new manifest data).  Before the first
   1.181 +write to each file, it stores a record of where the end of the file
   1.182 +was in its transaction log.  If the transaction must be rolled back,
   1.183 +Mercurial simply truncates each file back to the size it was before the
   1.184 +transaction began.
   1.185 +
   1.186 +When Mercurial \emph{reads} metadata, it reads the changelog first,
   1.187 +then everything else.  Since a reader will only access parts of the
   1.188 +manifest or file metadata that it can see in the changelog, it can
   1.189 +never see partially written data.
   1.190 +
   1.191 +Some controlling hooks (\hook{pretxncommit} and
   1.192 +\hook{pretxnchangegroup}) run when a transaction is almost complete.
   1.193 +All of the metadata has been written, but Mercurial can still roll the
   1.194 +transaction back and cause the newly-written data to disappear.
   1.195 +
   1.196 +If one of these hooks runs for long, it opens a window of time during
   1.197 +which a reader can see the metadata for changesets that are not yet
   1.198 +permanent, and should not be thought of as ``really there''.  The
   1.199 +longer the hook runs, the longer that window is open.
   1.200 +
   1.201 +\subsection{The problem illustrated}
   1.202 +
   1.203 +In principle, a good use for the \hook{pretxnchangegroup} hook would
   1.204 +be to automatically build and test incoming changes before they are
   1.205 +accepted into a central repository.  This could let you guarantee that
   1.206 +nobody can push changes to this repository that ``break the build''.
   1.207 +But if a client can pull changes while they're being tested, the
   1.208 +usefulness of the test is zero; an unsuspecting someone can pull
   1.209 +untested changes, potentially breaking their build.
   1.210 +
   1.211 +The safest technological answer to this challenge is to set up such a
   1.212 +``gatekeeper'' repository as \emph{unidirectional}.  Let it take
   1.213 +changes pushed in from the outside, but do not allow anyone to pull
   1.214 +changes from it (use the \hook{preoutgoing} hook to lock it down).
   1.215 +Configure a \hook{changegroup} hook so that if a build or test
   1.216 +succeeds, the hook will push the new changes out to another repository
   1.217 +that people \emph{can} pull from.
   1.218 +
   1.219 +In practice, putting a centralised bottleneck like this in place is
   1.220 +not often a good idea, and transaction visibility has nothing to do
   1.221 +with the problem.  As the size of a project---and the time it takes to
   1.222 +build and test---grows, you rapidly run into a wall with this ``try
   1.223 +before you buy'' approach, where you have more changesets to test than
   1.224 +time in which to deal with them.  The inevitable result is frustration
   1.225 +on the part of all involved.
   1.226 +
   1.227 +An approach that scales better is to get people to build and test
   1.228 +before they push, then run automated builds and tests centrally
   1.229 +\emph{after} a push, to be sure all is well.  The advantage of this
   1.230 +approach is that it does not impose a limit on the rate at which the
   1.231 +repository can accept changes.
   1.232 +
   1.233 +\section{A short tutorial on using hooks}
   1.234 +\label{sec:hook:simple}
   1.235 +
   1.236 +It is easy to write a Mercurial hook.  Let's start with a hook that
   1.237 +runs when you finish a \hgcmd{commit}, and simply prints the hash of
   1.238 +the changeset you just created.  The hook is called \hook{commit}.
   1.239 +
   1.240 +\begin{figure}[ht]
   1.241 +  \interaction{hook.simple.init}
   1.242 +  \caption{A simple hook that runs when a changeset is committed}
   1.243 +  \label{ex:hook:init}
   1.244 +\end{figure}
   1.245 +
   1.246 +All hooks follow the pattern in example~\ref{ex:hook:init}.  You add
   1.247 +an entry to the \rcsection{hooks} section of your \hgrc.  On the left
   1.248 +is the name of the event to trigger on; on the right is the action to
   1.249 +take.  As you can see, you can run an arbitrary shell command in a
   1.250 +hook.  Mercurial passes extra information to the hook using
   1.251 +environment variables (look for \envar{HG\_NODE} in the example).
   1.252 +
   1.253 +\subsection{Performing multiple actions per event}
   1.254 +
   1.255 +Quite often, you will want to define more than one hook for a
   1.256 +particular kind of event, as shown in example~\ref{ex:hook:ext}.
   1.257 +Mercurial lets you do this by adding an \emph{extension} to the end of
   1.258 +a hook's name.  You extend a hook's name by giving the name of the
   1.259 +hook, followed by a full stop (the ``\texttt{.}'' character), followed
   1.260 +by some more text of your choosing.  For example, Mercurial will run
   1.261 +both \texttt{commit.foo} and \texttt{commit.bar} when the
   1.262 +\texttt{commit} event occurs.
   1.263 +
   1.264 +\begin{figure}[ht]
   1.265 +  \interaction{hook.simple.ext}
   1.266 +  \caption{Defining a second \hook{commit} hook}
   1.267 +  \label{ex:hook:ext}
   1.268 +\end{figure}
   1.269 +
   1.270 +To give a well-defined order of execution when there are multiple
   1.271 +hooks defined for an event, Mercurial sorts hooks by extension, and
   1.272 +executes the hook commands in this sorted order.  In the above
   1.273 +example, it will execute \texttt{commit.bar} before
   1.274 +\texttt{commit.foo}, and \texttt{commit} before both.
   1.275 +
   1.276 +It is a good idea to use a somewhat descriptive extension when you
   1.277 +define a new hook.  This will help you to remember what the hook was
   1.278 +for.  If the hook fails, you'll get an error message that contains the
   1.279 +hook name and extension, so using a descriptive extension could give
   1.280 +you an immediate hint as to why the hook failed (see
   1.281 +section~\ref{sec:hook:perm} for an example).
   1.282 +
   1.283 +\subsection{Controlling whether an activity can proceed}
   1.284 +\label{sec:hook:perm}
   1.285 +
   1.286 +In our earlier examples, we used the \hook{commit} hook, which is
   1.287 +run after a commit has completed.  This is one of several Mercurial
   1.288 +hooks that run after an activity finishes.  Such hooks have no way of
   1.289 +influencing the activity itself.
   1.290 +
   1.291 +Mercurial defines a number of events that occur before an activity
   1.292 +starts; or after it starts, but before it finishes.  Hooks that
   1.293 +trigger on these events have the added ability to choose whether the
   1.294 +activity can continue, or will abort.  
   1.295 +
   1.296 +The \hook{pretxncommit} hook runs after a commit has all but
   1.297 +completed.  In other words, the metadata representing the changeset
   1.298 +has been written out to disk, but the transaction has not yet been
   1.299 +allowed to complete.  The \hook{pretxncommit} hook has the ability to
   1.300 +decide whether the transaction can complete, or must be rolled back.
   1.301 +
   1.302 +If the \hook{pretxncommit} hook exits with a status code of zero, the
   1.303 +transaction is allowed to complete; the commit finishes; and the
   1.304 +\hook{commit} hook is run.  If the \hook{pretxncommit} hook exits with
   1.305 +a non-zero status code, the transaction is rolled back; the metadata
   1.306 +representing the changeset is erased; and the \hook{commit} hook is
   1.307 +not run.
   1.308 +
   1.309 +\begin{figure}[ht]
   1.310 +  \interaction{hook.simple.pretxncommit}
   1.311 +  \caption{Using the \hook{pretxncommit} hook to control commits}
   1.312 +  \label{ex:hook:pretxncommit}
   1.313 +\end{figure}
   1.314 +
   1.315 +The hook in example~\ref{ex:hook:pretxncommit} checks that a commit
   1.316 +comment contains a bug ID.  If it does, the commit can complete.  If
   1.317 +not, the commit is rolled back.
   1.318 +
   1.319 +\section{Writing your own hooks}
   1.320 +
   1.321 +When you are writing a hook, you might find it useful to run Mercurial
   1.322 +either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
   1.323 +item set to ``true''.  When you do so, Mercurial will print a message
   1.324 +before it calls each hook.
   1.325 +
   1.326 +\subsection{Choosing how your hook should run}
   1.327 +\label{sec:hook:lang}
   1.328 +
   1.329 +You can write a hook either as a normal program---typically a shell
   1.330 +script---or as a Python function that is executed within the Mercurial
   1.331 +process.
   1.332 +
   1.333 +Writing a hook as an external program has the advantage that it
   1.334 +requires no knowledge of Mercurial's internals.  You can call normal
   1.335 +Mercurial commands to get any added information you need.  The
   1.336 +trade-off is that external hooks are slower than in-process hooks.
   1.337 +
   1.338 +An in-process Python hook has complete access to the Mercurial API,
   1.339 +and does not ``shell out'' to another process, so it is inherently
   1.340 +faster than an external hook.  It is also easier to obtain much of the
   1.341 +information that a hook requires by using the Mercurial API than by
   1.342 +running Mercurial commands.
   1.343 +
   1.344 +If you are comfortable with Python, or require high performance,
   1.345 +writing your hooks in Python may be a good choice.  However, when you
   1.346 +have a straightforward hook to write and you don't need to care about
   1.347 +performance (probably the majority of hooks), a shell script is
   1.348 +perfectly fine.
   1.349 +
   1.350 +\subsection{Hook parameters}
   1.351 +\label{sec:hook:param}
   1.352 +
   1.353 +Mercurial calls each hook with a set of well-defined parameters.  In
   1.354 +Python, a parameter is passed as a keyword argument to your hook
   1.355 +function.  For an external program, a parameter is passed as an
   1.356 +environment variable.
   1.357 +
   1.358 +Whether your hook is written in Python or as a shell script, the
   1.359 +hook-specific parameter names and values will be the same.  A boolean
   1.360 +parameter will be represented as a boolean value in Python, but as the
   1.361 +number 1 (for ``true'') or 0 (for ``false'') as an environment
   1.362 +variable for an external hook.  If a hook parameter is named
   1.363 +\texttt{foo}, the keyword argument for a Python hook will also be
   1.364 +named \texttt{foo}, while the environment variable for an external
   1.365 +hook will be named \texttt{HG\_FOO}.
   1.366 +
   1.367 +\subsection{Hook return values and activity control}
   1.368 +
   1.369 +A hook that executes successfully must exit with a status of zero if
   1.370 +external, or return boolean ``false'' if in-process.  Failure is
   1.371 +indicated with a non-zero exit status from an external hook, or an
   1.372 +in-process hook returning boolean ``true''.  If an in-process hook
   1.373 +raises an exception, the hook is considered to have failed.
   1.374 +
   1.375 +For a hook that controls whether an activity can proceed, zero/false
   1.376 +means ``allow'', while non-zero/true/exception means ``deny''.
   1.377 +
   1.378 +\subsection{Writing an external hook}
   1.379 +
   1.380 +When you define an external hook in your \hgrc\ and the hook is run,
   1.381 +its value is passed to your shell, which interprets it.  This means
   1.382 +that you can use normal shell constructs in the body of the hook.
   1.383 +
   1.384 +An executable hook is always run with its current directory set to a
   1.385 +repository's root directory.
   1.386 +
   1.387 +Each hook parameter is passed in as an environment variable; the name
   1.388 +is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
   1.389 +
   1.390 +With the exception of hook parameters, Mercurial does not set or
   1.391 +modify any environment variables when running a hook.  This is useful
   1.392 +to remember if you are writing a site-wide hook that may be run by a
   1.393 +number of different users with differing environment variables set.
   1.394 +In multi-user situations, you should not rely on environment variables
   1.395 +being set to the values you have in your environment when testing the
   1.396 +hook.
   1.397 +
   1.398 +\subsection{Telling Mercurial to use an in-process hook}
   1.399 +
   1.400 +The \hgrc\ syntax for defining an in-process hook is slightly
   1.401 +different than for an executable hook.  The value of the hook must
   1.402 +start with the text ``\texttt{python:}'', and continue with the
   1.403 +fully-qualified name of a callable object to use as the hook's value.
   1.404 +
   1.405 +The module in which a hook lives is automatically imported when a hook
   1.406 +is run.  So long as you have the module name and \envar{PYTHONPATH}
   1.407 +right, it should ``just work''.
   1.408 +
   1.409 +The following \hgrc\ example snippet illustrates the syntax and
   1.410 +meaning of the notions we just described.
   1.411 +\begin{codesample2}
   1.412 +  [hooks]
   1.413 +  commit.example = python:mymodule.submodule.myhook
   1.414 +\end{codesample2}
   1.415 +When Mercurial runs the \texttt{commit.example} hook, it imports
   1.416 +\texttt{mymodule.submodule}, looks for the callable object named
   1.417 +\texttt{myhook}, and calls it.
   1.418 +
   1.419 +\subsection{Writing an in-process hook}
   1.420 +
   1.421 +The simplest in-process hook does nothing, but illustrates the basic
   1.422 +shape of the hook API:
   1.423 +\begin{codesample2}
   1.424 +  def myhook(ui, repo, **kwargs):
   1.425 +      pass
   1.426 +\end{codesample2}
   1.427 +The first argument to a Python hook is always a
   1.428 +\pymodclass{mercurial.ui}{ui} object.  The second is a repository object;
   1.429 +at the moment, it is always an instance of
   1.430 +\pymodclass{mercurial.localrepo}{localrepository}.  Following these two
   1.431 +arguments are other keyword arguments.  Which ones are passed in
   1.432 +depends on the hook being called, but a hook can ignore arguments it
   1.433 +doesn't care about by dropping them into a keyword argument dict, as
   1.434 +with \texttt{**kwargs} above.
   1.435 +
   1.436 +\section{Some hook examples}
   1.437 +
   1.438 +\subsection{Writing meaningful commit messages}
   1.439 +
   1.440 +It's hard to imagine a useful commit message being very short.  The
   1.441 +simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go}
   1.442 +will prevent you from committing a changeset with a message that is
   1.443 +less than ten bytes long.
   1.444 +
   1.445 +\begin{figure}[ht]
   1.446 +  \interaction{hook.msglen.go}
   1.447 +  \caption{A hook that forbids overly short commit messages}
   1.448 +  \label{ex:hook:msglen.go}
   1.449 +\end{figure}
   1.450 +
   1.451 +\subsection{Checking for trailing whitespace}
   1.452 +
   1.453 +An interesting use of a commit-related hook is to help you to write
   1.454 +cleaner code.  A simple example of ``cleaner code'' is the dictum that
   1.455 +a change should not add any new lines of text that contain ``trailing
   1.456 +whitespace''.  Trailing whitespace is a series of space and tab
   1.457 +characters at the end of a line of text.  In most cases, trailing
   1.458 +whitespace is unnecessary, invisible noise, but it is occasionally
   1.459 +problematic, and people often prefer to get rid of it.
   1.460 +
   1.461 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to
   1.462 +tell whether you have a trailing whitespace problem.  If you use the
   1.463 +\hook{precommit} hook, the hook will not know which files you are
   1.464 +committing, so it will have to check every modified file in the
   1.465 +repository for trailing white space.  If you want to commit a change
   1.466 +to just the file \filename{foo}, but the file \filename{bar} contains
   1.467 +trailing whitespace, doing a check in the \hook{precommit} hook will
   1.468 +prevent you from committing \filename{foo} due to the problem with
   1.469 +\filename{bar}.  This doesn't seem right.
   1.470 +
   1.471 +Should you choose the \hook{pretxncommit} hook, the check won't occur
   1.472 +until just before the transaction for the commit completes.  This will
   1.473 +allow you to check for problems only the exact files that are being
   1.474 +committed.  However, if you entered the commit message interactively
   1.475 +and the hook fails, the transaction will roll back; you'll have to
   1.476 +re-enter the commit message after you fix the trailing whitespace and
   1.477 +run \hgcmd{commit} again.
   1.478 +
   1.479 +\begin{figure}[ht]
   1.480 +  \interaction{hook.ws.simple}
   1.481 +  \caption{A simple hook that checks for trailing whitespace}
   1.482 +  \label{ex:hook:ws.simple}
   1.483 +\end{figure}
   1.484 +
   1.485 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
   1.486 +hook that checks for trailing whitespace.  This hook is short, but not
   1.487 +very helpful.  It exits with an error status if a change adds a line
   1.488 +with trailing whitespace to any file, but does not print any
   1.489 +information that might help us to identify the offending file or
   1.490 +line.  It also has the nice property of not paying attention to
   1.491 +unmodified lines; only lines that introduce new trailing whitespace
   1.492 +cause problems.
   1.493 +
   1.494 +\begin{figure}[ht]
   1.495 +  \interaction{hook.ws.better}
   1.496 +  \caption{A better trailing whitespace hook}
   1.497 +  \label{ex:hook:ws.better}
   1.498 +\end{figure}
   1.499 +
   1.500 +The example of figure~\ref{ex:hook:ws.better} is much more complex,
   1.501 +but also more useful.  It parses a unified diff to see if any lines
   1.502 +add trailing whitespace, and prints the name of the file and the line
   1.503 +number of each such occurrence.  Even better, if the change adds
   1.504 +trailing whitespace, this hook saves the commit comment and prints the
   1.505 +name of the save file before exiting and telling Mercurial to roll the
   1.506 +transaction back, so you can use
   1.507 +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
   1.508 +saved commit message once you've corrected the problem.
   1.509 +
   1.510 +As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
   1.511 +\command{perl}'s in-place editing feature to get rid of trailing
   1.512 +whitespace from a file.  This is concise and useful enough that I will
   1.513 +reproduce it here.
   1.514 +\begin{codesample2}
   1.515 +  perl -pi -e 's,\\s+\$,,' filename
   1.516 +\end{codesample2}
   1.517 +
   1.518 +\section{Bundled hooks}
   1.519 +
   1.520 +Mercurial ships with several bundled hooks.  You can find them in the
   1.521 +\dirname{hgext} directory of a Mercurial source tree.  If you are
   1.522 +using a Mercurial binary package, the hooks will be located in the
   1.523 +\dirname{hgext} directory of wherever your package installer put
   1.524 +Mercurial.
   1.525 +
   1.526 +\subsection{\hgext{acl}---access control for parts of a repository}
   1.527 +
   1.528 +The \hgext{acl} extension lets you control which remote users are
   1.529 +allowed to push changesets to a networked server.  You can protect any
   1.530 +portion of a repository (including the entire repo), so that a
   1.531 +specific remote user can push changes that do not affect the protected
   1.532 +portion.
   1.533 +
   1.534 +This extension implements access control based on the identity of the
   1.535 +user performing a push, \emph{not} on who committed the changesets
   1.536 +they're pushing.  It makes sense to use this hook only if you have a
   1.537 +locked-down server environment that authenticates remote users, and
   1.538 +you want to be sure that only specific users are allowed to push
   1.539 +changes to that server.
   1.540 +
   1.541 +\subsubsection{Configuring the \hook{acl} hook}
   1.542 +
   1.543 +In order to manage incoming changesets, the \hgext{acl} hook must be
   1.544 +used as a \hook{pretxnchangegroup} hook.  This lets it see which files
   1.545 +are modified by each incoming changeset, and roll back a group of
   1.546 +changesets if they modify ``forbidden'' files.  Example:
   1.547 +\begin{codesample2}
   1.548 +  [hooks]
   1.549 +  pretxnchangegroup.acl = python:hgext.acl.hook
   1.550 +\end{codesample2}
   1.551 +
   1.552 +The \hgext{acl} extension is configured using three sections.  
   1.553 +
   1.554 +The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
   1.555 +which lists the sources of incoming changesets that the hook should
   1.556 +pay attention to.  You don't normally need to configure this section.
   1.557 +\begin{itemize}
   1.558 +\item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
   1.559 +  from a remote repository over http or ssh.  This is the default
   1.560 +  value of \rcitem{acl}{sources}, and usually the only setting you'll
   1.561 +  need for this configuration item.
   1.562 +\item[\rcitem{acl}{pull}] Control incoming changesets that are
   1.563 +  arriving via a pull from a local repository.
   1.564 +\item[\rcitem{acl}{push}] Control incoming changesets that are
   1.565 +  arriving via a push from a local repository.
   1.566 +\item[\rcitem{acl}{bundle}] Control incoming changesets that are
   1.567 +  arriving from another repository via a bundle.
   1.568 +\end{itemize}
   1.569 +
   1.570 +The \rcsection{acl.allow} section controls the users that are allowed to
   1.571 +add changesets to the repository.  If this section is not present, all
   1.572 +users that are not explicitly denied are allowed.  If this section is
   1.573 +present, all users that are not explicitly allowed are denied (so an
   1.574 +empty section means that all users are denied).
   1.575 +
   1.576 +The \rcsection{acl.deny} section determines which users are denied
   1.577 +from adding changesets to the repository.  If this section is not
   1.578 +present or is empty, no users are denied.
   1.579 +
   1.580 +The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
   1.581 +sections are identical.  On the left of each entry is a glob pattern
   1.582 +that matches files or directories, relative to the root of the
   1.583 +repository; on the right, a user name.
   1.584 +
   1.585 +In the following example, the user \texttt{docwriter} can only push
   1.586 +changes to the \dirname{docs} subtree of the repository, while
   1.587 +\texttt{intern} can push changes to any file or directory except
   1.588 +\dirname{source/sensitive}.
   1.589 +\begin{codesample2}
   1.590 +  [acl.allow]
   1.591 +  docs/** = docwriter
   1.592 +
   1.593 +  [acl.deny]
   1.594 +  source/sensitive/** = intern
   1.595 +\end{codesample2}
   1.596 +
   1.597 +\subsubsection{Testing and troubleshooting}
   1.598 +
   1.599 +If you want to test the \hgext{acl} hook, run it with Mercurial's
   1.600 +debugging output enabled.  Since you'll probably be running it on a
   1.601 +server where it's not convenient (or sometimes possible) to pass in
   1.602 +the \hggopt{--debug} option, don't forget that you can enable
   1.603 +debugging output in your \hgrc:
   1.604 +\begin{codesample2}
   1.605 +  [ui]
   1.606 +  debug = true
   1.607 +\end{codesample2}
   1.608 +With this enabled, the \hgext{acl} hook will print enough information
   1.609 +to let you figure out why it is allowing or forbidding pushes from
   1.610 +specific users.
   1.611 +
   1.612 +\subsection{\hgext{bugzilla}---integration with Bugzilla}
   1.613 +
   1.614 +The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
   1.615 +whenever it finds a reference to that bug ID in a commit comment.  You
   1.616 +can install this hook on a shared server, so that any time a remote
   1.617 +user pushes changes to this server, the hook gets run.  
   1.618 +
   1.619 +It adds a comment to the bug that looks like this (you can configure
   1.620 +the contents of the comment---see below):
   1.621 +\begin{codesample2}
   1.622 +  Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
   1.623 +  the frobnitz repository, refers to this bug.
   1.624 +
   1.625 +  For complete details, see
   1.626 +  http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
   1.627 +
   1.628 +  Changeset description:
   1.629 +        Fix bug 10483 by guarding against some NULL pointers
   1.630 +\end{codesample2}
   1.631 +The value of this hook is that it automates the process of updating a
   1.632 +bug any time a changeset refers to it.  If you configure the hook
   1.633 +properly, it makes it easy for people to browse straight from a
   1.634 +Bugzilla bug to a changeset that refers to that bug.
   1.635 +
   1.636 +You can use the code in this hook as a starting point for some more
   1.637 +exotic Bugzilla integration recipes.  Here are a few possibilities:
   1.638 +\begin{itemize}
   1.639 +\item Require that every changeset pushed to the server have a valid
   1.640 +  bug~ID in its commit comment.  In this case, you'd want to configure
   1.641 +  the hook as a \hook{pretxncommit} hook.  This would allow the hook
   1.642 +  to reject changes that didn't contain bug IDs.
   1.643 +\item Allow incoming changesets to automatically modify the
   1.644 +  \emph{state} of a bug, as well as simply adding a comment.  For
   1.645 +  example, the hook could recognise the string ``fixed bug 31337'' as
   1.646 +  indicating that it should update the state of bug 31337 to
   1.647 +  ``requires testing''.
   1.648 +\end{itemize}
   1.649 +
   1.650 +\subsubsection{Configuring the \hook{bugzilla} hook}
   1.651 +\label{sec:hook:bugzilla:config}
   1.652 +
   1.653 +You should configure this hook in your server's \hgrc\ as an
   1.654 +\hook{incoming} hook, for example as follows:
   1.655 +\begin{codesample2}
   1.656 +  [hooks]
   1.657 +  incoming.bugzilla = python:hgext.bugzilla.hook
   1.658 +\end{codesample2}
   1.659 +
   1.660 +Because of the specialised nature of this hook, and because Bugzilla
   1.661 +was not written with this kind of integration in mind, configuring
   1.662 +this hook is a somewhat involved process.
   1.663 +
   1.664 +Before you begin, you must install the MySQL bindings for Python on
   1.665 +the host(s) where you'll be running the hook.  If this is not
   1.666 +available as a binary package for your system, you can download it
   1.667 +from~\cite{web:mysql-python}.
   1.668 +
   1.669 +Configuration information for this hook lives in the
   1.670 +\rcsection{bugzilla} section of your \hgrc.
   1.671 +\begin{itemize}
   1.672 +\item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
   1.673 +  the server.  The database schema that Bugzilla uses changes
   1.674 +  occasionally, so this hook has to know exactly which schema to use.
   1.675 +  At the moment, the only version supported is \texttt{2.16}.
   1.676 +\item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
   1.677 +  stores your Bugzilla data.  The database must be configured to allow
   1.678 +  connections from whatever host you are running the \hook{bugzilla}
   1.679 +  hook on.
   1.680 +\item[\rcitem{bugzilla}{user}] The username with which to connect to
   1.681 +  the MySQL server.  The database must be configured to allow this
   1.682 +  user to connect from whatever host you are running the
   1.683 +  \hook{bugzilla} hook on.  This user must be able to access and
   1.684 +  modify Bugzilla tables.  The default value of this item is
   1.685 +  \texttt{bugs}, which is the standard name of the Bugzilla user in a
   1.686 +  MySQL database.
   1.687 +\item[\rcitem{bugzilla}{password}] The MySQL password for the user you
   1.688 +  configured above.  This is stored as plain text, so you should make
   1.689 +  sure that unauthorised users cannot read the \hgrc\ file where you
   1.690 +  store this information.
   1.691 +\item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
   1.692 +  MySQL server.  The default value of this item is \texttt{bugs},
   1.693 +  which is the standard name of the MySQL database where Bugzilla
   1.694 +  stores its data.
   1.695 +\item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
   1.696 +  notification email to subscribers after this hook has added a
   1.697 +  comment to a bug, you will need this hook to run a command whenever
   1.698 +  it updates the database.  The command to run depends on where you
   1.699 +  have installed Bugzilla, but it will typically look something like
   1.700 +  this, if you have Bugzilla installed in
   1.701 +  \dirname{/var/www/html/bugzilla}:
   1.702 +  \begin{codesample4}
   1.703 +    cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
   1.704 +  \end{codesample4}
   1.705 +  The Bugzilla \texttt{processmail} program expects to be given a
   1.706 +  bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
   1.707 +  email address.  It also expects to be able to write to some files in
   1.708 +  the directory that it runs in.  If Bugzilla and this hook are not
   1.709 +  installed on the same machine, you will need to find a way to run
   1.710 +  \texttt{processmail} on the server where Bugzilla is installed.
   1.711 +\end{itemize}
   1.712 +
   1.713 +\subsubsection{Mapping committer names to Bugzilla user names}
   1.714 +
   1.715 +By default, the \hgext{bugzilla} hook tries to use the email address
   1.716 +of a changeset's committer as the Bugzilla user name with which to
   1.717 +update a bug.  If this does not suit your needs, you can map committer
   1.718 +email addresses to Bugzilla user names using a \rcsection{usermap}
   1.719 +section.
   1.720 +
   1.721 +Each item in the \rcsection{usermap} section contains an email address
   1.722 +on the left, and a Bugzilla user name on the right.
   1.723 +\begin{codesample2}
   1.724 +  [usermap]
   1.725 +  jane.user@example.com = jane
   1.726 +\end{codesample2}
   1.727 +You can either keep the \rcsection{usermap} data in a normal \hgrc, or
   1.728 +tell the \hgext{bugzilla} hook to read the information from an
   1.729 +external \filename{usermap} file.  In the latter case, you can store
   1.730 +\filename{usermap} data by itself in (for example) a user-modifiable
   1.731 +repository.  This makes it possible to let your users maintain their
   1.732 +own \rcitem{bugzilla}{usermap} entries.  The main \hgrc\ file might
   1.733 +look like this:
   1.734 +\begin{codesample2}
   1.735 +  # regular hgrc file refers to external usermap file
   1.736 +  [bugzilla]
   1.737 +  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
   1.738 +\end{codesample2}
   1.739 +While the \filename{usermap} file that it refers to might look like
   1.740 +this:
   1.741 +\begin{codesample2}
   1.742 +  # bugzilla-usermap.conf - inside a hg repository
   1.743 +  [usermap]
   1.744 +  stephanie@example.com = steph
   1.745 +\end{codesample2}
   1.746 +
   1.747 +\subsubsection{Configuring the text that gets added to a bug}
   1.748 +
   1.749 +You can configure the text that this hook adds as a comment; you
   1.750 +specify it in the form of a Mercurial template.  Several \hgrc\
   1.751 +entries (still in the \rcsection{bugzilla} section) control this
   1.752 +behaviour.
   1.753 +\begin{itemize}
   1.754 +\item[\texttt{strip}] The number of leading path elements to strip
   1.755 +  from a repository's path name to construct a partial path for a URL.
   1.756 +  For example, if the repositories on your server live under
   1.757 +  \dirname{/home/hg/repos}, and you have a repository whose path is
   1.758 +  \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
   1.759 +  \texttt{4} will give a partial path of \dirname{app/tests}.  The
   1.760 +  hook will make this partial path available when expanding a
   1.761 +  template, as \texttt{webroot}.
   1.762 +\item[\texttt{template}] The text of the template to use.  In addition
   1.763 +  to the usual changeset-related variables, this template can use
   1.764 +  \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
   1.765 +  above) and \texttt{webroot} (the path constructed using
   1.766 +  \texttt{strip} above).
   1.767 +\end{itemize}
   1.768 +
   1.769 +In addition, you can add a \rcitem{web}{baseurl} item to the
   1.770 +\rcsection{web} section of your \hgrc.  The \hgext{bugzilla} hook will
   1.771 +make this available when expanding a template, as the base string to
   1.772 +use when constructing a URL that will let users browse from a Bugzilla
   1.773 +comment to view a changeset.  Example:
   1.774 +\begin{codesample2}
   1.775 +  [web]
   1.776 +  baseurl = http://hg.domain.com/
   1.777 +\end{codesample2}
   1.778 +
   1.779 +Here is an example set of \hgext{bugzilla} hook config information.
   1.780 +\begin{codesample2}
   1.781 +  [bugzilla]
   1.782 +  host = bugzilla.example.com
   1.783 +  password = mypassword
   1.784 +  version = 2.16
   1.785 +  # server-side repos live in /home/hg/repos, so strip 4 leading
   1.786 +  # separators
   1.787 +  strip = 4
   1.788 +  hgweb = http://hg.example.com/
   1.789 +  usermap = /home/hg/repos/notify/bugzilla.conf
   1.790 +  template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
   1.791 +    repo, refers to this bug.\\nFor complete details, see 
   1.792 +    \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
   1.793 +    description:\\n\\t\{desc|tabindent\}
   1.794 +\end{codesample2}
   1.795 +
   1.796 +\subsubsection{Testing and troubleshooting}
   1.797 +
   1.798 +The most common problems with configuring the \hgext{bugzilla} hook
   1.799 +relate to running Bugzilla's \filename{processmail} script and mapping
   1.800 +committer names to user names.
   1.801 +
   1.802 +Recall from section~\ref{sec:hook:bugzilla:config} above that the user
   1.803 +that runs the Mercurial process on the server is also the one that
   1.804 +will run the \filename{processmail} script.  The
   1.805 +\filename{processmail} script sometimes causes Bugzilla to write to
   1.806 +files in its configuration directory, and Bugzilla's configuration
   1.807 +files are usually owned by the user that your web server runs under.
   1.808 +
   1.809 +You can cause \filename{processmail} to be run with the suitable
   1.810 +user's identity using the \command{sudo} command.  Here is an example
   1.811 +entry for a \filename{sudoers} file.
   1.812 +\begin{codesample2}
   1.813 +  hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
   1.814 +\end{codesample2}
   1.815 +This allows the \texttt{hg\_user} user to run a
   1.816 +\filename{processmail-wrapper} program under the identity of
   1.817 +\texttt{httpd\_user}.
   1.818 +
   1.819 +This indirection through a wrapper script is necessary, because
   1.820 +\filename{processmail} expects to be run with its current directory
   1.821 +set to wherever you installed Bugzilla; you can't specify that kind of
   1.822 +constraint in a \filename{sudoers} file.  The contents of the wrapper
   1.823 +script are simple:
   1.824 +\begin{codesample2}
   1.825 +  #!/bin/sh
   1.826 +  cd `dirname $0` && ./processmail "$1" nobody@example.com
   1.827 +\end{codesample2}
   1.828 +It doesn't seem to matter what email address you pass to
   1.829 +\filename{processmail}.
   1.830 +
   1.831 +If your \rcsection{usermap} is not set up correctly, users will see an
   1.832 +error message from the \hgext{bugzilla} hook when they push changes
   1.833 +to the server.  The error message will look like this:
   1.834 +\begin{codesample2}
   1.835 +  cannot find bugzilla user id for john.q.public@example.com
   1.836 +\end{codesample2}
   1.837 +What this means is that the committer's address,
   1.838 +\texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
   1.839 +nor does it have an entry in your \rcsection{usermap} that maps it to
   1.840 +a valid Bugzilla user name.
   1.841 +
   1.842 +\subsection{\hgext{notify}---send email notifications}
   1.843 +
   1.844 +Although Mercurial's built-in web server provides RSS feeds of changes
   1.845 +in every repository, many people prefer to receive change
   1.846 +notifications via email.  The \hgext{notify} hook lets you send out
   1.847 +notifications to a set of email addresses whenever changesets arrive
   1.848 +that those subscribers are interested in.
   1.849 +
   1.850 +As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
   1.851 +template-driven, so you can customise the contents of the notification
   1.852 +messages that it sends.
   1.853 +
   1.854 +By default, the \hgext{notify} hook includes a diff of every changeset
   1.855 +that it sends out; you can limit the size of the diff, or turn this
   1.856 +feature off entirely.  It is useful for letting subscribers review
   1.857 +changes immediately, rather than clicking to follow a URL.
   1.858 +
   1.859 +\subsubsection{Configuring the \hgext{notify} hook}
   1.860 +
   1.861 +You can set up the \hgext{notify} hook to send one email message per
   1.862 +incoming changeset, or one per incoming group of changesets (all those
   1.863 +that arrived in a single pull or push).
   1.864 +\begin{codesample2}
   1.865 +  [hooks]
   1.866 +  # send one email per group of changes
   1.867 +  changegroup.notify = python:hgext.notify.hook
   1.868 +  # send one email per change
   1.869 +  incoming.notify = python:hgext.notify.hook
   1.870 +\end{codesample2}
   1.871 +
   1.872 +Configuration information for this hook lives in the
   1.873 +\rcsection{notify} section of a \hgrc\ file.
   1.874 +\begin{itemize}
   1.875 +\item[\rcitem{notify}{test}] By default, this hook does not send out
   1.876 +  email at all; instead, it prints the message that it \emph{would}
   1.877 +  send.  Set this item to \texttt{false} to allow email to be sent.
   1.878 +  The reason that sending of email is turned off by default is that it
   1.879 +  takes several tries to configure this extension exactly as you would
   1.880 +  like, and it would be bad form to spam subscribers with a number of
   1.881 +  ``broken'' notifications while you debug your configuration.
   1.882 +\item[\rcitem{notify}{config}] The path to a configuration file that
   1.883 +  contains subscription information.  This is kept separate from the
   1.884 +  main \hgrc\ so that you can maintain it in a repository of its own.
   1.885 +  People can then clone that repository, update their subscriptions,
   1.886 +  and push the changes back to your server.
   1.887 +\item[\rcitem{notify}{strip}] The number of leading path separator
   1.888 +  characters to strip from a repository's path, when deciding whether
   1.889 +  a repository has subscribers.  For example, if the repositories on
   1.890 +  your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
   1.891 +  considering a repository named \dirname{/home/hg/repos/shared/test},
   1.892 +  setting \rcitem{notify}{strip} to \texttt{4} will cause
   1.893 +  \hgext{notify} to trim the path it considers down to
   1.894 +  \dirname{shared/test}, and it will match subscribers against that.
   1.895 +\item[\rcitem{notify}{template}] The template text to use when sending
   1.896 +  messages.  This specifies both the contents of the message header
   1.897 +  and its body.
   1.898 +\item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
   1.899 +  data to append to the end of a message.  If a diff is longer than
   1.900 +  this, it is truncated.  By default, this is set to 300.  Set this to
   1.901 +  \texttt{0} to omit diffs from notification emails.
   1.902 +\item[\rcitem{notify}{sources}] A list of sources of changesets to
   1.903 +  consider.  This lets you limit \hgext{notify} to only sending out
   1.904 +  email about changes that remote users pushed into this repository
   1.905 +  via a server, for example.  See section~\ref{sec:hook:sources} for
   1.906 +  the sources you can specify here.
   1.907 +\end{itemize}
   1.908 +
   1.909 +If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
   1.910 +section, you can use it in a template; it will be available as
   1.911 +\texttt{webroot}.
   1.912 +
   1.913 +Here is an example set of \hgext{notify} configuration information.
   1.914 +\begin{codesample2}
   1.915 +  [notify]
   1.916 +  # really send email
   1.917 +  test = false
   1.918 +  # subscriber data lives in the notify repo
   1.919 +  config = /home/hg/repos/notify/notify.conf
   1.920 +  # repos live in /home/hg/repos on server, so strip 4 "/" chars
   1.921 +  strip = 4
   1.922 +  template = X-Hg-Repo: \{webroot\}
   1.923 +    Subject: \{webroot\}: \{desc|firstline|strip\}
   1.924 +    From: \{author\}
   1.925 +
   1.926 +    changeset \{node|short\} in \{root\}
   1.927 +    details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
   1.928 +    description:
   1.929 +      \{desc|tabindent|strip\}
   1.930 +
   1.931 +  [web]
   1.932 +  baseurl = http://hg.example.com/
   1.933 +\end{codesample2}
   1.934 +
   1.935 +This will produce a message that looks like the following:
   1.936 +\begin{codesample2}
   1.937 +  X-Hg-Repo: tests/slave
   1.938 +  Subject: tests/slave: Handle error case when slave has no buffers
   1.939 +  Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
   1.940 +
   1.941 +  changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
   1.942 +  details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
   1.943 +  description:
   1.944 +          Handle error case when slave has no buffers
   1.945 +  diffs (54 lines):
   1.946 +
   1.947 +  diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
   1.948 +  --- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
   1.949 +  +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
   1.950 +  @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
   1.951 +  [...snip...]
   1.952 +\end{codesample2}
   1.953 +
   1.954 +\subsubsection{Testing and troubleshooting}
   1.955 +
   1.956 +Do not forget that by default, the \hgext{notify} extension \emph{will
   1.957 +  not send any mail} until you explicitly configure it to do so, by
   1.958 +setting \rcitem{notify}{test} to \texttt{false}.  Until you do that,
   1.959 +it simply prints the message it \emph{would} send.
   1.960 +
   1.961 +\section{Information for writers of hooks}
   1.962 +\label{sec:hook:ref}
   1.963 +
   1.964 +\subsection{In-process hook execution}
   1.965 +
   1.966 +An in-process hook is called with arguments of the following form:
   1.967 +\begin{codesample2}
   1.968 +  def myhook(ui, repo, **kwargs):
   1.969 +      pass
   1.970 +\end{codesample2}
   1.971 +The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
   1.972 +The \texttt{repo} parameter is a
   1.973 +\pymodclass{mercurial.localrepo}{localrepository} object.  The
   1.974 +names and values of the \texttt{**kwargs} parameters depend on the
   1.975 +hook being invoked, with the following common features:
   1.976 +\begin{itemize}
   1.977 +\item If a parameter is named \texttt{node} or
   1.978 +  \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
   1.979 +  The empty string is used to represent ``null changeset ID'' instead
   1.980 +  of a string of zeroes.
   1.981 +\item If a parameter is named \texttt{url}, it will contain the URL of
   1.982 +  a remote repository, if that can be determined.
   1.983 +\item Boolean-valued parameters are represented as Python
   1.984 +  \texttt{bool} objects.
   1.985 +\end{itemize}
   1.986 +
   1.987 +An in-process hook is called without a change to the process's working
   1.988 +directory (unlike external hooks, which are run in the root of the
   1.989 +repository).  It must not change the process's working directory, or
   1.990 +it will cause any calls it makes into the Mercurial API to fail.
   1.991 +
   1.992 +If a hook returns a boolean ``false'' value, it is considered to have
   1.993 +succeeded.  If it returns a boolean ``true'' value or raises an
   1.994 +exception, it is considered to have failed.  A useful way to think of
   1.995 +the calling convention is ``tell me if you fail''.
   1.996 +
   1.997 +Note that changeset IDs are passed into Python hooks as hexadecimal
   1.998 +strings, not the binary hashes that Mercurial's APIs normally use.  To
   1.999 +convert a hash from hex to binary, use the
  1.1000 +\pymodfunc{mercurial.node}{bin} function.
  1.1001 +
  1.1002 +\subsection{External hook execution}
  1.1003 +
  1.1004 +An external hook is passed to the shell of the user running Mercurial.
  1.1005 +Features of that shell, such as variable substitution and command
  1.1006 +redirection, are available.  The hook is run in the root directory of
  1.1007 +the repository (unlike in-process hooks, which are run in the same
  1.1008 +directory that Mercurial was run in).
  1.1009 +
  1.1010 +Hook parameters are passed to the hook as environment variables.  Each
  1.1011 +environment variable's name is converted in upper case and prefixed
  1.1012 +with the string ``\texttt{HG\_}''.  For example, if the name of a
  1.1013 +parameter is ``\texttt{node}'', the name of the environment variable
  1.1014 +representing that parameter will be ``\texttt{HG\_NODE}''.
  1.1015 +
  1.1016 +A boolean parameter is represented as the string ``\texttt{1}'' for
  1.1017 +``true'', ``\texttt{0}'' for ``false''.  If an environment variable is
  1.1018 +named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
  1.1019 +contains a changeset ID represented as a hexadecimal string.  The
  1.1020 +empty string is used to represent ``null changeset ID'' instead of a
  1.1021 +string of zeroes.  If an environment variable is named
  1.1022 +\envar{HG\_URL}, it will contain the URL of a remote repository, if
  1.1023 +that can be determined.
  1.1024 +
  1.1025 +If a hook exits with a status of zero, it is considered to have
  1.1026 +succeeded.  If it exits with a non-zero status, it is considered to
  1.1027 +have failed.
  1.1028 +
  1.1029 +\subsection{Finding out where changesets come from}
  1.1030 +
  1.1031 +A hook that involves the transfer of changesets between a local
  1.1032 +repository and another may be able to find out information about the
  1.1033 +``far side''.  Mercurial knows \emph{how} changes are being
  1.1034 +transferred, and in many cases \emph{where} they are being transferred
  1.1035 +to or from.
  1.1036 +
  1.1037 +\subsubsection{Sources of changesets}
  1.1038 +\label{sec:hook:sources}
  1.1039 +
  1.1040 +Mercurial will tell a hook what means are, or were, used to transfer
  1.1041 +changesets between repositories.  This is provided by Mercurial in a
  1.1042 +Python parameter named \texttt{source}, or an environment variable named
  1.1043 +\envar{HG\_SOURCE}.
  1.1044 +
  1.1045 +\begin{itemize}
  1.1046 +\item[\texttt{serve}] Changesets are transferred to or from a remote
  1.1047 +  repository over http or ssh.
  1.1048 +\item[\texttt{pull}] Changesets are being transferred via a pull from
  1.1049 +  one repository into another.
  1.1050 +\item[\texttt{push}] Changesets are being transferred via a push from
  1.1051 +  one repository into another.
  1.1052 +\item[\texttt{bundle}] Changesets are being transferred to or from a
  1.1053 +  bundle.
  1.1054 +\end{itemize}
  1.1055 +
  1.1056 +\subsubsection{Where changes are going---remote repository URLs}
  1.1057 +\label{sec:hook:url}
  1.1058 +
  1.1059 +When possible, Mercurial will tell a hook the location of the ``far
  1.1060 +side'' of an activity that transfers changeset data between
  1.1061 +repositories.  This is provided by Mercurial in a Python parameter
  1.1062 +named \texttt{url}, or an environment variable named \envar{HG\_URL}.
  1.1063 +
  1.1064 +This information is not always known.  If a hook is invoked in a
  1.1065 +repository that is being served via http or ssh, Mercurial cannot tell
  1.1066 +where the remote repository is, but it may know where the client is
  1.1067 +connecting from.  In such cases, the URL will take one of the
  1.1068 +following forms:
  1.1069 +\begin{itemize}
  1.1070 +\item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
  1.1071 +  the given IP address.
  1.1072 +\item \texttt{remote:http:\emph{ip-address}}---remote http client, at
  1.1073 +  the given IP address.  If the client is using SSL, this will be of
  1.1074 +  the form \texttt{remote:https:\emph{ip-address}}.
  1.1075 +\item Empty---no information could be discovered about the remote
  1.1076 +  client.
  1.1077 +\end{itemize}
  1.1078 +
  1.1079 +\section{Hook reference}
  1.1080 +
  1.1081 +\subsection{\hook{changegroup}---after remote changesets added}
  1.1082 +\label{sec:hook:changegroup}
  1.1083 +
  1.1084 +This hook is run after a group of pre-existing changesets has been
  1.1085 +added to the repository, for example via a \hgcmd{pull} or
  1.1086 +\hgcmd{unbundle}.  This hook is run once per operation that added one
  1.1087 +or more changesets.  This is in contrast to the \hook{incoming} hook,
  1.1088 +which is run once per changeset, regardless of whether the changesets
  1.1089 +arrive in a group.
  1.1090 +
  1.1091 +Some possible uses for this hook include kicking off an automated
  1.1092 +build or test of the added changesets, updating a bug database, or
  1.1093 +notifying subscribers that a repository contains new changes.
  1.1094 +
  1.1095 +Parameters to this hook:
  1.1096 +\begin{itemize}
  1.1097 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
  1.1098 +  changeset in the group that was added.  All changesets between this
  1.1099 +  and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
  1.1100 +  a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
  1.1101 +\item[\texttt{source}] A string.  The source of these changes.  See
  1.1102 +  section~\ref{sec:hook:sources} for details.
  1.1103 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1104 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1105 +\end{itemize}
  1.1106 +
  1.1107 +See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
  1.1108 +\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
  1.1109 +\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  1.1110 +
  1.1111 +\subsection{\hook{commit}---after a new changeset is created}
  1.1112 +\label{sec:hook:commit}
  1.1113 +
  1.1114 +This hook is run after a new changeset has been created.
  1.1115 +
  1.1116 +Parameters to this hook:
  1.1117 +\begin{itemize}
  1.1118 +\item[\texttt{node}] A changeset ID.  The changeset ID of the newly
  1.1119 +  committed changeset.
  1.1120 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
  1.1121 +  parent of the newly committed changeset.
  1.1122 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
  1.1123 +  parent of the newly committed changeset.
  1.1124 +\end{itemize}
  1.1125 +
  1.1126 +See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
  1.1127 +\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
  1.1128 +
  1.1129 +\subsection{\hook{incoming}---after one remote changeset is added}
  1.1130 +\label{sec:hook:incoming}
  1.1131 +
  1.1132 +This hook is run after a pre-existing changeset has been added to the
  1.1133 +repository, for example via a \hgcmd{push}.  If a group of changesets
  1.1134 +was added in a single operation, this hook is called once for each
  1.1135 +added changeset.
  1.1136 +
  1.1137 +You can use this hook for the same purposes as the \hook{changegroup}
  1.1138 +hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
  1.1139 +sometimes to run a hook once per group of changesets, while other
  1.1140 +times it's handier once per changeset.
  1.1141 +
  1.1142 +Parameters to this hook:
  1.1143 +\begin{itemize}
  1.1144 +\item[\texttt{node}] A changeset ID.  The ID of the newly added
  1.1145 +  changeset.
  1.1146 +\item[\texttt{source}] A string.  The source of these changes.  See
  1.1147 +  section~\ref{sec:hook:sources} for details.
  1.1148 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1149 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1150 +\end{itemize}
  1.1151 +
  1.1152 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  1.1153 +
  1.1154 +\subsection{\hook{outgoing}---after changesets are propagated}
  1.1155 +\label{sec:hook:outgoing}
  1.1156 +
  1.1157 +This hook is run after a group of changesets has been propagated out
  1.1158 +of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
  1.1159 +command.
  1.1160 +
  1.1161 +One possible use for this hook is to notify administrators that
  1.1162 +changes have been pulled.
  1.1163 +
  1.1164 +Parameters to this hook:
  1.1165 +\begin{itemize}
  1.1166 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
  1.1167 +  changeset of the group that was sent.
  1.1168 +\item[\texttt{source}] A string.  The source of the of the operation
  1.1169 +  (see section~\ref{sec:hook:sources}).  If a remote client pulled
  1.1170 +  changes from this repository, \texttt{source} will be
  1.1171 +  \texttt{serve}.  If the client that obtained changes from this
  1.1172 +  repository was local, \texttt{source} will be \texttt{bundle},
  1.1173 +  \texttt{pull}, or \texttt{push}, depending on the operation the
  1.1174 +  client performed.
  1.1175 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1176 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1177 +\end{itemize}
  1.1178 +
  1.1179 +See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
  1.1180 +
  1.1181 +\subsection{\hook{prechangegroup}---before starting to add remote changesets}
  1.1182 +\label{sec:hook:prechangegroup}
  1.1183 +
  1.1184 +This controlling hook is run before Mercurial begins to add a group of
  1.1185 +changesets from another repository.
  1.1186 +
  1.1187 +This hook does not have any information about the changesets to be
  1.1188 +added, because it is run before transmission of those changesets is
  1.1189 +allowed to begin.  If this hook fails, the changesets will not be
  1.1190 +transmitted.
  1.1191 +
  1.1192 +One use for this hook is to prevent external changes from being added
  1.1193 +to a repository.  For example, you could use this to ``freeze'' a
  1.1194 +server-hosted branch temporarily or permanently so that users cannot
  1.1195 +push to it, while still allowing a local administrator to modify the
  1.1196 +repository.
  1.1197 +
  1.1198 +Parameters to this hook:
  1.1199 +\begin{itemize}
  1.1200 +\item[\texttt{source}] A string.  The source of these changes.  See
  1.1201 +  section~\ref{sec:hook:sources} for details.
  1.1202 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1203 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1204 +\end{itemize}
  1.1205 +
  1.1206 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
  1.1207 +\hook{incoming} (section~\ref{sec:hook:incoming}), ,
  1.1208 +\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
  1.1209 +
  1.1210 +\subsection{\hook{precommit}---before starting to commit a changeset}
  1.1211 +\label{sec:hook:precommit}
  1.1212 +
  1.1213 +This hook is run before Mercurial begins to commit a new changeset.
  1.1214 +It is run before Mercurial has any of the metadata for the commit,
  1.1215 +such as the files to be committed, the commit message, or the commit
  1.1216 +date.
  1.1217 +
  1.1218 +One use for this hook is to disable the ability to commit new
  1.1219 +changesets, while still allowing incoming changesets.  Another is to
  1.1220 +run a build or test, and only allow the commit to begin if the build
  1.1221 +or test succeeds.
  1.1222 +
  1.1223 +Parameters to this hook:
  1.1224 +\begin{itemize}
  1.1225 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
  1.1226 +  parent of the working directory.
  1.1227 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
  1.1228 +  parent of the working directory.
  1.1229 +\end{itemize}
  1.1230 +If the commit proceeds, the parents of the working directory will
  1.1231 +become the parents of the new changeset.
  1.1232 +
  1.1233 +See also: \hook{commit} (section~\ref{sec:hook:commit}),
  1.1234 +\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
  1.1235 +
  1.1236 +\subsection{\hook{preoutgoing}---before starting to propagate changesets}
  1.1237 +\label{sec:hook:preoutgoing}
  1.1238 +
  1.1239 +This hook is invoked before Mercurial knows the identities of the
  1.1240 +changesets to be transmitted.
  1.1241 +
  1.1242 +One use for this hook is to prevent changes from being transmitted to
  1.1243 +another repository.
  1.1244 +
  1.1245 +Parameters to this hook:
  1.1246 +\begin{itemize}
  1.1247 +\item[\texttt{source}] A string.  The source of the operation that is
  1.1248 +  attempting to obtain changes from this repository (see
  1.1249 +  section~\ref{sec:hook:sources}).  See the documentation for the
  1.1250 +  \texttt{source} parameter to the \hook{outgoing} hook, in
  1.1251 +  section~\ref{sec:hook:outgoing}, for possible values of this
  1.1252 +  parameter.
  1.1253 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1254 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1255 +\end{itemize}
  1.1256 +
  1.1257 +See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
  1.1258 +
  1.1259 +\subsection{\hook{pretag}---before tagging a changeset}
  1.1260 +\label{sec:hook:pretag}
  1.1261 +
  1.1262 +This controlling hook is run before a tag is created.  If the hook
  1.1263 +succeeds, creation of the tag proceeds.  If the hook fails, the tag is
  1.1264 +not created.
  1.1265 +
  1.1266 +Parameters to this hook:
  1.1267 +\begin{itemize}
  1.1268 +\item[\texttt{local}] A boolean.  Whether the tag is local to this
  1.1269 +  repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
  1.1270 +  managed by Mercurial (stored in \sfilename{.hgtags}).
  1.1271 +\item[\texttt{node}] A changeset ID.  The ID of the changeset to be tagged.
  1.1272 +\item[\texttt{tag}] A string.  The name of the tag to be created.
  1.1273 +\end{itemize}
  1.1274 +
  1.1275 +If the tag to be created is revision-controlled, the \hook{precommit}
  1.1276 +and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
  1.1277 +and~\ref{sec:hook:pretxncommit}) will also be run.
  1.1278 +
  1.1279 +See also: \hook{tag} (section~\ref{sec:hook:tag})
  1.1280 +
  1.1281 +\subsection{\hook{pretxnchangegroup}---before completing addition of
  1.1282 +  remote changesets}
  1.1283 +\label{sec:hook:pretxnchangegroup}
  1.1284 +
  1.1285 +This controlling hook is run before a transaction---that manages the
  1.1286 +addition of a group of new changesets from outside the
  1.1287 +repository---completes.  If the hook succeeds, the transaction
  1.1288 +completes, and all of the changesets become permanent within this
  1.1289 +repository.  If the hook fails, the transaction is rolled back, and
  1.1290 +the data for the changesets is erased.
  1.1291 +
  1.1292 +This hook can access the metadata associated with the almost-added
  1.1293 +changesets, but it should not do anything permanent with this data.
  1.1294 +It must also not modify the working directory.
  1.1295 +
  1.1296 +While this hook is running, if other Mercurial processes access this
  1.1297 +repository, they will be able to see the almost-added changesets as if
  1.1298 +they are permanent.  This may lead to race conditions if you do not
  1.1299 +take steps to avoid them.
  1.1300 +
  1.1301 +This hook can be used to automatically vet a group of changesets.  If
  1.1302 +the hook fails, all of the changesets are ``rejected'' when the
  1.1303 +transaction rolls back.
  1.1304 +
  1.1305 +Parameters to this hook:
  1.1306 +\begin{itemize}
  1.1307 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
  1.1308 +  changeset in the group that was added.  All changesets between this
  1.1309 +  and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
  1.1310 +  a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
  1.1311 +\item[\texttt{source}] A string.  The source of these changes.  See
  1.1312 +  section~\ref{sec:hook:sources} for details.
  1.1313 +\item[\texttt{url}] A URL.  The location of the remote repository, if
  1.1314 +  known.  See section~\ref{sec:hook:url} for more information.
  1.1315 +\end{itemize}
  1.1316 +
  1.1317 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
  1.1318 +\hook{incoming} (section~\ref{sec:hook:incoming}),
  1.1319 +\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
  1.1320 +
  1.1321 +\subsection{\hook{pretxncommit}---before completing commit of new changeset}
  1.1322 +\label{sec:hook:pretxncommit}
  1.1323 +
  1.1324 +This controlling hook is run before a transaction---that manages a new
  1.1325 +commit---completes.  If the hook succeeds, the transaction completes
  1.1326 +and the changeset becomes permanent within this repository.  If the
  1.1327 +hook fails, the transaction is rolled back, and the commit data is
  1.1328 +erased.
  1.1329 +
  1.1330 +This hook can access the metadata associated with the almost-new
  1.1331 +changeset, but it should not do anything permanent with this data.  It
  1.1332 +must also not modify the working directory.
  1.1333 +
  1.1334 +While this hook is running, if other Mercurial processes access this
  1.1335 +repository, they will be able to see the almost-new changeset as if it
  1.1336 +is permanent.  This may lead to race conditions if you do not take
  1.1337 +steps to avoid them.
  1.1338 +
  1.1339 +Parameters to this hook:
  1.1340 +\begin{itemize}
  1.1341 +\item[\texttt{node}] A changeset ID.  The changeset ID of the newly
  1.1342 +  committed changeset.
  1.1343 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
  1.1344 +  parent of the newly committed changeset.
  1.1345 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
  1.1346 +  parent of the newly committed changeset.
  1.1347 +\end{itemize}
  1.1348 +
  1.1349 +See also: \hook{precommit} (section~\ref{sec:hook:precommit})
  1.1350 +
  1.1351 +\subsection{\hook{preupdate}---before updating or merging working directory}
  1.1352 +\label{sec:hook:preupdate}
  1.1353 +
  1.1354 +This controlling hook is run before an update or merge of the working
  1.1355 +directory begins.  It is run only if Mercurial's normal pre-update
  1.1356 +checks determine that the update or merge can proceed.  If the hook
  1.1357 +succeeds, the update or merge may proceed; if it fails, the update or
  1.1358 +merge does not start.
  1.1359 +
  1.1360 +Parameters to this hook:
  1.1361 +\begin{itemize}
  1.1362 +\item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
  1.1363 +  working directory is to be updated to.  If the working directory is
  1.1364 +  being merged, it will not change this parent.
  1.1365 +\item[\texttt{parent2}] A changeset ID.  Only set if the working
  1.1366 +  directory is being merged.  The ID of the revision that the working
  1.1367 +  directory is being merged with.
  1.1368 +\end{itemize}
  1.1369 +
  1.1370 +See also: \hook{update} (section~\ref{sec:hook:update})
  1.1371 +
  1.1372 +\subsection{\hook{tag}---after tagging a changeset}
  1.1373 +\label{sec:hook:tag}
  1.1374 +
  1.1375 +This hook is run after a tag has been created.
  1.1376 +
  1.1377 +Parameters to this hook:
  1.1378 +\begin{itemize}
  1.1379 +\item[\texttt{local}] A boolean.  Whether the new tag is local to this
  1.1380 +  repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
  1.1381 +  managed by Mercurial (stored in \sfilename{.hgtags}).
  1.1382 +\item[\texttt{node}] A changeset ID.  The ID of the changeset that was
  1.1383 +  tagged.
  1.1384 +\item[\texttt{tag}] A string.  The name of the tag that was created.
  1.1385 +\end{itemize}
  1.1386 +
  1.1387 +If the created tag is revision-controlled, the \hook{commit} hook
  1.1388 +(section~\ref{sec:hook:commit}) is run before this hook.
  1.1389 +
  1.1390 +See also: \hook{pretag} (section~\ref{sec:hook:pretag})
  1.1391 +
  1.1392 +\subsection{\hook{update}---after updating or merging working directory}
  1.1393 +\label{sec:hook:update}
  1.1394 +
  1.1395 +This hook is run after an update or merge of the working directory
  1.1396 +completes.  Since a merge can fail (if the external \command{hgmerge}
  1.1397 +command fails to resolve conflicts in a file), this hook communicates
  1.1398 +whether the update or merge completed cleanly.
  1.1399 +
  1.1400 +\begin{itemize}
  1.1401 +\item[\texttt{error}] A boolean.  Indicates whether the update or
  1.1402 +  merge completed successfully.
  1.1403 +\item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
  1.1404 +  working directory was updated to.  If the working directory was
  1.1405 +  merged, it will not have changed this parent.
  1.1406 +\item[\texttt{parent2}] A changeset ID.  Only set if the working
  1.1407 +  directory was merged.  The ID of the revision that the working
  1.1408 +  directory was merged with.
  1.1409 +\end{itemize}
  1.1410 +
  1.1411 +See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
  1.1412 +
  1.1413 +%%% Local Variables: 
  1.1414 +%%% mode: latex
  1.1415 +%%% TeX-master: "00book"
  1.1416 +%%% End: