basic access control

Here's a very basic set of rules:

repo    gitolite-admin
        RW+     =   sitaram

repo    testing
        RW+     =   @all

repo    gitolite simplicity
        RW+     =   sitaram dilbert
        RW      =   alice ashok
        R       =   wally

It should be easy to guess what most of this means:

R means "read" permission
RW means "read and write", but no rewind
RW+ means "read and write", with rewind allowed

A "rewind" is more often called a "non-fast forward push"; see git docs for what that is. The + was chosen because it is part of the "git push" syntax for non-ff pushes.

Note that tags are generally considered "write once", so they are treated specially by gitolite: you need rewind permission (RW+) to overwrite a tag with a new value.

In a later section you'll see some more advanced permissions.

how rules are matched

It's important to understand that there're two levels at which access control happens. Please see this for details, especially about the first level check. Much of the complexity applies only to the second level check, so that is all we will be discussing here. This check is done by the update hook, and determines whether the push succeeds or fails.

For basic permissions like this, matching is simple. Gitolite already knows:

the user
the repo
the branch or tag ("ref") being pushed
whether it is a normal (ff) push or a rewind (non-ff) push.

Gitolite goes down the list of rules matching the user, repo, and the ref. The first matching rule that has the permission you're looking for (W or +), results in success. A fallthrough results in failure.

branches, tags, and specifying "refex"es

One of the original goals of gitolite was to allow access control at the branch/tag (aka "ref") level. The git source code contains a sample update hook that has the following in it:

# from Documentation/howto/update-hook-example.txt:

refs/heads/master       junio
+refs/heads/pu          junio
refs/heads/cogito$      pasky
refs/heads/bw/.*        linus
refs/heads/tmp/.*       .*
refs/tags/v[0-9].*      junio

If you did this in gitolite, this is what the equivalents would be:

repo    git
        RW      master$             =   junio   # line 1
        RW+     pu$                 =   junio   # line 2
        RW      cogito$             =   pasky   # line 3
        RW      bw/                 =   linus   # line 4
        RW      tmp/                =   @all    # line 5
        RW      refs/tags/v[0-9]    =   junio   # line 6

The following points will help you understand these rules. (Git recap: branches and tags together are called "ref"s in git. A branch ref usually looks like "refs/heads/foo", while a tag ref looks like "refs/tags/bar")

the general syntax of a paragraph of rules is:

# start line:
repo [one or more repos and/or repo groups]
# followed by one or more permissions lines:
[permission] [zero or more refexes] = [one or more users]

a refex is a perl regex that matches a ref. When you try to push a commit to a branch or a tag, that "ref" is matched against the refex part of each rule.
if the refex does not start with refs/, gitolite assumes a prefix of refs/heads/. This is useful because branch matching is the most common case, as you can see this applies to lines 1 through 5 here.
if no refex appears, the rule applies to all refs in that repo (as if you had specified refs/.* as the refex).
refexes are prefix-matched (they are internally anchored with ^ before being used). This means only the beginning of the actual ref needs to match the refex, unless the refex has an explicit $ meta-character at the end (like the first 3 lines in our example do).

Line 5, for instance, allows anyone to push a branch inside the "tmp/" namespace, while line 6 provides the ability to push version tags; "v1", "v1.0", "v2.0rc1", all match the criterion specified by v[0-9] because this is a prefix match only.

groups

Gitolite allows you to define groups of repos. users, or even refexes. A group is semantically (but not syntactically) like a #define in C. Here is an example of each kind:

@oss_repos  =   gitolite linux git perl rakudo entrans vkc
@staff      =   sitaram some_dev another-dev
@important  =   master$ QA_done refs/tags/v[0-9]

The syntax of a group definition is simply:

@groupname = [one or more names]

A group can accumulate values. For example:

@staff      =   sitaram some_dev another-dev
@staff      =   au.thor

is the same as

@staff      =   sitaram some_dev another-dev au.thor

This is more convenient than continuation lines, because it allows you to add to a group anywhere. Many people generate their gitolite.conf itself from some other database, and it is very useful to be able to do this sort of thing.

Groups can include other groups, and the included group will be expanded to whatever value it currently has:

@staff      =   sitaram some_dev another-dev    # line 1
@staff      =   au.thor                         # line 2
@interns    =   indy james                      # line 3
@alldevs    =   bob @interns @staff             # line 4

"@alldevs" expands to 7 names now. However, remember that the config file is parsed in a single-pass, so later additions to a group name cannot affect earlier uses of it. If you moved line 2 to the end, "@alldevs" would only have 6 names in it.

the special `@all` group

There's a special group called @all that includes all authenticated users when used as a username; you've seen examples of it earlier.

Advanced users: also see the entry for GL_ALL_INCLUDES_SPECIAL in the documentation for ~/.gitolite.rc.

When used as a reponame, it includes all repos physically present in ~/repositories (or whatever is the value of $REPO_BASE).