hgbook
diff en/hook.tex @ 44:012df94a02fe
Start hook examples. First is for trailing whitespace.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun Jul 23 23:25:52 2006 -0700 (2006-07-23) |
parents | d1a3394f8bcf |
children | 18210d46491f |
line diff
1.1 --- a/en/hook.tex Thu Jul 20 19:42:50 2006 -0700 1.2 +++ b/en/hook.tex Sun Jul 23 23:25:52 2006 -0700 1.3 @@ -413,6 +413,48 @@ 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{Some hook examples} 1.8 + 1.9 +\subsection{Enforcing coding guidelines in your own repository} 1.10 + 1.11 +An interesting use of a commit-related hook is to help you to write 1.12 +cleaner code. A simple example of ``cleaner code'' is the dictum that 1.13 +a change should not add any new lines of text that contain ``trailing 1.14 +whitespace''. Trailing whitespace is a series of space and tab 1.15 +characters at the end of a line of text. In most cases, trailing 1.16 +whitespace is unnecessary, invisible noise, but it is occasionally 1.17 +problematic, and people tend to prefer to get rid of it. 1.18 + 1.19 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to 1.20 +tell whether you have a trailing whitespace problem. If you use the 1.21 +\hook{precommit} hook, the hook will not know which files you are 1.22 +committing, so it will have to check every modified file in the 1.23 +repository for trailing white space. If you want to commit a change 1.24 +to just the file \filename{foo}, but the file \filename{bar} contains 1.25 +trailing whitespace, doing a check in the \hook{precommit} hook will 1.26 +prevent you from committing \filename{foo} due to the problem with 1.27 +\filename{bar}. This doesn't seem right. 1.28 + 1.29 +Should you choose the \hook{pretxncommit} hook, the check won't occur 1.30 +until just before the transaction for the commit completes. This will 1.31 +allow you to check for problems only the exact files that are being 1.32 +committed. However, if you entered the commit message interactively 1.33 +and the hook fails, the transaction will roll back; you'll have to 1.34 +re-enter the commit message after you fix the trailing whitespace and 1.35 +run \hgcmd{commit} again. 1.36 + 1.37 +\begin{figure}[ht] 1.38 + \interaction{hook.ws.simple} 1.39 + \caption{A simple hook that checks for trailing whitespace} 1.40 + \label{ex:hook:ws.simple} 1.41 +\end{figure} 1.42 + 1.43 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit} 1.44 +hook that checks for trailing whitespace. This hook is short, but not 1.45 +very helpful. It exits with an error status if a change adds a line 1.46 +with trailing whitespace to any file, but does not print any 1.47 +information that might help us to identify the offending file or line. 1.48 + 1.49 \section{Hook reference} 1.50 \label{sec:hook:ref} 1.51