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'>irkerd</refmiscinfo>
<refmiscinfo class='product'>irkerd</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>
     <arg rep='repeat'><replaceable>variable=value</replaceable></arg>
</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 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>
</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>
</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>The default value of the "project" variable is the basename
of the repository directory. The default value of the "urlprefix"
variable is "viewcvs".</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>
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>

<programlisting>
irkerhook.py repository=$1 commit=$2
</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
(required) repository= argument.The default value of the "urlprefix"
variable is "cgit".</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>There are no Subversion-specific variables.</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/'>http://www.catb.org/~esr/irker</ulink>
for updates and other resources.</para>
</refsect1>
</refentry>