1 <!DOCTYPE refentry PUBLIC
2 "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "docbook/docbookx.dtd">
4 <refentry id='irkerhook.1'>
6 <refentrytitle>irkerhook</refentrytitle>
7 <manvolnum>1</manvolnum>
8 <refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
9 <refmiscinfo class='source'>irker</refmiscinfo>
10 <refmiscinfo class='product'>irker</refmiscinfo>
11 <refmiscinfo class='manual'>Commands</refmiscinfo>
13 <refnamediv id='name'>
14 <refname>irkerhook</refname>
15 <refpurpose>repository hook script issuing irker notifications</refpurpose>
17 <refsynopsisdiv id='synopsis'>
20 <command>irkerhook.py</command>
23 <group><arg rep='repeat'><replaceable>--variable=value</replaceable></arg></group>
24 <group><arg rep='repeat'><replaceable>commit-id</replaceable></arg></group>
28 <refsect1 id='description'><title>DESCRIPTION</title>
30 <para><application>irkerhook.py</application> is a Python script intended
31 to be called from the post-commit hook of a version-control repository. Its
32 job is to collect information about the commit that fired the hook (and
33 possibly preferences set by the repository owner) and ship that information
34 to an instance of <application>irkerd</application> for forwarding to
35 various announcement channels.</para>
37 <para>The proper invocation and behavior of
38 <application>irkerhook.py</application> varies depending on which
39 VCS (version-control system) is calling it. There are four different places
40 from which it may extract information:</para>
43 <listitem><para>Calls to VCS utilities.</para></listitem>
44 <listitem><para>In VCSes like git that support user-settable configuration
45 variables, variables with the prefix "irker.".</para></listitem>
46 <listitem><para>In other VCSes, a configuration file, "irker.conf", in the
47 repository's internals directory.</para></listitem>
48 <listitem><para>Command-line arguments of the form
49 --variable=value.</para></listitem>
52 <para>The following variables are general to all supported VCSes:</para>
58 <para>The name of the project. Should be a relatively short identifier;
59 will usually appear at the very beginning of a notification.</para>
65 <para>The name of the repository top-level directory. If not
66 specified, defaults to a lowercased copy of the project name.</para>
72 <para>An IRC channel URL, or comma-separated list of same, identifying
73 channels to which notifications are to be sent. If not specified, the
74 defaults channel list id the freenode #commits channel plus the freenode
75 channel named by the project variable.</para>
81 <para>The host on which the notification-relaying irker daemon is expected
82 to reside. Defaults to "localhost".</para>
88 <para>If "true", use TCP for communication; if "false", use UDP.
89 Defaults to "false".</para>
93 <term>urlprefix</term>
95 <para>Changeset URL prefix for your repo. When the commit ID is appended
96 to this, it should point at a CGI that will display the commit
97 through cgit,gitweb or something similar. The defaults will probably
98 work if you have a typical gitweb/cgit setup.</para>
100 <para>If the value of this variable is "None", generation of the URL
101 field in commit notifications will be suppressed. Other magic values
102 are "cgit", "gitweb", and "viewcvs", which expand to URL templates
103 that will usually work with those systems.</para>
105 <para>The magic cookies "%(host)s" and %(repo)s" may occur in this
106 URL. The former is expanded to the FQDN of the host on which
107 <application>irkerhook.py</application> is running; the latter is
108 expanded to the value of the "repo" variable.</para>
112 <term>tinyifier</term>
114 <para>URL template pointing to a service for compressing URLs so they
115 will take up less space in the notification line. If the value of this
116 variable is "None", no compression will be attempted.</para>
122 <para>If "mIRC", highlight notification fields with mIRC color codes.
123 If "ANSI", highlight notification fields with ANSI color escape
124 sequences. Defaults to "none" (no colors). ANSI codes are supported
125 in Chatzilla. irssi, ircle, and BitchX, but not in mIRC, XChat, KVirc or
128 <para>Note: if you turn this on and notifications stop appearing on
129 your channel, you need to turn off IRC's color filter on that channel.
130 To do this you will need op privileges; issue the command "/mode
131 <channel> -c" with <channel> replaced by your chnnel name.
132 You may need to first issue the command "/msg chanserv set
133 <channel> MLOCK +nt-slk".</para>
137 <term>maxchannels</term>
139 <para>Interpreted as an integer. If not zero, limits the number of
140 channels the hook will interpret from the "channels" variable.</para>
142 <para>This variable cannot be set through VCS configuration variables
143 or <filename>irker.conf</filename>; it can only be set with a command-line
144 argument. Thus, on a forge site in which repository owners are not
145 allowed to modify their post-commit scripts, a site administrator can set it
146 to prevent shotgun spamming by malicious project owners. Setting it to
147 a value less than 2, however, would probably be unwise.</para>
153 <para>If not empty and not "None", this emulates the old CIA behavior
154 of dropping long lists of files in favor of a summary of the form (N
155 files in M directories). The value must be numeric giving a threshold
156 value for the length of the file list in characters.</para>
161 <refsect2 id="git"><title>git</title>
163 <para>Under git, the normal way to invoke this hook (from within the
164 update hook) passes with a refname followed by a list of commits. Because
165 <command>git rev-list</command> normally lists from most recent to oldest,
166 you'll want to use --reverse to make notifications be omitted in chronological
167 order. In a normal update script, the invocation should look like this</para>
173 irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})
176 <para>except that you'll need an absolute path for irkerhook.py.</para>
178 <para>For testing purposes and backward compatibility, if you invoke
179 <application>irkerhook.py</application> with no arguments (as in a
180 post-commit hook) it will behave as though it had been called like
184 irkerhook.py --refname=refs/heads/master HEAD
187 <para>However, this will not give the right result when you push to
188 a non-default branch of a bare repo.</para>
190 <para>Preferences may be set in the repo <filename>config</filename>
191 file in an [irker] section. Here is an example of what that can look
198 channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits
201 <para> You should not set the "repository" variable (an equivalent
202 will be computed). No attempt is made to interpret an
203 <filename>irker.conf</filename> file.</para>
205 <para>The default value of the "project" variable is the basename
206 of the repository directory. The default value of the "urlprefix"
207 variable is "cgit".</para>
209 <para>There is one git-specific variable, "revformat", controlling
210 the format of the commit identifier in a notification. It
211 may have the following values:</para>
216 <listitem><para>full hex ID of commit</para></listitem>
220 <listitem><para>first 12 chars of hex ID</para></listitem>
223 <term>describe</term>
224 <listitem><para>describe relative to last tag, falling back to short</para></listitem>
228 <para>The default is 'describe'.</para>
231 <refsect2 id="svn"><title>Subversion</title>
233 <para>Under Subversion, <application>irkerhook.py</application>
234 accepts a --repository option with value (the absolute pathname of the
235 Subversion repository) and a commit argument (the numeric revision level of
236 the commit). The defaults are the current working directory and HEAD,
239 <para>Note, however, that you <emphasis>cannot</emphasis> default the
240 repository argument inside a Subversion post-commit hook; this is
241 because of a limitation of Subversion, which is that getting the
242 current directory is not reliable inside these hooks. Instead, the
243 values must be the two arguments that Subversion passes to that hook
244 as arguments. Thus, a typical invocation in the post-commit script
245 will look like this:</para>
250 irkerhook.py --repository=$REPO $REV
253 <para>Other --variable=value settings may also be
254 given on the command line, and will override any settings in an
255 <filename>irker.conf</filename> file.</para>
257 <para>The default for the project variable is the basename of the
258 repository. The default value of the "urlprefix" variable is
261 <para>If an <filename>irker.conf</filename> file exists in the repository
262 root directory (not the checkout directory but where internals such as the
263 "format" file live) the hook will interpret variable settings from it. Here
264 is an example of what such a file might look like:</para>
267 # irkerhook variable settings for the irker project
269 channels = irc://chat.freenode/irker,irc://chat.freenode/commits
273 <para>Don't set the "repository" or "commit" variables in this file;
274 that would have unhappy results.</para>
276 <para>There are no Subversion-specific variables.</para>
280 <refsect2 id="hg"><title>Mercurial</title>
282 <para>Under Mercurial, <application>irkerhook.py</application> can be
283 invoked in two ways: either as a Python hook (preferred) or as a
286 <para>To call it as a Python hook, add the collowing to the
287 "commit" or "incoming" hook declaration in your Mercurial
292 incoming.irker = python:/path/to/irkerhook.py:hg_hook
295 <para>When called as a script, the hook accepts a --repository option
296 with value (the absolute pathname of the Mercurial repository) and can
297 take a commit argument (the Mercurial hash ID of the commit or a
298 reference to it). The default for the repository argument is the
299 current directory. The default commit argument is '-1', designating
300 the current tip commit.</para>
302 <para>As for git, in both cases all variables may be set in the repo
303 <filename>hgrc</filename> file in an [irker] section. Command-line
304 variable=value arguments are accepted but not required for script
305 invocation. No attempt is made to interpret an
306 <filename>irker.conf</filename> file.</para>
308 <para>The default value of the "project" variable is the basename
309 of the repository directory. The default value of the "urlprefix"
310 variable is the value of the "web.baseurl" config value, if it
315 <refsect2 id="filter"><title>Filtering</title>
317 <para>It is possible to filter commits before sending them to
318 <application>irkerd</application>.</para>
320 <para>You have to specify the <option>filtercmd</option> option, which
321 will be the command <application>irkerhook.py</application> will
322 run. This command should accept one arguments, which is a JSON
323 representation of commit and extractor metadata (including the
324 channels variable). The command should emit to standard output a JSON
325 representation of (possibly altered) metadata.</para>
327 <para>Below is an example filter:</para>
330 #!/usr/bin/env python
331 # This is a trivial example of a metadata filter.
332 # All it does is change the name of the commit's author.
335 metadata = json.loads(sys.argv[1])
337 metadata['author'] = "The Great and Powerful Oz"
339 print json.dumps(metadata)
343 <para>Standard error is available to the hook for progress and
344 error messages.</para>
350 <refsect1 id='options'><title>OPTIONS</title>
352 <para><application>irkerhook.py</application> takes the following
358 <listitem><para>Suppress transmission to a daemon. Instead, dump the
359 generated JSON request to standard output. Useful for
360 debugging.</para></listitem>
364 <listitem><para>Write the program version to stdout and
365 terminate.</para></listitem>
371 <refsect1 id='see_also'><title>SEE ALSO</title>
373 <citerefentry><refentrytitle>irkerd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
377 <refsect1 id='authors'><title>AUTHOR</title>
378 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>. See the
379 project page at <ulink
380 url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
381 for updates and other resources.</para>