1.1 --- a/en/hook.tex	Sun Jul 16 00:01:43 2006 -0700
     1.2 +++ b/en/hook.tex	Mon Jul 17 00:01:01 2006 -0700
     1.3 @@ -95,11 +95,18 @@
     1.4  comment contains a bug ID.  If it does, the commit can complete.  If
     1.5  not, the commit is rolled back.
     1.6  
     1.7 -\section{Choosing how to write a hook}
     1.8 -\label{sec:hook:impl}
     1.9 +\section{Writing your own hooks}
    1.10 +
    1.11 +When you are writing a hook, you might find it useful to run Mercurial
    1.12 +either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
    1.13 +item set to ``true''.  When you do so, Mercurial will print a message
    1.14 +before it calls each hook.
    1.15 +
    1.16 +\subsection{Choosing how your hook should run}
    1.17 +\label{sec:hook:lang}
    1.18  
    1.19  You can write a hook either as a normal program---typically a shell
    1.20 -script---or as a Python function that is called within the Mercurial
    1.21 +script---or as a Python function that is executed within the Mercurial
    1.22  process.
    1.23  
    1.24  Writing a hook as an external program has the advantage that it
    1.25 @@ -119,7 +126,7 @@
    1.26  performance (probably the majority of hooks), a shell script is
    1.27  perfectly fine.
    1.28  
    1.29 -\section{Hook parameters}
    1.30 +\subsection{Hook parameters}
    1.31  \label{sec:hook:param}
    1.32  
    1.33  Mercurial calls each hook with a set of well-defined parameters.  In
    1.34 @@ -128,9 +135,82 @@
    1.35  environment variable.
    1.36  
    1.37  Whether your hook is written in Python or as a shell script, the
    1.38 -parameter names and values will be the same.  A boolean parameter will
    1.39 -be represented as a boolean value in Python, but as the number 1 (for
    1.40 -``true'') or 0 (for ``false'')
    1.41 +hook-specific parameter names and values will be the same.  A boolean
    1.42 +parameter will be represented as a boolean value in Python, but as the
    1.43 +number 1 (for ``true'') or 0 (for ``false'') as an environment
    1.44 +variable for an external hook.  If a hook parameter is named
    1.45 +\texttt{foo}, the keyword argument for a Python hook will also be
    1.46 +named \texttt{foo} Python, while the environment variable for an
    1.47 +external hook will be named \texttt{HG\_FOO}.
    1.48 +
    1.49 +\subsection{Hook return values and activity control}
    1.50 +
    1.51 +A hook that executes successfully must exit with a status of zero if
    1.52 +external, or return boolean ``false'' if in-process.  Failure is
    1.53 +indicated with a non-zero exit status from an external hook, or an
    1.54 +in-process hook returning boolean ``true''.  If an in-process hook
    1.55 +raises an exception, the hook is considered to have failed.
    1.56 +
    1.57 +For a hook that controls whether an activity can proceed, zero/false
    1.58 +means ``allow'', while non-zero/true/exception means ``deny''.
    1.59 +
    1.60 +\subsection{Writing an external hook}
    1.61 +
    1.62 +When you define an external hook in your \hgrc\ and the hook is run,
    1.63 +its value is passed to your shell, which interprets it.  This means
    1.64 +that you can use normal shell constructs in the body of the hook.
    1.65 +
    1.66 +An executable hook is always run with its current directory set to a
    1.67 +repository's root directory.
    1.68 +
    1.69 +Each hook parameter is passed in as an environment variable; the name
    1.70 +is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
    1.71 +
    1.72 +With the exception of hook parameters, Mercurial does not set or
    1.73 +modify any environment variables when running a hook.  This is useful
    1.74 +to remember if you are writing a site-wide hook that may be run by a
    1.75 +number of different users with differing environment variables set.
    1.76 +In multi-user situations, you should not rely on environment variables
    1.77 +being set to the values you have in your environment when testing the
    1.78 +hook.
    1.79 +
    1.80 +\subsection{Telling Mercurial to use an in-process hook}
    1.81 +
    1.82 +The \hgrc\ syntax for defining an in-process hook is slightly
    1.83 +different than for an executable hook.  The value of the hook must
    1.84 +start with the text ``\texttt{python:}'', and continue with the
    1.85 +fully-qualified name of a callable object to use as the hook's value.
    1.86 +
    1.87 +The module in which a hook lives is automatically imported when a hook
    1.88 +is run.  So long as you have the module name and \envar{PYTHONPATH}
    1.89 +right, it should ``just work''.
    1.90 +
    1.91 +The following \hgrc\ example snippet illustrates the syntax and
    1.92 +meaning of the notions we just described.
    1.93 +\begin{codesample2}
    1.94 +  [hooks]
    1.95 +  commit.example = python:mymodule.submodule.myhook
    1.96 +\end{codesample2}
    1.97 +When Mercurial runs the \texttt{commit.example} hook, it imports
    1.98 +\texttt{mymodule.submodule}, looks for the callable object named
    1.99 +\texttt{myhook}, and calls it.
   1.100 +
   1.101 +\subsection{Writing an in-process hook}
   1.102 +
   1.103 +The simplest in-process hook does nothing, but illustrates the basic
   1.104 +shape of the hook API:
   1.105 +\begin{codesample2}
   1.106 +  def myhook(ui, repo, **kwargs):
   1.107 +      pass
   1.108 +\end{codesample2}
   1.109 +The first argument to a Python hook is always a
   1.110 +\pymodclass{mercurial.ui}{ui} object.  The second is a repository object;
   1.111 +at the moment, it is always an instance of
   1.112 +\pymodclass{mercurial.localrepo}{localrepository}.  Following these two
   1.113 +arguments are other keyword arguments.  Which ones are passed in
   1.114 +depends on the hook being called, but a hook can ignore arguments it
   1.115 +doesn't care about by dropping them into a keyword argument dict, as
   1.116 +with \texttt{**kwargs} above.
   1.117  
   1.118  
   1.119  %%% Local Variables: