irkerd: Store less state in IRCServerConnection.connect()

[irker.git] / irkerhook.xml

diff --git a/irkerhook.xml b/irkerhook.xml
index d097aaaeb442d33a808073116b933483b64d56a2..a78801ab8f4e5a7d50824f6888fd1dbe37ba3fe5 100644 (file)
--- a/irkerhook.xml
+++ b/irkerhook.xml
@@ -71,8 +71,7 @@ specified, defaults to a lowercased copy of the project name.</para>
 <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
-defaults channel list id the freenode #commits channel plus the freenode
-channel named by the project variable.</para>
+default is the freenode #commits channel.</para>
 </listitem>
 </varlistentry>
 <varlistentry>
@@ -83,6 +82,13 @@ 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.
@@ -94,7 +100,7 @@ Defaults to "false".</para>
 <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
+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
@@ -120,13 +126,17 @@ variable is "None", no compression will be attempted.</para>
 <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). 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 #irker -c".  You may need to
-first issue the command "/msg chanserv set #irker MLOCK
-+nt-slk".</para>
+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>
@@ -143,6 +153,15 @@ 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", 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>
 </variablelist>
 
 <refsect2 id="git"><title>git</title>
@@ -174,6 +193,20 @@ irkerhook.py --refname=refs/heads/master HEAD
 <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>
@@ -182,7 +215,7 @@ like:</para>
 [irker]
     project = gpsd
     color = ANSI
-    channels = {irc://chat.freenode.net/gpsd, irc://chat.freenode.net/commits}
+    channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits
 </programlisting>
 
 <para> You should not set the "repository" variable (an equivalent
@@ -224,10 +257,12 @@ the commit).  The defaults are the current working directory and HEAD,
 respectively.</para>
 
 <para>Note, however, that you <emphasis>cannot</emphasis> default the
-repository argumment inside a Subversion post-commit hook.  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>
+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
@@ -353,6 +388,12 @@ terminate.</para></listitem>
 
 </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