doc/4: added "how it actually works" section

thanks to Ilari for helping fix a bug (see previous commit) and then
prompting this documentation
This commit is contained in:
Sitaram Chamarty 2010-03-28 12:30:02 +05:30
parent a45d2d9912
commit 6a44c564a2

View file

@ -28,6 +28,7 @@ In this document:
* setting a gitweb description for a wildcard-matched repo * setting a gitweb description for a wildcard-matched repo
* reporting * reporting
* other issues and discussion * other issues and discussion
* how it actually works
This document is mostly "by example". This document is mostly "by example".
@ -61,15 +62,7 @@ new repo, as user "u4" (a student):
Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a12.git/ Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a12.git/
warning: You appear to have cloned an empty repository. warning: You appear to have cloned an empty repository.
Notice the *two* empty repo inits, and the order in which they occur ;-) Now Notice the *two* empty repo inits, and the order in which they occur ;-)
make some changes and push, and after that, that specific repo
(`assignments/u4/a12`) behaves as if the access control looked like this:
# effective config
repo assignments/u4/a12
RW+ = u4
RW = WRITERS @TAs
R = READERS @prof
#### Wildcard repos without creater name in them #### Wildcard repos without creater name in them
@ -215,6 +208,74 @@ Push the config, then try
of the time, it won't be difficult; the fixed prefix will usually be of the time, it won't be difficult; the fixed prefix will usually be
different anyway so there won't be overlaps. different anyway so there won't be overlaps.
### 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/CREATER/a[0-9][0-9]
C = @students
RW+ = CREATER
RW = WRITERS @TAs
R = READERS @prof
First we find the set of rules to apply. This involves replacing the special
words CREATER, WRITERS, and READERS with appropriate usernames to derive an
"effective" ruleset for the repo in question.
For a **new** repo, replace the word CREATER in all repo patterns and rules
with the name of the invoking user.
> (Note: this is why you should never use `C = CREATER`; 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. Only one pattern is allowed to match;
matching more than one is an error.
If the invoking user has been given "RW" permissions using `setperms`, all
occurrences of the word WRITERS are replaced by the invoking username.
Otherwise -- and this includes the "new repo" case, since you couldn't have
run `setperms` on a non-existant repo -- they are replaced by "NOBODY".
(The same thing is done with "R" access and the word "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 CREATER any other rights;
> they must be specifically given. `RW+ = CREATER` 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 (we're
ignoring the "NOBODY" business):
repo assignments/u4/a23
C = @students
RW+ = u4
RW = @TAs
R = @prof
If u4 gives "RW" perms to u5 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.
---- ----
Enjoy, and please use with care. This is pretty powerful stuff. As they say: Enjoy, and please use with care. This is pretty powerful stuff. As they say: