summaryrefslogtreecommitdiffstats
path: root/irkerhook.xml
blob: d6f7b514a778bd8901a09fe734b549928d542c6b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
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>