Update documentation in preparation of release.

1 files changed, 133 insertions, 12 deletions

diff --git a/README.rst b/README.rst
index 1dc9b75..d39275b 100644
--- a/README.rst
+++ b/README.rst
@@ -2,24 +2,145 @@
  ``gitosis`` -- software for hosting ``git`` repositories
 ==========================================================
 
-Example configuration:
+	Manage ``git`` repositories, provide access to them over SSH,
+	with tight access control and not needing shell accounts.
 
-.. include:: example.conf
-   :literal:
+.. note::
+
+	Documentation is still lacking, and non-default configurations
+	(e.g. config file, repositories, installing in a location that
+	is not in ``PATH``) basically have not been tested at all.
+	Basic usage should be very reliable -- the project has been
+	hosting itself for a long time. Any help is welcome.
+
+``gitosis`` aims to make hosting ``git`` repos easier and safer.  It
+manages multiple repositories under one user account, using SSH keys
+to identify users. End users do not need shell accounts on the server,
+they will talk to one shared account that will not let them run
+arbitrary commands.
+
+``gitosis`` is licensed under the GPL, see the file ``COPYING`` for
+more information.
+
+You can get ``gitosis`` via ``git`` by saying::
+
+    git clone git://eagain.net/gitosis
+
+And install it via::
+
+    python setup.py install
+
+Though you may want to use e.g. ``--prefix=``. For Debian/Ubuntu
+users, the source is debianized.
+
+
+Setting up
+==========
+
+First, we will create the user that will own the repositories. This is
+usually called ``git``, but any name will work, and you can have more
+than one per system if you really want to. The user does not need a
+password, but does need a valid shell (otherwise, SSH will refuse to
+work).
+
+I usually store ``git`` repositories in the subtree
+``/srv/example.com/git`` (replace ``example.com`` with your own
+domain). You may choose another location. Adjust to suit and run::
+
+	sudo adduser \
+	    --system \
+            --no-create-home \
+	    --shell /bin/sh \
+	    --gecos 'git version control' \
+	    --group \
+	    --disabled-password \
+	    --home /srv/example.com/git \
+	    git
+
+This command is known to work in Debian and Ubuntu. Your mileage may
+vary.
+
+You will need an SSH public key to continue. If you don't have one,
+you need to generate one. See the man page for ``ssh-keygen``, and you
+may also be interested in ``ssh-agent``. Create it on your personal
+computer, and protect the *private* key well -- that includes not
+transferring it over the network.
 
-TODO
-====
+Next, we need to set things up for this newly-created user. The
+following command will create a ``~/repositories`` that will hold the
+``git`` repositories, a ``~/.gitosis.conf`` that will be a symlink to
+the actual configuration file, and it will add the SSH public key to
+``~/.ssh/authorized_keys`` with a ``command=`` option that restricts
+it to running ``gitosis-serve``. Run::
 
-gitosis-lint: check that the user account (e.g. ``git``) looks valid
+	sudo -H -u git gitosis-init <FILENAME.pub
+	# (or just copy-paste the public key when prompted)
 
-gitosis-init: create repo with conf+keydir
+then just ``git clone git@SERVER:gitosis-admin.git``, and you get a
+repository with SSH keys as ``keys/USER.pub`` and a ``gitosis.conf``
+where you can configure who has access to what.
 
-gitosis-create-repositories: create repos mentioned in config if
-they don't exist
+.. warning::
+
+	For now, ``gitosis`` uses the ``HOME`` environment variable to
+	locate where to write its files. If you use ``sudo -u``
+	without ``-H``, ``sudo`` will leave the old value of ``HOME``
+	in place, and this will cause trouble. There will be a
+	workaround for that later on, but for now, always remember to
+	use ``-H`` if you're sudoing to the account.
+
+You should always edit the configuration file via ``git``. The file
+symlinked to ``~/.gitosis.conf`` on the server will be overwritten
+when pushing changes to the ``gitosis-admin.git`` repository.
+
+Edit the settings as you wish, commit and push. That's pretty much it!
+Once you push, ``gitosis`` will immediately make your changes take
+effect on the server.
+
+
+Managing it
+===========
+
+To add new users:
+
+- add a ``keys/USER.pub`` file
+- authorize them to read/write repositories as needed (or just
+  authorize the group ``@all``)
+
+To create new repositories, just authorize writing to them and
+push. It's that simple! For example: let's assume your username is
+``jdoe`` and you want to create a repository ``myproject``.
+In your clone of ``gitosis-admin``, edit ``gitosis.conf`` and add::
+
+	[group myteam]
+	members = jdoe
+	writable = myproject
+
+Commit that change and push. Then create the initial commit and push
+it::
+
+	mkdir myproject
+	git init
+	git remote add myserver git@MYSERVER:myproject.git
+	# do some work, git add and commit files
+	git push myserver master:master
+
+That's it. If you now add others to ``members``, they can use that
+repository too.
+
+
+Example configuration
+=====================
+
+.. include:: example.conf
+   :literal:
 
-make git hook: update authorized_keys
 
-make git hook: update config file
+Contact
+=======
 
-git-daemon-export-ok
+You can email the author at ``tv@eagain.net``, or hop on
+``irc.freenode.net`` channel ``#git`` and hope for the best.
 
+There will be more, keep an eye on http://eagain.net/ and/or the git
+mailing list.