Update documentation in preparation of release.

3 files changed, 214 insertions, 15 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.
diff --git a/TODO.rst b/TODO.rst
index 4e96501..fb96fe8 100644
--- a/TODO.rst
+++ b/TODO.rst
@@ -2,6 +2,15 @@
  TODO list
 ===========
 
+- let me have ~git{,/repositories} owned by root:root
+
+- gitosis-lint: check that the user account (e.g. ``git``) looks valid
+
+- gitosis-create-repositories: create repos mentioned in config if
+  they don't exist
+
+- git-daemon-export-ok
+
 - guard against *.pub files named -foo.pub or foo;bar.pub
 
 - gitweb doesn't understand mappings, just visible/no,
@@ -9,10 +18,49 @@
 
   - maybe remove the whole mapping feature for good?
 
+  - maybe create symlink trees to make mappings visible in filesystem?
+
 - use groups somehow to reduce typing for ``gitweb = yes``
 
 - detect when repo actually ends in ``.git`` for ``projects.list``
   (otherwise gitweb won't see it)
 
+- unit test projects.list generation in run-hook
+
 - ConfigParser does not guarantee ordering, rewrite all unit tests to
   assume sorted, fix code to sort
+
+- test with ssh://
+
+- write description to a file, make REPO.git/description symlink to it
+  if it doesn't exist (thus not overwriting local changes)
+
+- gitweb knows about cloneurl, handle like description
+
+- gitweb knows about README.html, figure out how to generate from e.g.
+  README.rst in gitosis.git
+
+- make gitosis-gitweb output a gitweb.conf file too
+
+- need to chgrp repositories www-data to make them accessible by gitweb
+
+- allow using git-cvsserver?
+
+- move from log.foo("bar" % quux) to log.foo("bar",  quux)
+
+- can't trust "~"::
+
+	[0 tv@musti ~]$ sudo python -c 'import os; print os.path.expanduser("~")'
+	/home/tv
+	[0 tv@musti ~]$ sudo -H python -c 'import os; print os.path.expanduser("~")'
+	/root
+
+- command line options
+
+  - gitosis init --repositories=
+  - gitosis init --config= (or whatever the option is elsewhere)
+  - gitosis init --home= (for testing)
+  - gitosis init --admin=username[@host]
+
+- gitosis-run-hook has to be in PATH and PYTHONPATH before you can
+  push to gitosis-admin.git
diff --git a/example.conf b/example.conf
index b6654ef..117be5c 100644
--- a/example.conf
+++ b/example.conf
@@ -1,20 +1,50 @@
+# this config file tries to show a bit of everything, most real life
+# configurations really only need a "group" section with "members" and
+# "writable"
+
 [gitosis]
-repositories = repo
+## To override the default ~/repositories path
+# repositories = repositories
+
+## Allow gitweb to show all known repositories. If you want gitweb,
+## you need either this or a [repo foo] section for each repository
+## you want visible in gitweb.
 gitweb = no
+
+## Allow git-daemon to publish all known repositories. As with gitweb,
+## this can be done globally or per-repository.
+## NOT YET IMPLEMENTED.
 # daemon-ok = no
 
+## Logging level, one of DEBUG, INFO, WARNING, ERROR, CRITICAL
+loglevel = DEBUG
+
 [group quux]
 members = jdoe wsmith @anothergroup
 writable = foo bar baz/thud
 readonly = xyzzy
+
+## You can play fancy tricks by making some repositories appear with
+## different names in different contexts. Not really supported
+## everywhere (e.g. gitweb) and can be confusing -- experts only.
 map writable visiblename1 = actualname1
 map readonly visiblename2 = actualname2
 
 [repo foo]
-# description = blah blah
+## Allow gitweb to show this repository.
 gitweb = yes
+
+## Oneline description of the project, mostly for gitweb.
+## NOT YET IMPLEMENTED.
+# description = blah blah
+## Owner of this repository. Used in gitweb list of projects.
 owner = John Doe
+
+## Allow git-daemon to publish this repository.
+## NOT YET IMPLEMENTED.
 # daemon-ok = no
 
-# [gitweb]
+[gitweb]
+## Where to make gitweb link to as it's "home location".
+## NOT YET IMPLEMENTED.
 # homelink = http://example.com/