hgbook
changeset 39:576fef93bb49
Further content for hook chapter.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Jul 19 16:32:10 2006 -0700 (2006-07-19) |
parents | b49a7dd4e564 |
children | b2fe9964b21b |
files | en/hook.tex |
line diff
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