hgbook
changeset 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 | 5cee64874312 |
children | b49a7dd4e564 |
files | en/99defs.tex en/hook.tex |
line diff
1.1 --- a/en/99defs.tex Mon Jul 17 00:00:12 2006 -0700 1.2 +++ b/en/99defs.tex Mon Jul 17 00:01:01 2006 -0700 1.3 @@ -1,34 +1,92 @@ 1.4 +% Bug ID. 1.5 \newcommand{\bug}[1]{\index{Mercurial issue!no.~#1}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial issue no.~#1}} 1.6 + 1.7 +% File name in the user's home directory. 1.8 \newcommand{\tildefile}[1]{\texttt{\~{}/#1}} 1.9 + 1.10 +% File name. 1.11 \newcommand{\filename}[1]{\texttt{#1}} 1.12 + 1.13 +% Directory name. 1.14 \newcommand{\dirname}[1]{\texttt{#1}} 1.15 + 1.16 +% File name, with index entry. 1.17 +% The ``s'' prefix comes from ``special''. 1.18 \newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}} 1.19 + 1.20 +% Directory name, with index entry. 1.21 \newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}} 1.22 + 1.23 +% Mercurial extension. 1.24 \newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}} 1.25 + 1.26 +% Mercurial command. 1.27 \newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''} 1.28 + 1.29 +% Mercurial command, with arguments. 1.30 +\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 1.31 + 1.32 +% Shell/system command. 1.33 \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}} 1.34 + 1.35 +% Shell/system command, with arguments. 1.36 \newcommand{\cmdargs}[2]{\index{\texttt{#1} command}``\texttt{#1 #2}''} 1.37 -\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 1.38 + 1.39 +% Mercurial command option. 1.40 \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 1.41 + 1.42 +% Mercurial global option. 1.43 +\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}} 1.44 + 1.45 +% Shell/system command option. 1.46 \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 1.47 + 1.48 +% Command option. 1.49 \newcommand{\option}[1]{\texttt{#1}} 1.50 + 1.51 +% Software package. 1.52 \newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}} 1.53 + 1.54 +% Section name from a hgrc file. 1.55 \newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}} 1.56 + 1.57 +% Named item in a hgrc file section. 1.58 \newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1} 1.59 section!\texttt{#2} entry}\texttt{#1.#2}} 1.60 + 1.61 +% hgrc file. 1.62 \newcommand{\hgrc}{\index{\texttt{hgrc} file}\texttt{hgrc}} 1.63 + 1.64 +% Hook name. 1.65 \newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}} 1.66 + 1.67 +% Environment variable. 1.68 \newcommand{\envar}[1]{\index{\texttt{#1} environment 1.69 variable}\index{environment variables!\texttt{#1}}\texttt{#1}} 1.70 1.71 +% Python module. 1.72 +\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}} 1.73 + 1.74 +% Python class in a module. 1.75 +\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2} 1.76 + class}\texttt{#1.#2}} 1.77 + 1.78 +% Note: blah blah. 1.79 \newsavebox{\notebox} 1.80 \newenvironment{note}% 1.81 {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}% 1.82 {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}} 1.83 1.84 +% Code sample, eating 4 characters of leading space. 1.85 \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}} 1.86 + 1.87 +% Code sample, eating 2 characters of leading space. 1.88 +\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}} 1.89 + 1.90 +% Interaction from the examples directory. 1.91 \newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.out}} 1.92 1.93 +% Graphics inclusion. 1.94 \ifpdf 1.95 \newcommand{\grafix}[1]{\includegraphics{#1}} 1.96 \else
2.1 --- a/en/hook.tex Mon Jul 17 00:00:12 2006 -0700 2.2 +++ b/en/hook.tex Mon Jul 17 00:01:01 2006 -0700 2.3 @@ -95,11 +95,18 @@ 2.4 comment contains a bug ID. If it does, the commit can complete. If 2.5 not, the commit is rolled back. 2.6 2.7 -\section{Choosing how to write a hook} 2.8 -\label{sec:hook:impl} 2.9 +\section{Writing your own hooks} 2.10 + 2.11 +When you are writing a hook, you might find it useful to run Mercurial 2.12 +either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config 2.13 +item set to ``true''. When you do so, Mercurial will print a message 2.14 +before it calls each hook. 2.15 + 2.16 +\subsection{Choosing how your hook should run} 2.17 +\label{sec:hook:lang} 2.18 2.19 You can write a hook either as a normal program---typically a shell 2.20 -script---or as a Python function that is called within the Mercurial 2.21 +script---or as a Python function that is executed within the Mercurial 2.22 process. 2.23 2.24 Writing a hook as an external program has the advantage that it 2.25 @@ -119,7 +126,7 @@ 2.26 performance (probably the majority of hooks), a shell script is 2.27 perfectly fine. 2.28 2.29 -\section{Hook parameters} 2.30 +\subsection{Hook parameters} 2.31 \label{sec:hook:param} 2.32 2.33 Mercurial calls each hook with a set of well-defined parameters. In 2.34 @@ -128,9 +135,82 @@ 2.35 environment variable. 2.36 2.37 Whether your hook is written in Python or as a shell script, the 2.38 -parameter names and values will be the same. A boolean parameter will 2.39 -be represented as a boolean value in Python, but as the number 1 (for 2.40 -``true'') or 0 (for ``false'') 2.41 +hook-specific parameter names and values will be the same. A boolean 2.42 +parameter will be represented as a boolean value in Python, but as the 2.43 +number 1 (for ``true'') or 0 (for ``false'') as an environment 2.44 +variable for an external hook. If a hook parameter is named 2.45 +\texttt{foo}, the keyword argument for a Python hook will also be 2.46 +named \texttt{foo} Python, while the environment variable for an 2.47 +external hook will be named \texttt{HG\_FOO}. 2.48 + 2.49 +\subsection{Hook return values and activity control} 2.50 + 2.51 +A hook that executes successfully must exit with a status of zero if 2.52 +external, or return boolean ``false'' if in-process. Failure is 2.53 +indicated with a non-zero exit status from an external hook, or an 2.54 +in-process hook returning boolean ``true''. If an in-process hook 2.55 +raises an exception, the hook is considered to have failed. 2.56 + 2.57 +For a hook that controls whether an activity can proceed, zero/false 2.58 +means ``allow'', while non-zero/true/exception means ``deny''. 2.59 + 2.60 +\subsection{Writing an external hook} 2.61 + 2.62 +When you define an external hook in your \hgrc\ and the hook is run, 2.63 +its value is passed to your shell, which interprets it. This means 2.64 +that you can use normal shell constructs in the body of the hook. 2.65 + 2.66 +An executable hook is always run with its current directory set to a 2.67 +repository's root directory. 2.68 + 2.69 +Each hook parameter is passed in as an environment variable; the name 2.70 +is upper-cased, and prefixed with the string ``\texttt{HG\_}''. 2.71 + 2.72 +With the exception of hook parameters, Mercurial does not set or 2.73 +modify any environment variables when running a hook. This is useful 2.74 +to remember if you are writing a site-wide hook that may be run by a 2.75 +number of different users with differing environment variables set. 2.76 +In multi-user situations, you should not rely on environment variables 2.77 +being set to the values you have in your environment when testing the 2.78 +hook. 2.79 + 2.80 +\subsection{Telling Mercurial to use an in-process hook} 2.81 + 2.82 +The \hgrc\ syntax for defining an in-process hook is slightly 2.83 +different than for an executable hook. The value of the hook must 2.84 +start with the text ``\texttt{python:}'', and continue with the 2.85 +fully-qualified name of a callable object to use as the hook's value. 2.86 + 2.87 +The module in which a hook lives is automatically imported when a hook 2.88 +is run. So long as you have the module name and \envar{PYTHONPATH} 2.89 +right, it should ``just work''. 2.90 + 2.91 +The following \hgrc\ example snippet illustrates the syntax and 2.92 +meaning of the notions we just described. 2.93 +\begin{codesample2} 2.94 + [hooks] 2.95 + commit.example = python:mymodule.submodule.myhook 2.96 +\end{codesample2} 2.97 +When Mercurial runs the \texttt{commit.example} hook, it imports 2.98 +\texttt{mymodule.submodule}, looks for the callable object named 2.99 +\texttt{myhook}, and calls it. 2.100 + 2.101 +\subsection{Writing an in-process hook} 2.102 + 2.103 +The simplest in-process hook does nothing, but illustrates the basic 2.104 +shape of the hook API: 2.105 +\begin{codesample2} 2.106 + def myhook(ui, repo, **kwargs): 2.107 + pass 2.108 +\end{codesample2} 2.109 +The first argument to a Python hook is always a 2.110 +\pymodclass{mercurial.ui}{ui} object. The second is a repository object; 2.111 +at the moment, it is always an instance of 2.112 +\pymodclass{mercurial.localrepo}{localrepository}. Following these two 2.113 +arguments are other keyword arguments. Which ones are passed in 2.114 +depends on the hook being called, but a hook can ignore arguments it 2.115 +doesn't care about by dropping them into a keyword argument dict, as 2.116 +with \texttt{**kwargs} above. 2.117 2.118 2.119 %%% Local Variables: