comparison en/hook.tex @ 44:012df94a02fe

Start hook examples. First is for trailing whitespace.

43:7ac85766db0f

arguments are other keyword arguments.  Which ones are passed in
depends on the hook being called, but a hook can ignore arguments it
doesn't care about by dropping them into a keyword argument dict, as
with \texttt{**kwargs} above.

\section{Hook reference}
\label{sec:hook:ref}

\subsection{In-process hook execution}

44:012df94a02fe

arguments are other keyword arguments.  Which ones are passed in
depends on the hook being called, but a hook can ignore arguments it
doesn't care about by dropping them into a keyword argument dict, as
with \texttt{**kwargs} above.

\section{Some hook examples}

\subsection{Enforcing coding guidelines in your own repository}

An interesting use of a commit-related hook is to help you to write
cleaner code.  A simple example of ``cleaner code'' is the dictum that
a change should not add any new lines of text that contain ``trailing
whitespace''.  Trailing whitespace is a series of space and tab
characters at the end of a line of text.  In most cases, trailing
whitespace is unnecessary, invisible noise, but it is occasionally
problematic, and people tend to prefer to get rid of it.

You can use either the \hook{precommit} or \hook{pretxncommit} hook to
tell whether you have a trailing whitespace problem.  If you use the
\hook{precommit} hook, the hook will not know which files you are
committing, so it will have to check every modified file in the
repository for trailing white space.  If you want to commit a change
to just the file \filename{foo}, but the file \filename{bar} contains
trailing whitespace, doing a check in the \hook{precommit} hook will
prevent you from committing \filename{foo} due to the problem with
\filename{bar}.  This doesn't seem right.

Should you choose the \hook{pretxncommit} hook, the check won't occur
until just before the transaction for the commit completes.  This will
allow you to check for problems only the exact files that are being
committed.  However, if you entered the commit message interactively
and the hook fails, the transaction will roll back; you'll have to
re-enter the commit message after you fix the trailing whitespace and
run \hgcmd{commit} again.

\begin{figure}[ht]
  \interaction{hook.ws.simple}
  \caption{A simple hook that checks for trailing whitespace}
  \label{ex:hook:ws.simple}
\end{figure}

Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
hook that checks for trailing whitespace.  This hook is short, but not
very helpful.  It exits with an error status if a change adds a line
with trailing whitespace to any file, but does not print any
information that might help us to identify the offending file or line.

\section{Hook reference}
\label{sec:hook:ref}

\subsection{In-process hook execution}