From 5415b425e765896971bafb66eae67ab928ac0868 Mon Sep 17 00:00:00 2001
From: Sitaram Chamarty <sitaram@sita-lt.atc.tcs.com>
Date: Wed, 16 Sep 2009 19:52:03 +0530
Subject: [PATCH] example conf, doc/3: explain refexes

---
 conf/example.conf      | 20 +++++++++++++++-----
 doc/3-faq-tips-etc.mkd | 12 ++++++++----
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/conf/example.conf b/conf/example.conf
index 86fdeca..14c6817 100644
--- a/conf/example.conf
+++ b/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
-#     - ref names are perl regex patterns
-#         - prefixed by "refs/heads/" if it doesn't start with "refs/"
-#           (i.e., tags have to be explicitly named as refs/tags/pattern)
+#     - a refex is a regex that matches a ref :-)  If you see the examples
+#       below you'll get it easy enough
+
+#     - 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
diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd
index 595d938..465959c 100644
--- a/doc/3-faq-tips-etc.mkd
+++ b/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"
-permissions come into play.
+whether it's a rewind or not).  This is where the "per-branch" permissions
+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