example.conf got lots more comments (aka documentation!)

example.conf

@@ -1,6 +1,9 @@
 # example conf file for gitosis-lite
 
-# comments in the normal shell-ish style; no surprises there
+# overall syntax:
+#     - everything in this is space-separated; no commas, semicolons, etc
+#     - comments in the normal shell-ish style; no surprises there
+#     - there are no continuation lines of any kind
 
 # objectives, over and above gitosis:
 #     - simpler syntax
@@ -9,51 +12,61 @@
 #     - allows branch level control
 
 # ----------------------------------------------------------------------------
-# user groups; syntax:
+# USERS and GROUPS
+
+# syntax:
 #   @groupname = username [...]
-# too many users?  just add more such lines
+
+# usernames and groupnames should be as simple as possible; there's no
+# explicit list of allowed characters for now but that's a TODO item.
+
+# too many users in one group?  just add more such lines
 # (they accumulate, like squid ACLs)
 
-@customers = cust1 cust2
-@customers = cust99
+@cust_A = cust1 cust2
+@cust_A = cust99
 @interns = indy james
 @staff = me alice
-# you can nest groups; they'll be fully expanded in actual use
+
+# you can nest groups, but not recursively of course!
 @staff = bob @interns
 @secret_staff = bruce whitfield martin
 
 # ----------------------------------------------------------------------------
-# each section pertains to one or more repo(s); syntax:
-#   repo reponame [...]
-#   (R|RW|RW+) [list of ref names] = [list of users]
+# REPOS, REFS, and PERMISSIONS
+
+# syntax:
+#   repo [one or more reponames]
+#   (R|RW|RW+) [zero or more refnames] = [one or more users]
+
+# notes:
 
 #     - RW+ means non-ff push is allowed
-#     - if no ref name exists, the rule applies to all refs
+#     - 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
-#         - suffixed by "$"
 #         - prefixed by "refs/heads/" if it doesn't start with "refs/"
 #           (i.e., tags have to be explicitly named as refs/tags/pattern)
 
-#     - the order of entries matters: the first ref+action line (for the repo)
-#       that matches is what counts.  If the user is listed, the action is
-#       allowed, otherwise it is rejected.
-
-#     - list of users can use any group name defined earlier
+#     - the list of users can inlude any group name defined earlier
 #     - "@all" is a special, predefined, groupname
 
-# anyone can play in the sandbox
+# anyone can play in the sandbox, including making non-fastforward commits
+# (that's what the "+" means)
 repo sandbox
     RW+     = @all
 
 # my repo and alice's repo have the same memberships and access, so we just
-# club them
+# put them both in the same stanza
 repo myrepo alicerepo
     RW+     = me  alice
     R       = bob  eve
 
-repo custrepo
-    RW      = @customers
-    R       = @staff
+# this repo is visible to customers from company A but they can't write to it
+repo cust_A_repo
+    R       = @cust_A
+    RW      = @staff
 
 # idea for the tags syntax shamelessly copied from git.git
 # Documentation/howto/update-hook-example.txt :)
@@ -61,5 +74,6 @@ repo secret
     RW+ pu                  = bruce
     RW master next          = bruce
     RW refs/tags/v[0-9].*   = bruce
+    RW refs/tags/           = @secret_staff
     RW tmp/.*               = @secret_staff
     R                       = @secret_staff