From 3aecc6d0a8d757d6159dfa5083f1b254296c5b43 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:27:58 +0200 Subject: Adding upstream version 2.23+dfsg. Signed-off-by: Daniel Baumann --- irkerhook.xml | 417 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 417 insertions(+) create mode 100644 irkerhook.xml (limited to 'irkerhook.xml') diff --git a/irkerhook.xml b/irkerhook.xml new file mode 100644 index 0000000..54b7425 --- /dev/null +++ b/irkerhook.xml @@ -0,0 +1,417 @@ + + + +irkerhook +1 +Aug 27 2012 +irker +irker +Commands + + +irkerhook +repository hook script issuing irker notifications + + + + + 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: + + +Calls to VCS utilities. +In VCSes like git that support user-settable configuration +variables, variables with the prefix "irker.". +In other VCSes, a configuration file, "irker.conf", in the +repository's internals directory. +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". + + + +email + +If set, use email for communication rather than TCP or UDP. +The value is used as the target mail address. + + + +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; mIRC codes only are recognized +in mIRC, XChat, KVirc, Konversation, or weechat. + +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 channel 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" (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. + + + +template + +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. + + + + +irkerhook.py will run under both python 2 and python 3, but it does +not support mercurial repositories under python 3 yet. + +git + +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 +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. + +A typical way to install this hook is actually in the +post-receive hook, because it gets all the +necessary details and will not abort the push on failure. Use the +following script: + + +#!/bin/sh + +echo "sending IRC notification" +while read old new refname; do + irkerhook --refname=${refname} $(git rev-list --reverse ${old}..${new}) +done + + +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 12 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 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 python3 +# 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 + +irkerd8, + + + +AUTHOR +Eric S. Raymond esr@snark.thyrsus.com. See the +project page at http://www.catb.org/~esr/irker +for updates and other resources. + + + -- cgit v1.2.3