changeset 44:012df94a02fe

Start hook examples. First is for trailing whitespace.

--- a/en/Makefile	Sun Jul 23 12:21:36 2006 -0700
+++ b/en/Makefile	Sun Jul 23 23:25:52 2006 -0700
@@ -20,6 +20,7 @@
 	examples/run-example \
 	examples/daily.files \
 	examples/hook.simple \
+	examples/hook.ws \
 	examples/mq.qinit-help \
 	examples/mq.diff \
 	examples/mq.tarball \

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/data/check_whitespace.py	Sun Jul 23 23:25:52 2006 -0700
@@ -0,0 +1,31 @@
+#!/usr/bin/python
+
+import os, re, sys
+
+count = 0
+
+for line in os.popen('hg export tip'):
+    # remember the name of the file that this diff affects
+    m = re.match(r'^--- [^/]/([^\t])', line)
+    if m: 
+	filename = m.group(1)
+	continue
+    # remember the line number
+    m = re.match(r'^@@ -(\d+),')
+    if m:
+        linenum = m.group(1)
+        continue
+    linenum += 1
+    # check for an added line with trailing whitespace
+    m = re.match(r'^\+.*\s$', line)
+    if m:
+	print >> sys.stderr, ('%s:%d: trailing whitespace introduced' %
+                              (filename, linenum))
+        count += 1
+
+if count:
+    # save the commit message so we don't need to retype it
+    os.system('hg tip --template "{desc}" > .hg/commit.save')
+    print >> sys.stderr, 'commit message saved to .hg/commit.save'
+
+sys.exit(count)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/hook.ws	Sun Jul 23 23:25:52 2006 -0700
@@ -0,0 +1,12 @@
+cp $EXAMPLE_DIR/data/check_whitespace.py .
+
+hg init a
+cd a
+echo '[hooks]' > .hg/hgrc
+echo "pretxncommit.whitespace = hg export tip | (! grep -qP '^\\+.*[ \\t]$')" >> .hg/hgrc
+
+#$ name: simple
+
+cat .hg/hgrc
+echo 'a ' > a
+hg commit -A -m 'test with trailing whitespace'

--- a/en/hook.tex	Sun Jul 23 12:21:36 2006 -0700
+++ b/en/hook.tex	Sun Jul 23 23:25:52 2006 -0700
@@ -413,6 +413,48 @@
 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}