X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=README;h=432904e8d1072763f25d481e7dd7eb8df6080690;hb=e1789cd2f72cbf3a7bf3517177334a20d0cf551f;hp=d6cabcb8e32a9cec186f5c1c530ce6ca691d5d68;hpb=5c69e9df5b780ddc59f29074b8f007734f38ed1a;p=repo_shell.git

diff --git a/README b/README
index d6cabcb..432904e 100644
--- a/README
+++ b/README
@@ -1,29 +1,86 @@
-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:
+
+    [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
+
+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.