view release on metacpan or  search on metacpan

script/kgb-client  view on Meta::CPAN

# Foundation; either version 2 of the License, or (at your option) any later
# version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
# details.
#
# You should have received a copy of the GNU General Public License along with
# this program; if not, write to the Free Software Foundation, Inc., 51
# Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

use strict;
use warnings;

=head1 NAME

kgb-client - relay commits to KGB servers

=head1 SYNOPSIS

=over

=item B<kgb-client> --conf I</path/to/config> [I<other-option> ...]

=item B<kgb-client> --uri I<http://some.server:port/service>
                    --password I<password>
                    --repo-id I<repository>
                    --repository I<svn|git|cvs>
                    --timeout I<timeout-in-seconds>
                    --single-line-commits I<off|forced|auto>
                    --use-irc-notices
                    --web-link I<template>
                    --short-url-service I<service>
                    --status-dir I<directory>
                    --[no]-use-color
                    --message-template I<template>
                    --batch-messages
                    --dry-run

=item B<kgb-client> I<option>... I</svn/repo> I<revision>

=item B<kgb-client> I<option>... I<old-rev> I<new-rev> I<ref-name>

=item B<kgb-client> I<option>... $CVSROOT "%p"

=item B<kgb-client> I<option>... --fake

=item B<kgb-client> I<option>... --relay-msg I<message>...

=item B<kgb-client> --help

=item B<kgb-client> --man

=back

=head1 DESCRIPTION

B<kgb-client> is the client counterpart of L<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 to the
KGB server, which will show it on IRC.

=head1 CONFIGURATION

=over

=item B<--conf> I<configuration file>

Specifies the path to kgb-client configuration file.

=back

Configuration options (except B<--conf>, B<--fake> and B<--relay-msg>) 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.

See L<kgb-client.conf(5)> for available configuration options. Unless noted
otherwise, all the options in the configuration file can also be used on
command line, prefixing them with two dashes. E.g. C<repo-id> becomes
C<--repo-id>.

Options given on the command line take precedence over configuration file.

=head1 FAKE COMMIT MODE

If invoked with the B<--fake> option, B<kgb-client> will send a fake commit to
the servers. This is useful for testing client-server communication
independently from VCS setup.

=head1 MESSAGE RELAY MODE

When the B<--relay-msg> option is given, there is no repository to be
inspected. Instead, the non-option 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.

=head1 SUPPORTED VERSION CONTROL SYSTEMS

=head2 Subversion

Installation requires calling B<kgb-client> with two command line arguments,
like this:

    /path/to/kgb-client "$REPOS" "$REV"

=over

=item I<path to the subversion repository>

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

=item I<revision>

This is the revision number of the commit, that has triggered the hook.

=back