ngitcached

ngitcached copied to clipboard

=pod

=head1 ngitcached - a caching git proxy

B<THIS IS PRE-RELEASE SOFTWARE>

It is not suitable for use in production.

ngitcached is a git proxy with two primary goals:

=over

=item *

speed up repeated clones/fetches of the same git objects from multiple clients.

=item *

provide a stable interface to flaky git servers.

=back

=head2 Installing from source

make install

Installing from source requires the "npm" command to be available.

See `make help' for more information.

=head2 Installing from binaries

Ubuntu: there is a PPA available for ngitcached packages: https://launchpad.net/~rohanpm/+archive/ngitcached

It is also recommended to obtain node.js from this PPA: https://launchpad.net/~chris-lea/+archive/node.js

sudo apt-add-repository ppa:chris-lea/node.js sudo apt-add-repository ppa:rohanpm/ngitcached sudo apt-get update sudo apt-get install ngitcached

Other platforms: packages have not yet been prepared.

=head1 Manual

=head2 NAME

ngitcached - a caching git proxy

=head2 SYNOPSIS

ngitcached --cache-dir /srv/ngitcached

Start a git daemon service on this machine which may proxy requests to other servers and cache the results.

=head3 OPTIONS

=over

=item --help

Print this usage info.

=item --version

Print version and exit.

=item --port PORT

Listen on the given port number. Default: 9418 (standard git-daemon port).

=item --cache-dir PATH

Set the path to the git cache directory (mandatory).

=item --node PATH

Set the path to the node runtime to be used (default: first in $PATH).

=item --verbose *

Increase verbosity. May be used multiple times.

=item --test

Enable a few internal strict checks to help find bugs in ngitcached. This turns some warnings into fatal errors, and therefore should not be used in production.

=back

=head2 USING THE PROXY

ngitcached may be used as a transparent proxy at the git or OS level, or an opt-in proxy at the git level by using a special syntax for git repositories.

=head3 PROXY BY GIT CONFIG

The C<core.gitProxy> git config value, or the C<GIT_PROXY_COMMAND> environment variable, may be used to redirect all git communications through ngitcached.

For example, connections may be routed through an ngitcached instance running on gitproxy.example.com port 9418 by the following shell snippet:

GIT_PROXY_COMMAND=/tmp/proxy2ngitcached { echo -e '#!/bin/sh\nexec netcat gitproxy.example.com 9418' } > $GIT_PROXY_COMMAND chmod +x $GIT_PROXY_COMMAND export GIT_PROXY_COMMAND

See "git help config" for more information.

=head3 PROXY BY OPERATING SYSTEM

ngitcached may be used as a transparent proxy by arranging for outgoing git TCP connections to be routed through an ngitcached instance; for example, by the usage of iptables on Linux.

This generally requires superuser privileges either on the client machine, or on a router between the client and server.

=head3 PROXY BY SPECIAL GIT URL

The proxy may be used by explicitly cloning from the proxy's URL and including the desired remote at the end of the URL, as a "remote" parameter in HTTP query string style.

For example, git://github.com/rohanpm/ngitcached.git may be cloned via an ngitcached instance running on gitproxy.example.com port 9418 by the following command:

git clone git://gitproxy.example.com:9418/?remote=github.com/rohanpm/ngitcached.git

=head2 SIGNALS

The ngitcached process will react to the following signals:

=over

=item SIGHUP

ngitcached will dump, to standard out, some statistics and the state of each connection to the proxy.

=back

=head2 BUGS

A list of known bugs is available at https://github.com/rohanpm/ngitcached/issues