<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>
<listitem>
<para>An IRC channel URL, or comma-separated list of same, identifying
channels to which notifications are to be sent. If not specified, the
-defaults channel list id the freenode #commits channel plus the freenode
-channel named by the project variable.</para>
+default is the freenode #commits channel.</para>
</listitem>
</varlistentry>
<varlistentry>
</listitem>
</varlistentry>
<varlistentry>
+<term>email</term>
+<listitem>
+<para>If set, use email for communication rather than TCP or UDP.
+The value is used as the target mail address.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
<term>tcp</term>
<listitem>
<para>If "true", use TCP for communication; if "false", use UDP.
<listitem>
<para>Changeset URL prefix for your repo. When the commit ID is appended
to this, it should point at a CGI that will display the commit
-through cgit,gitweb or something similar. The defaults will probably
+through cgit, gitweb or something similar. The defaults will probably
work if you have a typical gitweb/cgit setup.</para>
<para>If the value of this variable is "None", generation of the URL
<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>
+If "ANSI", highlight notification fields with ANSI color escape
+sequences. Defaults to "none" (no colors). ANSI codes are supported
+in Chatzilla, irssi, ircle, and BitchX; mIRC codes only are recognized
+in mIRC, XChat, KVirc, Konversation, or weechat.</para>
+
+<para>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
+<channel> -c" with <channel> replaced by your channel name.
+You may need to first issue the command "/msg chanserv set
+<channel> MLOCK +nt-slk".</para>
</listitem>
</varlistentry>
<varlistentry>
a value less than 2, however, would probably be unwise.</para>
</listitem>
</varlistentry>
+<varlistentry>
+<term>cialike</term>
+<listitem>
+<para>If not empty and not "None", this emulates the old CIA behavior
+of dropping long lists of files in favor of a summary of the form (N
+files in M directories). The value must be numeric giving a threshold
+value for the length of the file list in characters.</para>
+</listitem>
+</varlistentry>
</variablelist>
<refsect2 id="git"><title>git</title>
-<para>Under git, <application>irkerhook.py</application> does not
-require any arguments. 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>
+<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>A typical way to install this hook is actually in the
+<filename>post-receive</filename> hook, because it gets all the
+necessary details and will not abort the push on failure. Use the
+following script:</para>
+
+<programlisting>
+#!/bin/sh
+
+echo "sending IRC notification"
+while read old new refname; do
+ irkerhook --refname=${refname} $(git rev-list --reverse ${old}..${new})
+done
+</programlisting>
+
+<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}
+ channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits
</programlisting>
-<para>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> 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
-script will look like this:</para>
+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 argument inside a Subversion post-commit hook; this is
+because of a limitation of Subversion, which is that getting the
+current directory is not reliable inside these hooks. 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>
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>irkerd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+</para>
+</refsect1>
+
<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