From 2e99f70cfa0aa1a81c5a5cf40c761b18baa3a82b Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Sun, 30 Sep 2012 09:51:37 -0400 Subject: [PATCH] irkerhook.py gets a manual page. --- irkerhook.py | 43 ++--------------- irkerhook.xml | 129 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 131 insertions(+), 41 deletions(-) diff --git a/irkerhook.py b/irkerhook.py index b50b765..c2ddb4c 100755 --- a/irkerhook.py +++ b/irkerhook.py @@ -9,47 +9,10 @@ # # This script is meant to be run in a post-commit hook. Try it with # -n to see the notification dumped to stdout and verify that it looks -# sane. With -V it dumps its version and exits. +# sane. With -V this script dumps its version and exits. # -# Currently works for svn and git. For svn you must call it as follows: -# -# irkerhook.py repository=REPO-PATH commit=REVISION channels=CHANNELS server=SERVER -# -# REPO-PATH must be the absolute path of the SVN repository (first -# argument of Subversion post-commit). REVISION must be the Subversion numeric -# commit level (second argument of Subversion post-commit). CHANNELS must -# be a string containing either an IRC URL or comma-separated list of same. -# SERVER must be an irker host. -# -# For git, you can normally call this script without arguments; it -# will deduce most of what it needs from git configuration variables -# (and the project value from where it is in the file system). -# Configuration variables are as follows. -# -# irker.project = name of the project -# irker.channels = list of IRC URLs corresponding to channels -# irker.repo = name of the project repo for gitweb/cgit purposes -# irker.revformat = format in which the revision is shown -# irker.server = location of the irker server to use for relaying -# irker.tcp = use TCP/IP if true, otherwise UDP -# -# irker.channels defaults to a project channel on freenode, and #commits -# irker.project defaults to the directory name of the repository toplevel. -# irker.repo defaults to irker.project lowercased. -# irker.tcp defaults to False -# -# This means that in the normal case you need not do any configuration at all, -# but setting the project name will speed it up slightly. -# -# The revformat variable 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'. -# -# Any of these variables can be overridden with a command-line argument that -# is a key=value pair. For example "project=foobar" will force the project -# name to foobar, regardless of what the git configuration says. +# See the irkerhook manual page in the distribution for a detailed +# explanation of how to configure this hook. # # Other configuration changes you may want to make are to: # diff --git a/irkerhook.xml b/irkerhook.xml index c56b64f..7842d83 100644 --- a/irkerhook.xml +++ b/irkerhook.xml @@ -20,7 +20,7 @@ irkerhook.py -n -V - key=val + variable=value @@ -33,6 +33,133 @@ 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 notofications 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. + + + +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". + + + + +git + +Under git, irkerhook.py does not +require any arguments. All variables may be set in the repo +config file, and are distinguished with +the application prefix "irker.". Command-line variable=value +arguments are accepted but not required. No attempt is made +to interpret an irker.conf file. + +The default value of the "project" variable is the basename +of the repository directory. + +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 +requires two arguments: "repository=" (the absolute pathname of the +Subversion repository) and "commit=" (the numeric revision level of +the commit). The values must be the two arguments that Subversion +gives its post-commit hook. Thus, a typical invocation in the post-commit +script will look like this: + + +irkerhook.py repository=$1 commit=$2 + + +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 +(required) repository= argument. + +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 + + +There are no Subversion-specific variables. + + + OPTIONS -- 2.26.2