gitolite/README.mkd
Sitaram Chamarty 536e3198bf doc fixes...
- README: add a "what" section first, plus a few minor fixes
  - doc/5:
      - remove reference to obsolete ml branch URL; point it to the right
        place with the right section name
      - change text to reflect the fact that p-t-a is now the default!
2009-10-14 14:09:34 +05:30

106 lines
4.3 KiB
Markdown

# 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:
* what
* why
* extra features
* security
* contact and license
----
### what
Gitolite allows a server to host many git repositories and provide access to
many developers, without having to give them real userids on the server. The
essential magic in doing this is ssh's pubkey access and the `authorized_keys`
file, and the inspiration was an older program called gitosis.
Gitolite can restrict who can read from (clone/fetch) or write to (push) a
repository. It can also restrict who can push to what branch or tag, which is
very important in a corporate environment. Gitolite can be installed without
requiring root permissions, and with no additional software than git itself
and perl. It also has several other neat features described below and
elsewhere in the `doc/` directory.
### 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 below) had to be written anyway
All of this pointed to a rewrite. In perl, naturally :-)
### extra features
The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and 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