karawitan / ngitcached

A caching git proxy

ngitcached - a caching git proxy

THIS IS PRE-RELEASE SOFTWARE

It is not suitable for use in production.

ngitcached is a git proxy with two primary goals:

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

• provide a stable interface to flaky git servers.

Installing from source

make install

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

See `make help' for more information.

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.

Manual

NAME

ngitcached - a caching git proxy

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.

OPTIONS

--help

Print this usage info.

--version

Print version and exit.

--port PORT

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

--cache-dir PATH

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

--node PATH

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

--verbose *

Increase verbosity. May be used multiple times.

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

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.

PROXY BY GIT CONFIG

The core.gitProxy git config value, or the 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.

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.

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

SIGNALS

The ngitcached process will react to the following signals:

SIGHUP

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

BUGS

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