1.1 --- a/en/hook.tex	Wed Jul 19 00:06:21 2006 -0700
     1.2 +++ b/en/hook.tex	Wed Jul 19 16:32:10 2006 -0700
     1.3 @@ -381,6 +381,88 @@
     1.4  doesn't care about by dropping them into a keyword argument dict, as
     1.5  with \texttt{**kwargs} above.
     1.6  
     1.7 +\section{Hook reference}
     1.8 +
     1.9 +
    1.10 +\subsection{In-process hook execution}
    1.11 +
    1.12 +An in-process hook is called with arguments of the following form:
    1.13 +\begin{codesample2}
    1.14 +  def myhook(ui, repo, **kwargs):
    1.15 +      pass
    1.16 +\end{codesample2}
    1.17 +The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
    1.18 +The \texttt{repo} parameter is a
    1.19 +\pymodclass{mercurial.localrepo}{localrepository} object.  The
    1.20 +names and values of the \texttt{**kwargs} parameters depend on the
    1.21 +hook being invoked, with the following common features:
    1.22 +\begin{itemize}
    1.23 +\item If a parameter is named \texttt{node} or
    1.24 +  \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
    1.25 +  The empty string is used to represent ``null changeset ID'' instead
    1.26 +  of a string of zeroes.
    1.27 +\item Boolean-valued parameters are represented as Python
    1.28 +  \texttt{bool} objects.
    1.29 +\end{itemize}
    1.30 +
    1.31 +An in-process hook is called without a change to the process's working
    1.32 +directory (unlike external hooks, which are run in the root of the
    1.33 +repository).  It must not change the process's working directory.  If
    1.34 +it were to do so, it would probably cause calls to the Mercurial API,
    1.35 +or operations after the hook finishes, to fail.
    1.36 +
    1.37 +If a hook returns a boolean ``false'' value, it is considered to
    1.38 +have succeeded.  If it returns a boolean ``true'' value or raises an
    1.39 +exception, it is considered to have failed.
    1.40 +
    1.41 +\subsection{External hook execution}
    1.42 +
    1.43 +An external hook is passed to the user's shell for execution, so
    1.44 +features of that shell, such as variable substitution and command
    1.45 +redirection, are available.  The hook is run in the root directory of
    1.46 +the repository.
    1.47 +
    1.48 +Hook parameters are passed to the hook as environment variables.  Each
    1.49 +environment variable's name is converted in upper case and prefixed
    1.50 +with the string ``\texttt{HG\_}''.  For example, if the name of a
    1.51 +parameter is ``\texttt{node}'', the name of the environment variable
    1.52 +representing that parameter will be ``\texttt{HG\_NODE}''.
    1.53 +
    1.54 +A boolean parameter is represented as the string ``\texttt{1}'' for
    1.55 +``true'', ``\texttt{0}'' for ``false''.  If an environment variable is
    1.56 +named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
    1.57 +contains a changeset ID represented as a hexadecimal string.  The
    1.58 +empty string is used to represent ``null changeset ID'' instead of a
    1.59 +string of zeroes.
    1.60 +
    1.61 +If a hook exits with a status of zero, it is considered to have
    1.62 +succeeded.  If it exits with a non-zero status, it is considered to
    1.63 +have failed.
    1.64 +
    1.65 +\subsection{The \hook{changegroup} hook}
    1.66 +\label{sec:hook:changegroup}
    1.67 +
    1.68 +Parameters to this hook:
    1.69 +\begin{itemize}
    1.70 +\item[\texttt{node}] The changeset ID of the first changeset in the
    1.71 +  group that was added.  All changesets between this and
    1.72 +  \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by a
    1.73 +  single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
    1.74 +\end{itemize}
    1.75 +
    1.76 +
    1.77 +\subsection{The \hook{commit} hook}
    1.78 +\label{sec:hook:commit}
    1.79 +
    1.80 +Parameters to this hook:
    1.81 +\begin{itemize}
    1.82 +\item[\texttt{node}] The changeset ID of the newly committed
    1.83 +  changeset.
    1.84 +\item[\texttt{parent1}] The changeset ID of the first parent of the
    1.85 +  newly committed changeset.
    1.86 +\item[\texttt{parent2}] The changeset ID of the second parent of the
    1.87 +  newly committed changeset.
    1.88 +\end{itemize}
    1.89  
    1.90  %%% Local Variables: 
    1.91  %%% mode: latex