NAME

       irkerhook - repository hook script issuing irker notifications

SYNOPSIS

       irkerhook.py [-n] [-V] [[--variable=value...]] [[commit-id...]]

DESCRIPTION

       irkerhook.py 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 irkerd for forwarding to various announcement channels.

       The proper invocation and behavior of irkerhook.py varies depending on which VCS
       (version-control system) is calling it. There are four different places from which it may
       extract information:

        1. Calls to VCS utilities.

        2. In VCSes like git that support user-settable configuration variables, variables with
           the prefix "irker.".

        3. In other VCSes, a configuration file, "irker.conf", in the repository's internals
           directory.

        4. Command-line arguments of the form --variable=value.

       The following variables are general to all supported VCSes:

       project
           The name of the project. Should be a relatively short identifier; will usually appear
           at the very beginning of a notification.

       repo
           The name of the repository top-level directory. If not specified, defaults to a
           lowercased copy of the project name.

       channels
           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.

       server
           The host on which the notification-relaying irker daemon is expected to reside.
           Defaults to "localhost".

       tcp
           If "true", use TCP for communication; if "false", use UDP. Defaults to "false".

       urlprefix
           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.

           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.

           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 irkerhook.py is running; the latter is
           expanded to the value of the "repo" variable.

       tinyifier
           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.

       color
           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, but not in mIRC,
           XChat, KVirc or Konversation.

           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 <channel> -c" with <channel> replaced by your
           chnnel name. You may need to first issue the command "/msg chanserv set <channel>
           MLOCK +nt-slk".

       maxchannels
           Interpreted as an integer. If not zero, limits the number of channels the hook will
           interpret from the "channels" variable.

           This variable cannot be set through VCS configuration variables or irker.conf; 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.

       cialike
           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.

   git
       Under git, the normal way to invoke this hook (from within the update hook) passes with a
       refname followed by a list of commits. Because git rev-list 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

           refname=$1
           old=$2
           new=$3
           irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})

       except that you'll need an absolute path for irkerhook.py.

       For testing purposes and backward compatibility, if you invoke irkerhook.py with no
       arguments (as in a post-commit hook) it will behave as though it had been called like
       this:

           irkerhook.py --refname=refs/heads/master HEAD

       However, this will not give the right result when you push to a non-default branch of a
       bare repo.

       Preferences may be set in the repo config file in an [irker] section. Here is an example
       of what that can look like:

           [irker]
               project = gpsd
               color = ANSI
               channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits

       You should not set the "repository" variable (an equivalent will be computed). No attempt
       is made to interpret an irker.conf file.

       The default value of the "project" variable is the basename of the repository directory.
       The default value of the "urlprefix" variable is "cgit".

       There is one git-specific variable, "revformat", controlling the format of the commit
       identifier in a notification. It may have the following values:

       raw
           full hex ID of commit

       short
           first 7 chars of hex ID

       describe
           describe relative to last tag, falling back to short

       The default is 'describe'.

   Subversion
       Under Subversion, irkerhook.py 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.

       Note, however, that you cannot 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:

           REPO=$1
           REV=$2
           irkerhook.py --repository=$REPO $REV

       Other --variable=value settings may also be given on the command line, and will override
       any settings in an irker.conf file.

       The default for the project variable is the basename of the repository. The default value
       of the "urlprefix" variable is "viewcvs".

       If an irker.conf 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:

           # irkerhook variable settings for the irker project
           project = irker
           channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
           tcp = false

       Don't set the "repository" or "commit" variables in this file; that would have unhappy
       results.

       There are no Subversion-specific variables.

   Mercurial
       Under Mercurial, irkerhook.py can be invoked in two ways: either as a Python hook
       (preferred) or as a script.

       To call it as a Python hook, add the collowing to the "commit" or "incoming" hook
       declaration in your Mercurial repository:

           [hooks]
                incoming.irker = python:/path/to/irkerhook.py:hg_hook

       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.

       As for git, in both cases all variables may be set in the repo hgrc 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 irker.conf file.

       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.

   Filtering
       It is possible to filter commits before sending them to irkerd.

       You have to specify the filtercmd option, which will be the command irkerhook.py 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.

       Below is an example filter:

           #!/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

       Standard error is available to the hook for progress and error messages.

OPTIONS

       irkerhook.py takes the following options:

       -n
           Suppress transmission to a daemon. Instead, dump the generated JSON request to
           standard output. Useful for debugging.

       -V
           Write the program version to stdout and terminate.

SEE ALSO

       irkerd(8),

AUTHOR

       Eric S. Raymond esr@snark.thyrsus.com. See the project page at
       http://www.catb.org/~esr/irker for updates and other resources.