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'>irkerd</refmiscinfo>
  10 <refmiscinfo class='product'>irkerd</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 </variablelist>
 118
 119 <refsect2 id="git"><title>git</title>
 120
 121 <para>Under git, <application>irkerhook.py</application> does not
 122 require any arguments.  All variables may be set in the repo
 123 <filename>config</filename> file in an [irker] section.  Command-line
 124 variable=value arguments are accepted but not required.  No attempt is
 125 made to interpret an <filename>irker.conf</filename> file.  You should
 126 not set the "repository" variable (an equivalent will be
 127 computed).</para>
 128
 129 <para>The default value of the "project" variable is the basename
 130 of the repository directory. The default value of the "urlprefix"
 131 variable is "cgit".</para>
 132
 133 <para>There is one git-specific variable, "revformat", controlling
 134 the format of the commit identifier in a notification. It
 135 may have the following values:</para>
 136
 137 <variablelist>
 138 <varlistentry>
 139 <term>raw</term>
 140 <listitem><para>full hex ID of commit</para></listitem>
 141 </varlistentry>
 142 <varlistentry>
 143 <term>short</term>
 144 <listitem><para>first 12 chars of hex ID</para></listitem>
 145 </varlistentry>
 146 <varlistentry>
 147 <term>describe</term>
 148 <listitem><para>describe relative to last tag, falling back to short</para></listitem>
 149 </varlistentry>
 150 </variablelist>
 151
 152 <para>The default is 'describe'.</para>
 153 </refsect2>
 154
 155 <refsect2 id="svn"><title>Subversion</title>
 156
 157 <para>Under Subversion, <application>irkerhook.py</application>
 158 requires two arguments: "repository=" (the absolute pathname of the
 159 Subversion repository) and "commit=" (the numeric revision level of
 160 the commit).  The values must be the two arguments that Subversion
 161 gives its post-commit hook. Thus, a typical invocation in the post-commit
 162 script will look like this:</para>
 163
 164 <programlisting>
 165 irkerhook.py repository=$1 commit=$2
 166 </programlisting>
 167
 168 <para>Other variable=value settings may also be
 169 given on the command line, and will override any settings in an
 170 <filename>irker.conf</filename> file.</para>
 171
 172 <para>The default for the project variable is the basename of the
 173 (required) repository= argument.The default value of the "urlprefix"
 174 variable is "viewcvs".</para>
 175
 176 <para>If an <filename>irker.conf</filename> file exists in the repository
 177 root directory (not the checkout directory but where internals such as the
 178 "format" file live) the hook will interpret variable settings from it.  Here
 179 is an example of what such a file might look like:</para>
 180
 181 <programlisting>
 182 # irkerhook variable settings for the irker project
 183 project = irker
 184 channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
 185 tcp = false
 186 </programlisting>
 187
 188 <para>Don't the "repository" or "commit" variables in this file;
 189 that would have unhappy results.</para>
 190
 191 <para>There are no Subversion-specific variables.</para>
 192
 193 </refsect2>
 194
 195 </refsect1>
 196
 197 <refsect1 id='options'><title>OPTIONS</title>
 198
 199 <para><application>irkerhook.py</application> takes the following
 200 options:</para>
 201
 202 <variablelist>
 203 <varlistentry>
 204 <term>-n</term>
 205 <listitem><para>Suppress transmission to a daemon. Instead, dump the
 206 generated JSON request to standard output. Useful for
 207 debugging.</para></listitem>
 208 </varlistentry>
 209 <varlistentry>
 210 <term>-V</term>
 211 <listitem><para>Write the program version to stdout and
 212 terminate.</para></listitem>
 213 </varlistentry>
 214 </variablelist>
 215
 216 </refsect1>
 217
 218 <refsect1 id='authors'><title>AUTHOR</title>
 219 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
 220 project page at <ulink
 221 url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/irker</ulink>
 222 for updates and other resources.</para>
 223 </refsect1>
 224 </refentry>
 225