kgb-client - relay commits to KGB servers
kgb-client is the client counterpart of kgb-bot(1). It is intended to be used as a hook in your version control system, executed after the repository gets updated. It analyzes the commit(s) and then relays the information about the repository, branch, author, modified files and change log to the KGB server, which will show it on IRC.
If invoked with the --fake option, kgb-client will send a fake commit to the servers. This is useful for testing client-server communication independently from VCS setup.
Specifies the path to kgb-client configuration file.
Configuration options (except --conf and --fake) may be specified both in the configuration file and on the command line. Usually you want to have all the options in a configuration file, because having passwords on the command line is insecure. The configuration file also gives more control, for example it supports multiple servers and multiple ways of detection of branch and module names.
The configuration file is in YAML format. Unless noted otherwise, all the options below can be used on the command line if prepended with two dashes. An example configuration file is shipped with the distribution.
Specifies the type of the repository kgb-client shall be working with. The default is determined as follows:
GIT_DIR
CVSROOT
Short repository identifier. Will be used for identifying the repository to the KGB daemon, which will also use this for IRC notifications. Mandatory.
URI of the KGB server. Something like http://some.server:port. Mandatory.
http://some.server:port
URI of the SOAP proxy. If not given, it is the value of the uri option, with ?session=KGB added.
?session=KGB
Password for authentication to the KGB server.
Timeout for server communication. Default is 15 seconds, as we want instant IRC and commit response.
Only available in the configuration file.
An array of servers, each described using uri, proxy, password and timeout options. When several servers are configured, kgb-client chooses one randomly. If a given server times out or there is another problem with communication, kgb-client tries another server.
The top-level uri, proxy, password and timeout options are treated as describing an extra server to the servers described in servers array.
The password and timeout options default too the top-level options of the same name.
Request different modes of commit message processing:
No processing is done. The commit message is printed as was given, with each line in a separate IRC message, blank lines omitted. This is the only possible behaviour in versions before 1.14.
Only the first line is sent to IRC, regardless of whether it is followed by a blank line or not.
If the first line is followed by an empty line, only the first line is sent to IRC and the rest is ignored. This is the default since version 1.14.
With this option, kgb-client tries to contact the last server that was successfully contacted first. The directory is used to store the information about the last contacted server.
Makes the whole process more verbose.
For Git repositories, the default value for module is taken to be the last path component of GIT_DIR environment variable, with trailing .git removed.
.git
See also the branch-and-module-re setting, useful for multi-project repositories.
Passes a web link to the server, who would make it appear in the notification. The following items in template are expanded before sending.
The branch of the commit, as determined by the branch-and-module-re regular expressions, see "Branches and modules".
The module as determined by the branch-and-module-re regular expressions, see "Branches and modules".
The commit ID (revision number for Subversion, short commit hash for Git).
Examples:
http://git.debian.org/?p=pkg-firebird/2.5.git;a=commitdiff;h=${commit} http://git.debian.org/?p=pkg-perl/packages/${module}.git;a=commitdiff;h=${commit} http://svn.debian.org/viewvc/kgb?view=revision&revision=${commit}
Makes sense only if web-link is also used. Uses the specified service of WWW::Shorten to shorten the link. See the manual of WWW::Shorten for the list of supported services.
Sometimes development is done in multiple branches. Sometimes, a project consists of multiple sub-projects or modules. It is nice to have the module and branch highlighted in notifications. There are two options to help determining the module and branch names from a list of changes.
These options are mainly useful when using Subversion. Git commits carry implicit branch information and chances are that sub-projects use separate Git repositories.
A list of regular expressions that serve for detection of branch and module of commits. Each item from the list is tried in turn, until an item is found that matches all the paths that were modified by the commit. Regular expressions must have two captures: the first one giving the branch name, and the second one giving the module name.
All the paths that were modified by the commit must resolve to the same branch and module in order for the branch and module to be transmitted to the KGB server.
Hint: use () to match empty branch or module if the concept is not applicable. Like:
branch-and-module-re: - "^/(trunk)/([^/]+)/" - "^()/(website)/" # either a sub-project in /trunk/<subproject> # or a file in the website, which is matched like a module
If you can only provide the module name in the first capture and the branch name in the second, use this option to signal the fact to kgb-client. The setting is in effect for all patterns.
branch-and-module-re-swap: 1 branch-and-module-re: - "^/([^/]+)/(trunk|tags)/" - "^/(website)/()" # either a sub-project in /<subproject> # or a file in the website, which is matched like a module
In the case of sub-projects that use separate Git repositories, you may want to use explicit module name. Having this on the command line would allow for all the sub-project to share the configuration file (same repo-id) while still having sub-project-specific notifications.
When the --relay-msg option is given, there is no repository to be inspected. Instead, the remaining command line arguments are passed verbatim to the bot to display on IRC. This can be used for real-time notification about other events like bug submissions etc.
Installation requires calling kgb-client with two command line arguments:
This is the physical path to the Subversion repository. Something like /srv/svn/my-repo
This is the revision number of the commit, that has triggered the hook.
Both these arguments are supplied to the standard Subversion post-commit hooks.
kgb-client shall be installed as a post-receive hook. Something along the following shall do:
#!/bin/sh /path/to/kgb-client --git-reflog - --conf /path/to.conf ...
--git-reflog - will make kgb-client read the reflog information from standard input as any standard Git post-receive hook.
There are other ways to give kgb-client information about Git reflog, mostly useful when debugging on in unusual situations. See App::KGB::Client::Git.
kgb-client shall be installed in the loginfo file under CVSROOT in the CVS repository. It shall be given two arguments -- the repository root, and the directory in which the changes are being made.
For example:
ALL /path/to/kgb-client --repository cvs ... "$CVSROOT" "%p"
To install App::KGB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::KGB
CPAN shell
perl -MCPAN -e shell install App::KGB
For more information on module installation, please visit the detailed CPAN module installation guide.