diff --git a/doc/wildcard-repositories.mkd b/doc/wildcard-repositories.mkd
index 974455e..2c7241f 100644
--- a/doc/wildcard-repositories.mkd
+++ b/doc/wildcard-repositories.mkd
@@ -8,19 +8,13 @@ created it, allowing him/her to hand out R and RW permissions to other users
to collaborate, all these are possible. And any of these could have a bug in
it. I haven't found any yet, but that doesn't mean there aren't any.
-Also, there are some limitations. For example, you cannot specify gitconfig
-values for a wildcard repo; it only works for actual repos.
-
-There may be other such missing features. Sometimes it's just not possible to
-make it work. Or it may be cumbersome enough that unless there are *no*
-workarounds I may not have the time to code it right away.
-
----
In this document:
+ * quick introduction
* rc file setting required
- * wildcard repos
+ * examples of wildcard repos
* wildcard repos with creator name in them
* wildcard repos without creator name in them
* side-note: line-anchored regexes
@@ -28,7 +22,6 @@ In this document:
* handing out rights to wildcard-matched repos
* setting a gitweb description for a wildcard-matched repo
* reporting
- * other issues and discussion
* how it actually works
----
@@ -37,6 +30,16 @@ This document is mostly "by example".
----
+
+
+### quick introduction
+
+The wildrepos feature allows you to specify access control rules using regular
+expression patterns, so you can have many actual repos being served by a
+single set of rules in the config file. The regex pattern can also include
+the word `CREATOR` in it, allowing you to parametrise the name of the user
+creating the repo. The examples below will make this clearer.
+
### rc file setting required
@@ -45,13 +48,24 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this.
-
+
-### wildcard repos
+### examples of wildcard repos
+
+As the introduction said, you can include the word `CREATOR` in the regex
+pattern, though it is not mandatory. We'll look at examples of both types of
+usage.
Which of these alternatives you choose depends on your needs, and the social
-aspects of your environment. The first one is a little more rigid, making it
-harder to make mistakes, and the second is more flexible and trusting.
+aspects of your environment. Including the creator name in the pattern keeps
+users rigidly separated from each others repos, and is good for a largely
+autonomous collection of users with a high probability of repo name clashes.
+
+Omitting the creator name from the pattern puts the repos in a common
+namespace, and is suitable for environments where it is not very important to
+keep track of who actually created the repo (except for granting access), but
+needs more communication / co-operation among the users to avoid repo name
+clashes.
@@ -196,28 +210,6 @@ commands, thanks to Teemu.
In order to see what repositories were created from a wildcard, use the
"expand" command, described briefly in [doc/report-output.mkd][repout].
-
-
-### other issues and discussion
-
- * *what if the repo name being pushed matches more than one pattern*?
-
- I think it would be very hard to reason about access if we were to do
- something like combine all the access rights in all the matching patterns.
- No matter how you do it, and how carefully you document it, there'll be
- someone who is surprised by the result.
-
- And in security, that's a ***Bad Thing***.
-
- So we don't combine permissions. At runtime, we die if we find more than
- one match. Let 'em go holler at the admin for creating multiple matching
- repo patterns :-)
-
- This can make some repos inaccessible if the patterns changed *after* they
- were created. The administrator should be careful not to do this. Most
- 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
@@ -249,8 +241,8 @@ 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.
+tells you which set of rules to apply. There can be multiple matches; if so,
+they will all be applied in the sequence they appear in the config file.
If the invoking user has been given "RW" permissions using `setperms`, all
occurrences of the word WRITERS are replaced by the invoking username.