repo_shell provides a login shell for servers hosting subversion and/or git
centralized repositories.  Unlike gitolite, which is a more full-featured and
powerful solution for git, repo_shell requires user accounts to be set up on the
server for each developer.  This allows a critical feature that we needed: the
option to allow access to a repository via a user's password in addition to an
SSH key pair.  This feature is useful when needing to check out objects from a
repository where copying the user's private key to some machine is either
undesirable or a waste of time.

repo_shell owes great thanks to work shared by two other projects:

- The GIT stupid content tracker - http://git-scm.org
  Some useful information was gleaned from git's git-shell program.
  GIT is licensed under the GPLv2.

- The inih .ini parser library - http://code.google.com/p/inih/
  This is a great little library for handling simple configuration files.
  inih is licensed under a modified BSD license, available in inih/LICENSE.txt.

To acquire repo_shell:

    git clone git://oss.titaniummirror.com/repo_shell.git

To build repo_shell, use make.  Please build from a clone of the above
repository, as the make script uses 'git describe --tags' to generate the
resulting executable's version string.

    make repo_shell

To install repo_shell:

    sudo cp repo_shell /usr/local/bin/
    sudo chown root:root /usr/local/bin/repo_shell
    sudo chmod u+s /usr/local/bin/repo_shell
    vi /etc/repo_shell.cfg

The /etc/repo_shell.cfg configuration file is straightforward:

    [core]
    owner=repo
    git_root=/var/lib/git
    svn_root=/var/lib/svn/repositories

The owner field denotes the user that owns all repositories.  The git_root and
svn_root fields identify the path to the respective repositories.  The latter
two fields allow repo_shell to automatically add the appropriate repository root
path to repository access commands, obviating the need for developers to know
exactly where repositories are stored.  Note that git repositories can be nested
within directories, as the examples show below.

    git clone server:repo.git          -> server:<git_root>/repo.git
    git clone server:/repo.git         -> server:<git_root>/repo.git
    git clone server:/subdir/repo.git  -> server:<git_root>/subdir/repo.git
    svn checkout svn+ssh://server/repo -> server:<svn_root>/repo

Repositories should be owned by the user identified in the owner field.  For
example:

    sudo -iu owner
    umask 077
    svnadmin create --fs-type fsfs <svn_root>/newreponame
    git --git-dir <git_root>/newrepopath.git init --bare

Please see the svncreate for an example helper script for subversion repository
creation.

To use external viewers that directly interrogate the repository, the simplest
solution is to have those viewers run as another user belonging to the owner's
primary group.  In this case, in the examples above, a umask of 027 is
appropriate when creating repositories.  However, please note that such external
programs are able to read all repositories independent of access controls.

For users to have access to repositories, they need only have repo_shell set as
their login shell:

    sudo chsh -s /usr/local/bin/repo_shell <developername>

And of course the user must be associated for appropriate access in subversion
and get access control lists.

Access controls for subversion repositories uses subversion's built-in features,
using svnserve.conf.  A good way to go is to have each repository's
svnserve.conf set a global authz.conf file, using the standard hooks and
activating svnperms.conf for branch-based commit control.  These are suggestions
outside the scope of the repo_shell program itself.

Access controls for git are envisioned to be incorporated into repo_shell.  They
aren't at this time, and any developer has read-write access to any git
repository.