gitolite/README.mkd

# gitolite

>   [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
>   please read if upgrading gitolite]

>   [Update 2009-10-10: apart from all the nifty new features, there's now an
>   "easy install" script in the src directory.  Please see the INSTALL
>   document in the doc directory for details]

----

Gitolite is a rewrite of gitosis, with a completely different config file that
allows (at last!) access control down to the branch level, including
specifying who can and cannot *rewind* a given branch.

In this document:

  * why
  * what's extra
  * security
  * contact and license

----

### why

I have been using gitosis for a while, and have learnt a lot from it.  But in
a typical $DAYJOB setting, there are some issues:

  * it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get)
    and be done
  * often, "python-setuptools" isn't installed (and on a Solaris9 I was trying
    to help remotely, we never did manage to install it eventually)
  * you don't have root access, or the ability to add users (this is also true
    for people who have just one userid on a hosting provider)
  * the most requested feature (see "what's new?") had to be written anyway

All of this pointed to a rewrite.  In perl, naturally :-)

### what's extra

**Per-branch permissions**.  You will not believe how often I am asked this at
$DAYJOB.  This is almost the single reason I started *thinking* about rolling
my own gitosis in the first place.

It's not just "read-only" versus "read-write".  Rewinding a branch (aka "non
fast forward push") is potentially dangerous, but sometimes needed.  So is
deleting a branch (which is really just an extreme form of rewind).  I needed
something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).

Here're **some more features**.  All of them are documented in detail
somewhere in the `doc/` subdirectory.

  * simpler, yet far more powerful, config file syntax, including specifying
    gitweb/daemon access.  You'll need this power if you manage lots of users
    + repos + combinations of access
  * config file syntax gets checked upfront, and much more thoroughly
  * if your requirements are still too complex, you can split up the config
    file and delegate authority over parts of it
  * more comprehensive logging [aka: management does not think "blame" is just
    a synonym for "annotate" :-)]
  * "personal namespace" prefix for each dev
  * migration guide and simple converter for gitosis conf file
  * "exclude" (or "deny" rights in the config file) -- this is the "rebel"
    branch in the repository, and always will be ;-)

### security

Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one.  The code is
very small and easily reviewable -- the 2 programs that actually control
access when a user logs in total about 200 lines of code (about
80 lines according to "sloccount").

For the first person to find a security hole in it, defined as allowing a
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
that the config file says he shouldn't, and caused by a bug in *code* that is
in the "master" branch, (not in the other branches, or the configuration file
or in Unix, perl, shell, etc.)...  well I can't afford 1000 USD rewards like
djb, so you'll have to settle for 1000 INR (Indian Rupees) as a "token" prize
:-)

----

### contact and license

Gitolite is released under GPL v2.  See COPYING for details.

sitaramc@gmail.com