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

thanks to Ilari for helping fix a bug (see previous commit) and then
prompting this documentation

doc/4-wildcard-repositories.mkd

@@ -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
+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
 
@@ -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: