-Build
------
+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.
-make repo_shell
+repo_shell owes great thanks to work shared by two other projects:
-Install
--------
+- 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.
-sudo cp repo_shell /usr/local/bin/
+- 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.
-Configure
----------
+To acquire repo_shell:
-cat <+EOF+ > repo_shell.cfg
-[core]
-owner=repo
-git_root=/var/lib/git
-svn_root=/var/lib/svn/repositories
-+EOF+
-sudo mv repo_shell.cfg /etc/
+ git clone git://oss.titaniummirror.com/repo_shell.git
-Notes
------
-The inih library comes from:
-URL: http://inih.googlecode.com/svn/trunk
-Repository Root: http://inih.googlecode.com/svn
-Repository UUID: f5d6dc10-6d35-11de-b131-07d8e4d3762e
-Revision: 22
+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:
+
+ owner=repo
+ git_root=/var/lib/git
+ svn_root=/var/lib/svn/repositories
+ git_acl_file=/var/lib/git/.gitacls
+
+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 repositories uses a feature built-into repo_shell. The
+/etc/repo_shell.cfg file lists a parameter git_acl_file, which should be set to
+the name of the git acl file. A recommended name is /var/lib/git/.gitacls, with
+permissions 0400. See git_acl.cfg.example for information on the format of this
+file, which is similar in concept, but different, than subversion's authz.conf
+file format.