Password support could be done by passing the credential every time.

[irker.git] / irkerhook.xml

diff --git a/irkerhook.xml b/irkerhook.xml
index b09a745902471c32fcdcdab915a593460b40c57e..d097aaaeb442d33a808073116b933483b64d56a2 100644 (file)
--- a/irkerhook.xml
+++ b/irkerhook.xml
@@ -111,8 +111,9 @@ expanded to the value of the "repo" variable.</para>
 <varlistentry>
 <term>tinyifier</term>
 <listitem>
-<para>URL template pointing to a service for compressing URLs so they 
-will take up less space in the notification line.</para>
+<para>URL template pointing to a service for compressing URLs so they
+will take up less space in the notification line. If the value of this
+variable is "None", no compression will be attempted.</para>
 </listitem>
 </varlistentry>
 <varlistentry>
@@ -217,10 +218,15 @@ may have the following values:</para>
 <refsect2 id="svn"><title>Subversion</title>
 
 <para>Under Subversion, <application>irkerhook.py</application>
-requires two arguments: "repository=" (the absolute pathname of the
-Subversion repository) and "commit=" (the numeric revision level of
-the commit).  The values must be the two arguments that Subversion
-gives its post-commit hook. Thus, a typical invocation in the post-commit
+accepts a --repository option with value (the absolute pathname of the
+Subversion repository) and a commit argument (the numeric revision level of
+the commit).  The defaults are the current working directory and HEAD,
+respectively.</para>
+
+<para>Note, however, that you <emphasis>cannot</emphasis> default the
+repository argumment inside a Subversion post-commit hook.  Instead,
+the values must be the two arguments that Subversion passes to that
+hook as arguments. Thus, a typical invocation in the post-commit
 script will look like this:</para>
 
 <programlisting>
@@ -234,8 +240,8 @@ given on the command line, and will override any settings in an
 <filename>irker.conf</filename> file.</para>
 
 <para>The default for the project variable is the basename of the
-(required) --repository argument.The default value of the "urlprefix"
-variable is "viewcvs".</para>
+repository. The default value of the "urlprefix" variable is
+"viewcvs".</para>
 
 <para>If an <filename>irker.conf</filename> file exists in the repository
 root directory (not the checkout directory but where internals such as the
@@ -258,12 +264,27 @@ that would have unhappy results.</para>
 
 <refsect2 id="hg"><title>Mercurial</title>
 
-<para>NOTE: Mercurial support is currently broken.  It is expected
-this will be fixed in the next release.</para>
-
 <para>Under Mercurial, <application>irkerhook.py</application> can be
 invoked in two ways: either as a Python hook (preferred) or as a
-script.  As for git, in both cases all variables may be set in the repo
+script.</para>
+
+<para>To call it as a Python hook, add the collowing to the 
+"commit" or "incoming" hook declaration in your Mercurial
+repository:</para>
+
+<programlisting>
+[hooks]
+       incoming.irker = python:/path/to/irkerhook.py:hg_hook
+</programlisting>
+
+<para>When called as a script, the hook accepts a --repository option
+with value (the absolute pathname of the Mercurial repository) and can
+take a commit argument (the Mercurial hash ID of the commit or a
+reference to it). The default for the repository argument is the 
+current directory. The default commit argument is '-1', designating
+the current tip commit.</para>
+
+<para>As for git, in both cases all variables may be set in the repo
 <filename>hgrc</filename> file in an [irker] section.  Command-line
 variable=value arguments are accepted but not required for script
 invocation.  No attempt is made to interpret an
@@ -276,6 +297,39 @@ exists.</para>
 
 </refsect2>
 
+<refsect2 id="filter"><title>Filtering</title>
+
+<para>It is possible to filter commits before sending them to
+<application>irkerd</application>.</para>
+
+<para>You have to specify the <option>filtercmd</option> option, which
+will be the command <application>irkerhook.py</application> will
+run. This command should accept one arguments, which is a JSON
+representation of commit and extractor metadata (including the
+channels variable). The command should emit to standard output a JSON
+representation of (possibly altered) metadata.</para>
+
+<para>Below is an example filter:</para>
+
+<programlisting>
+#!/usr/bin/env python
+# This is a trivial example of a metadata filter.
+# All it does is change the name of the commit's author.
+# 
+import sys, json
+metadata = json.loads(sys.argv[1])
+
+metadata['author'] = "The Great and Powerful Oz"
+
+print json.dumps(metadata)
+# end
+</programlisting>
+
+<para>Standard error is available to the hook for progress and
+error messages.</para>
+
+</refsect2>
+
 </refsect1>
 
 <refsect1 id='options'><title>OPTIONS</title>