KGB-CLIENT(1p)						User Contributed Perl Documentation					    KGB-CLIENT(1p)

NAME

       kgb-client - relay commits to KGB servers

SYNOPSIS

       kgb-client --conf /path/to/config [other-option ...]
       kgb-client --uri http://some.server:port/service --password password --repo-id repository --timeout timeout-in-seconds
       --single-line-commits off|forced|auto --status-dir directory
       kgb-client option... /svn/repo revision
       kgb-client option... old-rev new-rev ref-name

DESCRIPTION

       kgb-client is the client counterpart of kgb-bot(1). Intented usage is 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, whch will show it on IRC.

CONFIGURATION

       --conf configuration file
	   Specifies the path to kgb-client configuration file.

       Configuration options (except --conf) 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 multple servers and multiple ways of detection of branch and module names.

       The configration 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.

       repository type
	   Specifies the type of the repository kgb-client shall be working with.  Currently defaults to "svn".

       repo-id repository name
	   Short repository identifier. Will be used for identifying the repository to the KGB daemon, which will also use this for IRC
	   notifications. Mandatory.

       uri URI
	   URI of the KGB server. Something like "http://some.server:port". Mandatory.

       proxy URI
	   URI of the SOAP proxy. If not given, it is the value of the uri option, with "?session=KGB" added.

       password password
	   Password for authentication to the KGB server.

       timeout seconds
	   Timeout for server communication. Default is 15 seconds, as we want instant IRC and commit response.

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

       single-line-commits off|forced|auto
	   Request different modes of commit message processing:

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

	   forced
	       Only the first line is sent to IRC, regardles of whether it is followed by a blank line or not.

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

       status-dir directory
	   With this option, kgb-client tries to contact the last server that was successfuly contacted first. The directory is used to store the
	   information about the last contacted server.

       verbose
	   Makes the whole process more verbose.

   Branches and modules
       Sometimes development is done in multiple branches. Simetimes, a project consists of multiple sub-projects or modules. It is nice to have
       the module and branc 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.

       branch-and-module-re
	   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

       branch-and-module-re-swap 1
	   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

       module name
	   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.

SUPPORTED VERSION CONTROL SYSTEMS

   Subversion
       Installation requires calling kgb-client with two command line arguments:

       path to the subversion repository
	   This is the physical path to the Subversion repository. Something like /srv/svn/my-repo

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

   Git
       kgb-client shall be installed as a post-recieve 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.

SEE ALSO

       App::KGB::Client
       App::KGB::Client::Subversion
       App::KGB::Client::Git

perl v5.12.4							    2011-09-14							    KGB-CLIENT(1p)