how it actually works

This section tells you what is happening inside gitolite so you can understand this feature better. Let's use the config example at the beginning of this document:

repo    assignments/CREATOR/a[0-9][0-9]
    C   =   @students
    RW+ =   CREATOR
    RW  =   WRITERS @TAs
    R   =   READERS @prof

First we find the set of rules to apply. This involves replacing the special words CREATOR, WRITERS, and READERS with appropriate usernames to derive an "effective" ruleset for the repo in question.

For a new repo, replace the word CREATOR in all repo patterns and rules with the name of the invoking user.

(Note: this is why you should never use C = CREATOR; it becomes C = invoking_user! Unless you really want to allow all users to create repos, you should restrict "C" perms to an actual user or set of users, like in the examples in this document).

For an existing repo, do the same but replace with the name of the user who actually created the repo (this name is recorded in a special file in the repo directory when the repo is first created, so it is available).

Now find a repo pattern that matches the actual reponame being pushed -- this tells you which set of rules to apply. There can be multiple matches; if so, they will all be applied in the sequence they appear in the config file.

If the invoking user has been given the "WRITERS" role using setperms, all permissions for the the user WRITERS are given to the invoking username (and similarly for READERS).

At this point we have an effective ruleset, and the normal access rules (R, RW, etc) apply, with the addition that the invoking user needs "C" access to be able to create a repo.

(Note: "C" rights do not automatically give the CREATOR any other rights; they must be specifically given. RW+ = CREATOR is recommended in most situations, as you can see in our example).

Assuming user "u4" trying to push-create a new repo called assignments/u4/a23, this is what the effective ruleset looks like:

repo    assignments/u4/a23
    C   =   @students
    RW+ =   u4
    RW  =   @TAs
    R   =   @prof

If u4 gives u5 the "WRITERS" role using setperms, and u5 tries to access that repo, the ruleset looks like:

repo    assignments/u4/a23
    C   =   @students
    RW+ =   u4
    RW  =   u5 @TAs
    R   =   @prof

I hope that helps.