<command>irkerhook.py</command>
<arg>-n</arg>
<arg>-V</arg>
- <arg rep='repeat'><replaceable>variable=value</replaceable></arg>
+ <group><arg rep='repeat'><replaceable>--variable=value</replaceable></arg></group>
+ <group><arg rep='repeat'><replaceable>commit-id</replaceable></arg></group>
</cmdsynopsis>
</refsynopsisdiv>
<listitem><para>In other VCSes, a configuration file, "irker.conf", in the
repository's internals directory.</para></listitem>
<listitem><para>Command-line arguments of the form
-variable=value.</para></listitem>
+--variable=value.</para></listitem>
</orderedlist>
<para>The following variables are general to all supported VCSes:</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>
+<term>color</term>
+<listitem>
+<para>If "mIRC", highlight notification fields with mIRC color codes.
+If "ANSI", highlight notification fields with ANSI color escape sequences.
+Defaults to "none" (no colors). Note: if you turn this on and
+notifications stop appearing on your channel, you need to turn off
+IRC's color filter on that channel. To do this you will need op
+privileges; issue the command "/mode #irker -c". You may need to
+first issue the command "/msg chanserv set #irker MLOCK
++nt-slk".</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>maxchannels</term>
+<listitem>
+<para>Interpreted as an integer. If not zero, limits the number of
+channels the hook will interpret from the "channels" variable.</para>
+
+<para>This variable cannot be set through VCS configuration variables
+or <filename>irker.conf</filename>; it can only be set with a command-line
+argument. Thus, on a forge site in which repository owners are not
+allowed to modify their post-commit scripts, a site administrator can set it
+to prevent shotgun spamming by malicious project owners. Setting it to
+a value less than 2, however, would probably be unwise.</para>
</listitem>
</varlistentry>
</variablelist>
<refsect2 id="git"><title>git</title>
-<para>Under git, <application>irkerhook.py</application> does not
-require any arguments. All variables may be set in the repo
-<filename>config</filename> file in an [irker] section. Command-line
-variable=value arguments are accepted but not required. No attempt is
-made to interpret an <filename>irker.conf</filename> file. You should
-not set the "repository" variable (an equivalent will be
-computed).</para>
+<para>Under git, the normal way to invoke this hook (from within the
+update hook) passes with a refname followed by a list of commits. Because
+<command>git rev-list</command> normally lists from most recent to oldest,
+you'll want to use --reverse to make notifications be omitted in chronological
+order. In a normal update script, the invocation should look like this</para>
+
+<programlisting>
+refname=$1
+old=$2
+new=$3
+irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})
+</programlisting>
+
+<para>except that you'll need an absolute path for irkerhook.py.</para>
+
+<para>For testing purposes and backward compatibility, if you invoke
+<application>irkerhook.py</application> with no arguments (as in a
+post-commit hook) it will behave as though it had been called like
+this:</para>
+
+<programlisting>
+irkerhook.py --refname=refs/heads/master HEAD
+</programlisting>
+
+<para>However, this will not give the right result when you push to
+a non-default branch of a bare repo.</para>
+
+<para>Preferences may be set in the repo <filename>config</filename>
+file in an [irker] section. Here is an example of what that can look
+like:</para>
+
+<programlisting>
+[irker]
+ project = gpsd
+ color = ANSI
+ channels = {irc://chat.freenode.net/gpsd, irc://chat.freenode.net/commits}
+</programlisting>
+
+<para> You should not set the "repository" variable (an equivalent
+will be computed). No attempt is made to interpret an
+<filename>irker.conf</filename> file.</para>
<para>The default value of the "project" variable is the basename
of the repository directory. The default value of the "urlprefix"
<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>
-irkerhook.py repository=$1 commit=$2
+REPO=$1
+REV=$2
+irkerhook.py --repository=$REPO $REV
</programlisting>
-<para>Other variable=value settings may also be
+<para>Other --variable=value settings may also be
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
tcp = false
</programlisting>
-<para>Don't the "repository" or "commit" variables in this file;
+<para>Don't set the "repository" or "commit" variables in this file;
that would have unhappy results.</para>
<para>There are no Subversion-specific variables.</para>
</refsect2>
+<refsect2 id="hg"><title>Mercurial</title>
+
+<para>Under Mercurial, <application>irkerhook.py</application> can be
+invoked in two ways: either as a Python hook (preferred) or as a
+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
+<filename>irker.conf</filename> file.</para>
+
+<para>The default value of the "project" variable is the basename
+of the repository directory. The default value of the "urlprefix"
+variable is the value of the "web.baseurl" config value, if it
+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>
<refsect1 id='authors'><title>AUTHOR</title>
<para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>. See the
project page at <ulink
-url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/irker</ulink>
+url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
for updates and other resources.</para>
</refsect1>
</refentry>
projects / irker.git / blobdiff