Format of rules files for Gitano
--------------------------------

Gitano adminsters rules at various levels.  For example they define what users
and groups have access to each repository, what paths and what branches within
that repository.

Apart from the core rules file in the admin repository, whose purpose it is to
provide a set of core rules in case everything else goes wrong, the rules files
are always stored in the refs/gitano/admin branch in the repositories in
question.

The rules file for a repository will be rewritten by Gitano on the server side
(and possibly by Gitano or users on the client side) and as such any comments
or non-standard structures will end up elided during parse/rewrite.  Do not
expect to store commentary in the rules files which are stored in the
refs/gitano/admin branch.

Rules files are essentially Lua scripts which a very tight syntax.  They have
no access to any of the loaded modules, nor to any of the normal function such
as pairs etc.  Instead a limited set of functions are provided which are meant
to form a simple DSL for describing rules.

Rules files are processed from top to bottom and produce a sequence of rules
which are then amalgamated into the ruleset considered for any given operation
being requested by a user.

Example rules file for myfrobbler:

---8<-----
GrantFFWrite(Branch "master", User "myfrobbler-pqm")

DenyWrite(Branch "master", User "gitano/any")

GrantWrite(Branch "devs/$USER/**", Group "myfrobbler-devs")
---8<-----

The first statement allows the myfrobbler-pqm user (probably a robotic merge
tool) to push to the master branch, but only by fast-forward.

The second statement denies all other writes to the master branch.

The third statement grants write access (including forced-push and branch
deletion) to any branch whose name is devs/$USER/** (the $USER means calling
username) to anyone in the group myfrobbler-devs

Without the second statement, the owner of the repository would still have
implicit write access to the master branch.  While the owner would be able to
alter the rules to re-enable their access, this kind of rule is a helpful
preventative measure so that they don't accidentally push to master without
their patch robot getting to run tests.  [See rules-evaluation for more]

Note: If you grant any kind of write to a branch then you are also granting
read access to the entire repository.