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:
parent
a45d2d9912
commit
6a44c564a2
|
@ -28,6 +28,7 @@ In this document:
|
|||
* setting a gitweb description for a wildcard-matched repo
|
||||
* reporting
|
||||
* other issues and discussion
|
||||
* how it actually works
|
||||
|
||||
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/
|
||||
warning: You appear to have cloned an empty repository.
|
||||
|
||||
Notice the *two* empty repo inits, and the order in which they occur ;-) Now
|
||||
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
|
||||
Notice the *two* empty repo inits, and the order in which they occur ;-)
|
||||
|
||||
#### 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
|
||||
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:
|
||||
|
|
Loading…
Reference in a new issue