IRKERHOOK(1)

✨ NAME ✨

irkerhook — bestie, it's the repository hook script that goes and issues irker notifications 💅

---

🎀 SYNOPSIS 🎀

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

okay so that's the whole vibe right there: you run irkerhook.py, and you may throw some flags at it, and you may throw some variables at it, and you may throw a commit id at it. Everything past the script name is optional, and that is very much on purpose 🫶

• it's literally a hook script — the gremlin that wakes up when your repo does something and then goes off to issue irker notifications 📣
• the flags and args are all wrapped in [...] and [[...]], so none of them are required ✨
• -n and -V are chillin' there right at the top, no equals sign, no nothing 💀
• --variable=value... is giving repeatable, equals-sign-using, long-option energy 👑
• commit-id... comes last and, yeah, the ... means you can hand it more than one 🦋

ngl if you're here looking for the why and the how, the rest of this page is coming — this is only part 1, so don't go anywhere 🍓

---

✨ DESCRIPTION ✨

So bestie, irkerhook.py is a Python script and its whole thing is that it's meant to be called from the post-commit hook of a version-control repository. Like, that's its job. Its job is to collect information about the commit that fired the hook (and possibly preferences set by the repository owner, because sometimes the owner has ✨opinions✨) and then ship that info over to an instance of irkerd for forwarding to various announcement channels. Iconic relay chain behaviour, honestly.

The proper invocation and behavior of irkerhook.py varies depending on which VCS (that's version-control system, iykyk) 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; it will usually appear at the very beginning of a notification. First impression energy 🌸
• repo — the name of the repository top-level directory. If you don't specify it, it defaults to a lowercased copy of the project name.
• channels — an IRC channel URL, or a 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. Keeping things snack-sized 🍓
• 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.
• template — 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.

irkerhook.py will run under both python 2 and python 3, but it does not support mercurial repositories under python 3 yet. (One day, bestie. One day. 😭)

---

🌈 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. Yes, absolute. Don't fight it.

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. 🙈 Noted, lowkey important.

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. She's the low-maintenance version and we love her for it. 🫶

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. We're being so serious about this one. 😤

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 following 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. Vibe check, but for commits. ✨

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 python3
# 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 ✨

okay bestie, irkerhook.py only has two flags and honestly? it's giving minimalism, it's giving main-character restraint 💅 here they are:

• -n — bestie, this one is SO handy. Instead of actually sending anything off to a daemon, it just dumps the generated JSON request straight to standard output. Debugging icon behavior. Perfect for peeking at what it would have sent without bothering anybody. 🕵️♀️
• -V — prints the program version to stdout and then dips. that's it, that's the whole flag. short and sweet, no notes. 👑

---

🌈 SEE ALSO 🌈

• irkerd(8)

---

💖 AUTHOR 💖

Eric S. Raymond <esr@snark.thyrsus.com> — the legend themself, no cap. 🫶 Head over to the project page at http://www.catb.org/~esr/irker for updates and other resources, because there's always more lore to catch up on. fr fr.

---

and that's a wrap on IRKERHOOK(1), from the irker source, dated 07/21/2026 — ty for reading my little TED talk, bestie, you absolutely ate this whole manpage and i'm so proud of you 🌸💖✨ slay responsibly 💅