example conf, doc/3: explain refexes

conf/example.conf

@@ -43,7 +43,7 @@
 
 # syntax:
 #   repo [one or more repos]
-#   (R|RW|RW+) [zero or more refnames] = [one or more users]
+#   (R|RW|RW+) [zero or more refexes] = [one or more users]
 
 # notes:
 
@@ -53,15 +53,25 @@
 #     - RW+ means non-ff push is allowed
 #     - you can't write just "W" or "+"; it has to be R, or RW, or RW+
 
-#     - if no ref name appears, the rule applies to all refs in that repo
+#     - a refex is a regex that matches a ref :-)  If you see the examples
-#     - ref names are perl regex patterns
+#       below you'll get it easy enough
-#         - prefixed by "refs/heads/" if it doesn't start with "refs/"
+
-#           (i.e., tags have to be explicitly named as refs/tags/pattern)
+#     - refexes are specified in perl regex syntax
+#     - if no refex appears, the rule applies to all refs in that repo
+#     - a refex is automatically prefixed by "refs/heads/" if it doesn't start
+#       with "refs/" (so tags have to be explicitly named as
+#       refs/tags/pattern)
 
 #     - the list of users or repos can inlude any group name defined earlier
 #     - "@all" is a special, predefined, groupname that means "all users"
 #       (there is no corresponding shortcut for all repos)
 
+# matching:
+
+#     - user, repo, and access (W or +) are known.  For that combination, if
+#       any of the refexes match the refname being updated, the push succeeds.
+#       If none of them match, it fails
+
 # anyone can play in the sandbox, including making non-fastforward commits
 # (that's what the "+" means)
 repo sandbox

doc/3-faq-tips-etc.mkd

@@ -10,7 +10,7 @@ In this document:
       * error checking the config file
       * one user, many keys
       * who am I?
-  * cool ideas I want feedback on
+  * other cool things
       * developer specific branches
 
 ### common errors and mistakes
@@ -117,8 +117,12 @@ only `R` (read access) don't count.  *The user must have write access to
 The **second check** is via a git `update hook`.  This check only happens for
 write operations.  By this time we know what "ref" he is trying to update, as
 well as the old and the new SHAs of that ref (by which we can also deduce
-whether it's a fast forward or not).  This is where the "per-branch"
+whether it's a rewind or not).  This is where the "per-branch" permissions
-permissions come into play.
+come into play.
+
+Each refex that allows `W` access (or `+` if this is a rewind) for *this*
+user, on *this* repo, is matched against the actual refname being updated.  If
+any of the refexes match, the push succeeds.  If none of them match, it fails.
 
 #### error checking the config file
 
@@ -188,7 +192,7 @@ In gitolite, it's simple: just ask nicely :-)
     PTY allocation request failed on channel 0
     no SSH_ORIGINAL_COMMAND?  I'm not a shell, sitaram!
 
-### cool ideas
+### other cool things
 
 #### developer specific branches