<refentrytitle>irkerhook</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
-<refmiscinfo class='source'>irkerd</refmiscinfo>
-<refmiscinfo class='product'>irkerd</refmiscinfo>
+<refmiscinfo class='source'>irker</refmiscinfo>
+<refmiscinfo class='product'>irker</refmiscinfo>
<refmiscinfo class='manual'>Commands</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<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>
<term>channels</term>
<listitem>
<para>An IRC channel URL, or comma-separated list of same, identifying
-channels to which notofications 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>
+channels to which notifications are to be sent. If not specified, the
+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.
Defaults to "false".</para>
</listitem>
</varlistentry>
+<varlistentry>
+<term>urlprefix</term>
+<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
+work if you have a typical gitweb/cgit setup.</para>
+
+<para>If the value of this variable is "None", generation of the URL
+field in commit notifications will be suppressed. Other magic values
+are "cgit", "gitweb", and "viewcvs", which expand to URL templates
+that will usually work with those systems.</para>
+
+<para>The magic cookies "%(host)s" and %(repo)s" may occur in this
+URL. The former is expanded to the FQDN of the host on which
+<application>irkerhook.py</application> is running; the latter is
+expanded to the value of the "repo" variable.</para>
+</listitem>
+</varlistentry>
+<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. 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). ANSI codes are supported
+in Chatzilla. irssi, ircle, and BitchX, but not in mIRC, XChat, KVirc or
+Konversation.</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 chnnel name.
+You may need to first issue the command "/msg chanserv set
+<channel> 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>
+<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. All variables may be set in the repo
-<filename>config</filename> file, and are distinguished with
-the application prefix "irker.". Command-line variable=value
-arguments are accepted but not required. No attempt is made
-to interpret an <filename>irker.conf</filename> file.</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.</para>
+of the repository directory. The default value of the "urlprefix"
+variable is "cgit".</para>
<para>There is one git-specific variable, "revformat", controlling
the format of the commit identifier in a notification. It
<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.</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 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