IRKERHOOK(1) | Commands | IRKERHOOK(1) |
NAME¶
irkerhook - repository hook script issuing irker notificationsSYNOPSIS¶
irkerhook.py [-n] [-V] [[--variable=value...]]
[[commit-id...]]
DESCRIPTION¶
irkerhook.py 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 irkerd for forwarding to various announcement channels. The proper invocation and behavior of irkerhook.py varies depending on which VCS (version-control system) is calling it. There are four different places from which it may extract information: 1.Calls to VCS utilities.
2.In VCSes like git that support user-settable
configuration variables, variables with the prefix "irker.".
3.In other VCSes, a configuration file,
"irker.conf", in the repository's internals directory.
4.Command-line arguments of the form
--variable=value.
The following variables are general to all supported VCSes:
project
The name of the project. Should be a relatively short
identifier; will usually appear at the very beginning of a notification.
repo
The name of the repository top-level directory. If not
specified, defaults to a lowercased copy of the project name.
channels
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.
server
The host on which the notification-relaying irker daemon
is expected to reside. Defaults to "localhost".
email
If set, use email for communication rather than TCP or
UDP. The value is used as the target mail address.
tcp
If "true", use TCP for communication; if
"false", use UDP. Defaults to "false".
urlprefix
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.
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.
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 irkerhook.py is
running; the latter is expanded to the value of the "repo"
variable.
tinyifier
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.
color
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.
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".
maxchannels
Interpreted as an integer. If not zero, limits the number
of channels the hook will interpret from the "channels" variable.
This variable cannot be set through VCS configuration variables or irker.conf;
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.
cialike
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.
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 thisrefname=$1 old=$2 new=$3 irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})
irkerhook.py --refname=refs/heads/master HEAD
#!/bin/sh echo "sending IRC notification" while read old new refname; do irkerhook --refname=${refname} $(git rev-list --reverse ${old}..${new}) done
[irker] project = gpsd color = ANSI channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits
full hex ID of commit
short
first 7 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
# irkerhook variable settings for the irker project project = irker channels = irc://chat.freenode/irker,irc://chat.freenode/commits tcp = false
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
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
OPTIONS¶
irkerhook.py takes the following options: -nSuppress 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.
SEE ALSO¶
irkerd(8),AUTHOR¶
Eric S. Raymond <esr@snark.thyrsus.com>. See the project page at http://www.catb.org/~esr/irker for updates and other resources.01/17/2015 | irker |