diff options
Diffstat (limited to 'irkerhook.xml')
| -rw-r--r-- | irkerhook.xml | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/irkerhook.xml b/irkerhook.xml new file mode 100644 index 0000000..2f068d2 --- /dev/null +++ b/irkerhook.xml @@ -0,0 +1,414 @@ +<!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 +default is the freenode #commits channel.</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>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; 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> +<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" (the default), 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> +<varlistentry> +<term>template</term> +<listitem> +<para>Set the template used to generate notification messages. Only +available in VCses with config variables; presently this means git or +hg. All basic commit and extractor fields, including color switches, +are available as %() substitutions.</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 it 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 +</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 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> +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='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/irker'>http://www.catb.org/~esr/irker</ulink> +for updates and other resources.</para> +</refsect1> +</refentry> + |