Adding upstream version 2.19+dfsg.upstream/2.19+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 417 insertions, 0 deletions

diff --git a/irkerhook.xml b/irkerhook.xml
new file mode 100644
index 0000000..d6f7b51
--- /dev/null
+++ b/irkerhook.xml
@@ -0,0 +1,417 @@
+<!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
+&lt;channel&gt; -c" with &lt;channel&gt; replaced by your channel name.
+You may need to first issue the command "/msg chanserv set
+&lt;channel&gt; 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>
+
+<para>irkerhook.py will run under both python 2 and python 3, but it does
+not support mercurial repositories under python 3 yet.</para>
+
+<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>
+