diff --git a/conf/example.conf b/conf/example.conf index 6dcc4e2..6ad91ad 100644 --- a/conf/example.conf +++ b/conf/example.conf @@ -142,10 +142,18 @@ repo git # DENY/EXCLUDE RULES -# ***IMPORTANT NOTE: if you use deny rules, the order of the rules also makes -# a difference, where earlier it did not. Please review your ruleset -# carefully or test it. In particular, do not use `@all` in a deny rule -- it -# won't work as you might expect***. +# ***IMPORTANT NOTES ABOUT "DENY" RULES***: + +# - deny rules do NOT affect read access. They only apply to `W` and `+`. +# +# - when using deny rules, the order of your rules starts to matter, where +# earlier it did not. The first matching rule applies, where "matching" is +# defined as either permitting the operation you're attempting (`W` or `+`), +# which results in success, or a "deny" (`-`), which results in failure. +# (As before, a fallthrough also results in failure). +# +# - do not use `@all` when your config has any deny rules; it won't work as +# you probably expect it to! # in the example above, you cannot easily say "anyone can write any tag, # except version tags can only be written by junio". The following might look @@ -161,10 +169,6 @@ repo git - refs/tags/v[0-9] = linus pasky @others RW refs/tags/ = junio linus pasky @others -# Briefly, the rule is: the first matching refex that has the operation you're -# looking for (`W` or `+`), or a minus (`-`), results in success, or failure, -# respectively. A fallthrough also results in failure - # FILE/DIR NAME BASED RESTRICTIONS # -------------------------------- diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index edc6351..67ef956 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -499,12 +499,9 @@ that code path to better use :-) #### "exclude" (or "deny") rules -***IMPORTANT CAVEAT: if you use deny rules, the order of the rules also makes -a difference, where earlier it did not. Please review your ruleset carefully -or test it. In particular, do not use `@all` in a deny rule -- it won't work -as you might expect***. Also, deny rules are only processed in the second -level checks (see "two levels of access rights checking" above), which means -they only apply to write operations. +Here is an illustrative explanation of "deny" rules. However, please be sure +to read the "DENY/EXCLUDE RULES" section in `conf/example.conf` for important +notes/caveats before using "deny" rules. Take a look at the following snippet, which *seems* to say that "bruce" can write versioned tags (anything containing `refs/tags/v[0-9]`), but the other