irkerhook.xml

   1 <!DOCTYPE refentry PUBLIC
   2    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3    "docbook/docbookx.dtd">
   4 <refentry id='irkerhook.1'>
   5 <refmeta>
   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>
  12 </refmeta>
  13 <refnamediv id='name'>
  14 <refname>irkerhook</refname>
  15 <refpurpose>repository hook script issuing irker notifications</refpurpose>
  16 </refnamediv>
  17 <refsynopsisdiv id='synopsis'>
  18
  19 <cmdsynopsis>
  20   <command>irkerhook.py</command>
  21      <arg>-n</arg>
  22      <arg>-V</arg>
  23      <arg rep='repeat'><replaceable>variable=value</replaceable></arg>
  24 </cmdsynopsis>
  25 </refsynopsisdiv>
  26
  27 <refsect1 id='description'><title>DESCRIPTION</title>
  28
  29 <para><application>irkerhook.py</application> is a Python script intended
  30 to be called from the post-commit hook of a version-control repository. Its
  31 job is to collect information about the commit that fired the hook (and
  32 possibly preferences set by the repository owner) and ship that information
  33 to an instance of <application>irkerd</application> for forwarding to
  34 various announcement channels.</para>
  35
  36 <para>The proper invocation and behavior of
  37 <application>irkerhook.py</application> varies depending on which
  38 VCS (version-control system) is calling it.  There are four different places
  39 from which it may extract information:</para>
  40
  41 <orderedlist>
  42 <listitem><para>Calls to VCS utilities.</para></listitem>
  43 <listitem><para>In VCSes like git that support user-settable configuration
  44 variables, variables with the prefix "irker.".</para></listitem>
  45 <listitem><para>In other VCSes, a configuration file, "irker.conf", in the
  46 repository's internals directory.</para></listitem>
  47 <listitem><para>Command-line arguments of the form
  48 variable=value.</para></listitem>
  49 </orderedlist>
  50
  51 <para>The following variables are general to all supported VCSes:</para>
  52
  53 <variablelist>
  54 <varlistentry>
  55 <term>project</term>
  56 <listitem>
  57 <para>The name of the project.  Should be a relatively short identifier;
  58 will usually appear at the very beginning of a notification.</para>
  59 </listitem>
  60 </varlistentry>
  61 <varlistentry>
  62 <term>repo</term>
  63 <listitem>
  64 <para>The name of the repository top-level directory.  If not
  65 specified, defaults to a lowercased copy of the project name.</para>
  66 </listitem>
  67 </varlistentry>
  68 <varlistentry>
  69 <term>channels</term>
  70 <listitem>
  71 <para>An IRC channel URL, or comma-separated list of same, identifying
  72 channels to which notifications are to be sent. If not specified, the
  73 defaults channel list id the freenode #commits channel plus the freenode
  74 channel named by the project variable.</para>
  75 </listitem>
  76 </varlistentry>
  77 <varlistentry>
  78 <term>server</term>
  79 <listitem>
  80 <para>The host on which the notification-relaying irker daemon is expected
  81 to reside. Defaults to "localhost".</para>
  82 </listitem>
  83 </varlistentry>
  84 <varlistentry>
  85 <term>tcp</term>
  86 <listitem>
  87 <para>If "true", use TCP for communication; if "false", use UDP.
  88 Defaults to "false".</para>
  89 </listitem>
  90 </varlistentry>
  91 <varlistentry>
  92 <term>urlprefix</term>
  93 <listitem>
  94 <para>Changeset URL prefix for your repo. When the commit ID is appended
  95 to this, it should point at a CGI that will display the commit
  96 through cgit,gitweb or something similar. The defaults will probably
  97 work if you have a typical gitweb/cgit setup.</para>
  98
  99 <para>If the value of this variable is "None", generation of the URL
 100 field in commit notifications will be suppressed. Other magic values
 101 are "cgit", "gitweb", and "viewcvs", which expand to URL templates
 102 that will usually work with those systems.</para>
 103
 104 <para>The magic cookies "%(host)s" and %(repo)s" may occur in this
 105 URL.  The former is expanded to the FQDN of the host on which
 106 <application>irkerhook.py</application> is running; the latter is
 107 expanded to the value of the "repo" variable.</para>
 108 </listitem>
 109 </varlistentry>
 110 <varlistentry>
 111 <term>tinyifier</term>
 112 <listitem>
 113 <para>URL template pointing to a service for compressing URLs so they
 114 will take up less space in the notification line.</para>
 115 </listitem>
 116 </varlistentry>
 117 <varlistentry>
 118 <term>color</term>
 119 <listitem>
 120 <para>If "mIRC", highlight notification fields with mIRC color codes.
 121 If "ANSI", highlight notification fields with ANSI color escape sequences.
 122 Defaults to "none" (no colors). Note: if you turn this on and
 123 notifications stop appearing on your channel, you need to turn off
 124 IRC's color filter on that channel.  To do this you will need op
 125 privileges; issue the command "/mode #irker -c".  You may need to
 126 first issue the command "/msg chanserv set #irker MLOCK
 127 +nt-slk".</para>
 128 </listitem>
 129 </varlistentry>
 130 <varlistentry>
 131 <term>maxchannels</term>
 132 <listitem>
 133 <para>Interpreted as an integer. If not zero, limits the number of
 134 channels the hook will interpret from the "channels" variable.</para>
 135
 136 <para>This variable cannot be set through VCS configuration variables
 137 or <filename>irker.conf</filename>; it can only be set with a command-line
 138 argument.  Thus, on a forge site in which repository owners are not
 139 allowed to modify their post-commit scripts, a site administrator can set it
 140 to prevent shotgun spamming by malicious project owners.  Setting it to
 141 a value less than 2, however, would probably be unwise.</para>
 142 </listitem>
 143 </varlistentry>
 144 </variablelist>
 145
 146 <refsect2 id="git"><title>git</title>
 147
 148 <para>Under git, <application>irkerhook.py</application> does not
 149 require any arguments.  Preferences may be set in the repo
 150 <filename>config</filename> file in an [irker] section. Here
 151 is an example of what that can look like:</para>
 152
 153 <programlisting>
 154 [irker]
 155     project = gpsd
 156     color = ANSI
 157     channels = {irc://chat.freenode.net/gpsd, irc://chat.freenode.net/commits}
 158 </programlisting>
 159
 160 <para>Command-line variable=value arguments are accepted but not
 161 required.  No attempt is made to interpret an
 162 <filename>irker.conf</filename> file.  You should not set the
 163 "repository" variable (an equivalent will be computed).</para>
 164
 165 <para>The default value of the "project" variable is the basename
 166 of the repository directory. The default value of the "urlprefix"
 167 variable is "cgit".</para>
 168
 169 <para>There is one git-specific variable, "revformat", controlling
 170 the format of the commit identifier in a notification. It
 171 may have the following values:</para>
 172
 173 <variablelist>
 174 <varlistentry>
 175 <term>raw</term>
 176 <listitem><para>full hex ID of commit</para></listitem>
 177 </varlistentry>
 178 <varlistentry>
 179 <term>short</term>
 180 <listitem><para>first 12 chars of hex ID</para></listitem>
 181 </varlistentry>
 182 <varlistentry>
 183 <term>describe</term>
 184 <listitem><para>describe relative to last tag, falling back to short</para></listitem>
 185 </varlistentry>
 186 </variablelist>
 187
 188 <para>The default is 'describe'.</para>
 189 </refsect2>
 190
 191 <refsect2 id="svn"><title>Subversion</title>
 192
 193 <para>Under Subversion, <application>irkerhook.py</application>
 194 requires two arguments: "repository=" (the absolute pathname of the
 195 Subversion repository) and "commit=" (the numeric revision level of
 196 the commit).  The values must be the two arguments that Subversion
 197 gives its post-commit hook. Thus, a typical invocation in the post-commit
 198 script will look like this:</para>
 199
 200 <programlisting>
 201 irkerhook.py repository=$1 commit=$2
 202 </programlisting>
 203
 204 <para>Other variable=value settings may also be
 205 given on the command line, and will override any settings in an
 206 <filename>irker.conf</filename> file.</para>
 207
 208 <para>The default for the project variable is the basename of the
 209 (required) repository= argument.The default value of the "urlprefix"
 210 variable is "viewcvs".</para>
 211
 212 <para>If an <filename>irker.conf</filename> file exists in the repository
 213 root directory (not the checkout directory but where internals such as the
 214 "format" file live) the hook will interpret variable settings from it.  Here
 215 is an example of what such a file might look like:</para>
 216
 217 <programlisting>
 218 # irkerhook variable settings for the irker project
 219 project = irker
 220 channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
 221 tcp = false
 222 </programlisting>
 223
 224 <para>Don't the "repository" or "commit" variables in this file;
 225 that would have unhappy results.</para>
 226
 227 <para>There are no Subversion-specific variables.</para>
 228
 229 </refsect2>
 230
 231 </refsect1>
 232
 233 <refsect1 id='options'><title>OPTIONS</title>
 234
 235 <para><application>irkerhook.py</application> takes the following
 236 options:</para>
 237
 238 <variablelist>
 239 <varlistentry>
 240 <term>-n</term>
 241 <listitem><para>Suppress transmission to a daemon. Instead, dump the
 242 generated JSON request to standard output. Useful for
 243 debugging.</para></listitem>
 244 </varlistentry>
 245 <varlistentry>
 246 <term>-V</term>
 247 <listitem><para>Write the program version to stdout and
 248 terminate.</para></listitem>
 249 </varlistentry>
 250 </variablelist>
 251
 252 </refsect1>
 253
 254 <refsect1 id='authors'><title>AUTHOR</title>
 255 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
 256 project page at <ulink
 257 url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/irker</ulink>
 258 for updates and other resources.</para>
 259 </refsect1>
 260 </refentry>
 261