hgbook
diff en/hook.tex @ 37:9fd0c59b009a
Add to hook chapter.
Document each macro in 99defs.tex.
Document each macro in 99defs.tex.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Jul 17 00:01:01 2006 -0700 (2006-07-17) |
parents | c0979ed1eabd |
children | b49a7dd4e564 |
line diff
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: