Documentation improvements.

[irker.git] / irkerhook.xml

<!DOCTYPE refentry PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd">
<refentry id='irkerhook.1'>
<refmeta>
<refentrytitle>irkerhook</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
<refmiscinfo class='source'>irker</refmiscinfo>
<refmiscinfo class='product'>irker</refmiscinfo>
<refmiscinfo class='manual'>Commands</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>irkerhook</refname>
<refpurpose>repository hook script issuing irker notifications</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>irkerhook.py</command>
     <arg>-n</arg>
     <arg>-V</arg>
     <group><arg rep='repeat'><replaceable>--variable=value</replaceable></arg></group>
     <group><arg rep='repeat'><replaceable>commit-id</replaceable></arg></group>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><application>irkerhook.py</application> is a Python script intended 
to be called from the post-commit hook of a version-control repository. Its
job is to collect information about the commit that fired the hook (and
possibly preferences set by the repository owner) and ship that information
to an instance of <application>irkerd</application> for forwarding to
various announcement channels.</para>

<para>The proper invocation and behavior of 
<application>irkerhook.py</application> varies depending on which
VCS (version-control system) is calling it.  There are four different places
from which it may extract information:</para>

<orderedlist>
<listitem><para>Calls to VCS utilities.</para></listitem>
<listitem><para>In VCSes like git that support user-settable configuration
variables, variables with the prefix "irker.".</para></listitem>
<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>
</orderedlist>

<para>The following variables are general to all supported VCSes:</para>

<variablelist>
<varlistentry>
<term>project</term>
<listitem>
<para>The name of the project.  Should be a relatively short identifier;
will usually appear at the very beginning of a notification.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>repo</term>
<listitem>
<para>The name of the repository top-level directory.  If not
specified, defaults to a lowercased copy of the project name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>channels</term>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>server</term>
<listitem>
<para>The host on which the notification-relaying irker daemon is expected
to reside. Defaults to "localhost".</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). 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, 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"
variable is "cgit".</para>

<para>There is one git-specific variable, "revformat", controlling
the format of the commit identifier in a notification. It
may have the following values:</para>

<variablelist>
<varlistentry>
<term>raw</term>
<listitem><para>full hex ID of commit</para></listitem>
</varlistentry>
<varlistentry>
<term>short</term>
<listitem><para>first 12 chars of hex ID</para></listitem>
</varlistentry>
<varlistentry>
<term>describe</term>
<listitem><para>describe relative to last tag, falling back to short</para></listitem>
</varlistentry>
</variablelist>

<para>The default is 'describe'.</para>
</refsect2>

<refsect2 id="svn"><title>Subversion</title>

<para>Under Subversion, <application>irkerhook.py</application>
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>
REPO=$1
REV=$2
irkerhook.py --repository=$REPO $REV
</programlisting>

<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
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
"format" file live) the hook will interpret variable settings from it.  Here
is an example of what such a file might look like:</para>

<programlisting>
# irkerhook variable settings for the irker project
project = irker
channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
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>

<para><application>irkerhook.py</application> takes the following
options:</para>

<variablelist>
<varlistentry>
<term>-n</term>
<listitem><para>Suppress transmission to a daemon. Instead, dump the
generated JSON request to standard output. Useful for
debugging.</para></listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem><para>Write the program version to stdout and
terminate.</para></listitem>
</varlistentry>
</variablelist>

</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/irker'>http://www.catb.org/~esr/irker</ulink>
for updates and other resources.</para>
</refsect1>
</refentry>