gitolite/README.mkd

# main README file for gitolite -- start here!

<a name="start"></a>

***IMPORTANT NOTE: There is a [master table of contents of all gitolite
documentation][docs] that can help if you're looking for stuff.  Just click
the link and use your browser's search function (Ctrl-F, usually) to look for
likely sounding words.  All documents are listed, as well as links to section
headers in some of the longer documents***

[docs]: http://sitaramc.github.com/gitolite

----

Gitolite is an access control layer on top of git, which allows access control
down to the branch level, including specifying who can and cannot *rewind* a
given branch.

Gitolite comes with a **huge** amount of documentation.  If you're absolutely
new, the suggested reading order is this:

  * the README (this document) for a quick intro
  * the [INSTALL][install] document
  * the [ADMIN][admin] document

If you run into trouble start [here](#support).  If you're migrating from
gitosis, read [this][migr].

And [here][who]'s some information on some of the projects and people using
gitolite (and who, in turn, have helped shape its features).

Once you've installed it and started using it, you'll want to explore some of
the more powerful features.  **The documentation is best read [online
here][docs] or you can read it in your clone's `doc/` directory**.  All the
longer documents have tables of contents, so you can quickly get a feel for
what is covered right at the top.

----

In this document:

  * <a href="#_what">what</a>
  * <a href="#_why">why</a>
  * <a href="#_main_features">main features</a>
  * <a href="#_support">support</a>
  * <a href="#_security">security</a>
  * <a href="#_contact_and_license">contact and license</a>

----

<a name="_what"></a>

### what

Gitolite lets you use a single user on a server to host many git repositories
and provide access to many developers, without having to give them real
userids on or shell access to 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/][docs] directory.

<a name="_why"></a>

### why

Gitolite is separate from git, and needs to be installed and configured.  So...
why do we bother?

Gitolite is useful in any server that is going to host multiple git
repositories, each with many developers, where some sort of access control is
required.

In theory, this can be done with plain old Unix permissions: each user is a
member of one or more groups, each group "owns" one or more repositories, and
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
allow/disallow users access to repos.

But there are several disadvantages here:

  * every user needs a userid and password on the server.  This is usually a
    killer, especially in tightly controlled environments
  * adding/removing access rights involves complex `usermod -G ...` mumblings
    which most admins would rather not deal with
  * *viewing* (aka auditing) the current set of permissions requires running
    multiple commands to list directories and their permissions/ownerships,
    users and their group memberships, and then correlating all these manually
  * auditing historical permissions or permission changes is pretty much
    impossible without extraneous tools
  * errors or omissions in setting the permissions exactly can cause problems
    of either kind: false accepts or false rejects
  * without going into ACLs it is not possible to give someone read-only
    access to a repo; they either get read-write access or no access
  * it is absolutely impossible to restrict pushing by branch name or tag
    name.

Gitolite does away with all this:

  * it uses ssh magic to remove the need to give actual unix userids to
    developers
  * it uses a simple but powerful config file format to specify access rights
  * access control changes are affected by modifying this file, adding or
    removing user's public keys, and "compiling" the configuration
  * this also makes auditing trivial -- all the data is in one place, and
    changes to the configuration are also logged, so you can audit them.
  * finally, the config file allows distinguishing between read-only and
    read-write access, not only at the repository level, but at the branch
    level within repositories.

<a name="_main_features"></a>

### main 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 writing gitolite.

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, and more, are documented in
detail somewhere in gitolite's [doc/][docs] subdirectory.

  * simple, yet powerful, config file syntax, including specifying
    gitweb/daemon access.  You'll need this power if you manage lots of
    users+repos+combinations of access
  * apart from branch-name based restrictions, you can also restrict by
    file/dir name changed (i.e., output of `git diff --name-only`)
  * if your requirements are still too complex, you can split up the config
    file and delegate authority over parts of it
  * easy to specify gitweb owner, description and gitweb/daemon access
  * easy to sync gitweb (http) authorisation with gitolite's access config
  * 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 at the branch/tag level
  * specify repos using patterns (patterns may include creator's name)
  * define powerful operations on the server side, even github-like forking

<a name="support"></a>

<a name="_support"></a>

### support

Most installation problems are caused by not knowing ssh.  Take a look at this
[transcript][] to see how simple it actually is, if your server's ssh daemon
is behaving itself.  Someone also wrote a tutorial, see [here][tut].

If I suspect your problem is an ssh issue, I will probably ignore it.  Please
learn how [gitolite uses ssh][doc9gas] and then methodically go through the
[ssh trouble shooting][doc6sts] document.  These two documents contain
everything I could possibly tell you.  I have nothing to add.

Even for other topics, please look through at least the table of contents of
at least the numbered documents to see if your question is already answered,
before asking.

<a name="_security"></a>

### 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.

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 5000 INR (Indian Rupees) as a "token" prize
:-)

However, there are a few optional features (which must be explicitly enabled
in the RC file) where I just haven't had the time to reason about security
thoroughly enough.  Please read the comments in `conf/example.gitolite.rc` for
details, looking for the word "security".

----

<a name="_contact_and_license"></a>

### contact and license

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

  * author: sitaramc@gmail.com, sitaram@atc.tcs.com
  * mailing list: gitolite@googlegroups.com
  * list subscribe address : gitolite+subscribe@googlegroups.com

[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
[admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
[migr]: http://sitaramc.github.com/gitolite/doc/migrate.html
[doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
[doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
[who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial