gitolite/doc/rules.mkd

## #rules access rules

This is arguably the most complex part of day-to-day gitolite.  There are
several interconnected ideas that make this hard to lay out easily if you're
totally new to this, so read carefully.

We will use this as a running example:

    @staff          =   dilbert alice wally bob

    repo foo
        RW+         =   dilbert     # line 1
        RW+ dev     =   alice       # line 2
        -           =   wally       # line 3
        RW  temp/   =   @staff      # line 4
        R           =   ashok       # line 5

### what does a rule look like?

A rule line has the structure

    <permission> <zero or more refexes> = <one or more users/user groups>

The most common permissions used are:

  * R, for read only
  * RW, for push existing ref or create new ref
  * RW+, for  "push -f" or ref deletion allowed (i.e., destroy
    information)
  * `-` (the minus sign), to **deny** access.

There are also other, less commonly used, [types of permissions][write-types].

A refex is an expression that matches the ref (i.e., branch or tag) being
pushed.  See [this][refex] for more info.

### when are the rules checked?

There are 2 places where access rules are checked.

The "pre-git" check is before git is invoked.  Gitolite knows the repo name,
user name, and attempted access (R or W), but no ref name.

The "update" check is only for write operations, and it is just before git
updates a ref.  This time gitolite knows the refname also.

### how are the rules matched?

For the **pre-git check**, any permission that contains "R" matches a read
operation, and any permission that contains "W" matches a write operation.
This is because we simply don't know enough to make finer distinctions at this
point.

In addition, *gitolite ignores deny rules during the pre-git check*.  <font
color="gray">(You can [change this][deny-rules] if you wish, though it's
rarely needed)</font>.  This means line 3 is ignored, and so Wally in our
example will pass the pre-git check.

For the **update check**, git gives us all the information we need.  Then:

  * all the rules for a repo are [accumulated][rule-accum]

  * the rules pertaining to this repo *and* this user (or to a group to which
    they belong, respectively) are kept; the rest are ignored

  * these rules are examined *in the sequence they appeared in the conf file*.
    For each rule:

      * if the ref does not match the [refex][], the rule is skipped
      * if it's a deny rule (the permissions field is a `-`), access is
        **rejected** and the matching stops
      * if the permission field matches the specific [type of
        write][write-types] operation, access is **allowed** and the matching
        stops

  * if no rule ends with a decision, ("fallthru"), access is **rejected**.

Now you need to understand how [refex][] matching happens and how the
permissions match the various [types of write operations][write-types].

Using these, you can see, in our example, that:

  * everyone, even wally, can read the repo.
  * dilbert can push, rewind, or delete any ref.
  * alice can push, rewind, or delete any ref whose name starts with 'dev';
    see [refex][] for details.
  * alice can also push (but not rewind or delete) any ref whose name starts
    with 'temp/'.  This applies to bob also.
  * if it weren't for line 3, the previous statement would apply to wally
    also.

Interestingly, wally can get past the pre-git check because gitolite ignores
deny rules for pre-git, but having got past it, he can't actually do anything.
That's by design, and as I said if you don't like it you can ask gitolite to
[deny at pre-git][deny-rules].

### #perms summary of permissions

The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`.  This expands
to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
`RW+CD`, all but the first two optionally followed by an `M`.  And by now you
know what they all mean.

## additional topics

### #rule-accum rule accumulation

Gitolite was meant to collect rules from multiple places and apply them all.
For example, this:

    repo foo
        RW  =   u1

    @gr1 = foo bar

    repo @gr1
        RW  =   u2
        R   =   u3

    repo @all
        R   =   gitweb

is effectively the same as this, for repo foo:

    repo foo
        RW  =   u1
        RW  =   u2
        R   =   u3
        R   =   gitweb

This extends to patterns also, but I'll leave an example for later.

### #deny-rules applying deny rules during the pre-git check

The access rules section above describes the problem in one scenario.  Here's
another.  Let's say you have this at the end of your gitolite.conf file:

    repo @all
        R   =   gitweb daemon

but you don't want the gitolite-admin repo showing up on gitweb.  How do you
do that?  Here's how:

    repo gitolite-admin
        -   =   gitweb daemon
        option deny-rules = 1

    repo @all
        R   =   gitweb daemon

Note that the order matters; the `-` rule must come *before* the `R` rule.