SYNOPSIS

irkerhook.py [-n] [-V] [[--variable=value...]] [[commit-id...]]

DESCRIPTION

git

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 git rev-list 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

refname=$1
old=$2
new=$3
irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})

except that you'll need an absolute path for irkerhook.py.

For testing purposes and backward compatibility, if you invoke irkerhook.py with no arguments (as in a post-commit hook) it will behave as though it had been called like this:

irkerhook.py --refname=refs/heads/master HEAD

However, this will not give the right result when you push to a non-default branch of a bare repo.

A typical way to install this hook is actually in the post-receive hook, because it gets all the necessary details and will not abort the push on failure. Use the following script:

#!/bin/sh
echo "sending IRC notification"
while read old new refname; do
    irkerhook --refname=${refname} $(git rev-list --reverse ${old}..${new})
done

For convenience, this is implemented by the irkerhook-git helper script. This script will complain about some common configuration isssues. For simplicity, irkerhook-git does not support all the options of irkerhook.py, and is thus not suitable for all applications.

Preferences may be set in the repo config file in an [irker] section. Here is an example of what that can look like:

[irker]
    project = gpsd
    color = ANSI
    channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits

You should not set the "repository" variable (an equivalent will be computed). No attempt is made to interpret an irker.conf file.

The default value of the "project" variable is the basename of the repository directory. The default value of the "urlprefix" variable is "cgit".

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

raw

full hex ID of commit

short

first 12 chars of hex ID

describe

describe relative to last tag, falling back to short

The default is 'describe'.

Subversion

Under Subversion, irkerhook.py 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.

Note, however, that you cannot 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:

REPO=$1
REV=$2
irkerhook.py --repository=$REPO $REV

Other --variable=value settings may also be given on the command line, and will override any settings in an irker.conf file.

The default for the project variable is the basename of the repository. The default value of the "urlprefix" variable is "viewcvs".

If an irker.conf 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:

# irkerhook variable settings for the irker project
project = irker
channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
tcp = false

Don't set the "repository" or "commit" variables in this file; that would have unhappy results.

There are no Subversion-specific variables.

Mercurial

Under Mercurial, irkerhook.py can be invoked in two ways: either as a Python hook (preferred) or as a script.

To call it as a Python hook, add the collowing to the "commit" or "incoming" hook declaration in your Mercurial repository:

[hooks]
        incoming.irker = python:/path/to/irkerhook.py:hg_hook

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.

As for git, in both cases all variables may be set in the repo hgrc 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 irker.conf file.

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.

Filtering

It is possible to filter commits before sending them to irkerd.

You have to specify the filtercmd option, which will be the command irkerhook.py 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.

Below is an example filter:

#!/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

Standard error is available to the hook for progress and error messages.

OPTIONS

irkerhook.py takes the following options:

-n

Suppress transmission to a daemon. Instead, dump the generated JSON request to standard output. Useful for debugging.

-V

Write the program version to stdout and terminate.

AUTHOR

Eric S. Raymond <[email protected]>. See the project page at m[blue]http://www.catb.org/~esr/irkerm[] for updates and other resources.