[PATCH 3 of 4] acl: user docs for the "!" prefix in user or group names

[elifarley at gmail.com]

# HG changeset patch
# User Elifarley Callado Coelho Cruz
# Date 1338425271 10800
# Node ID 82e85f53b37f020a2bc5eb35511b5c8518ef2c29
# Parent  d2e0d6775893b8509ba0e44ee9a8604a9ec96863
acl: user docs for the "!" prefix in user or group names

diff --git a/hgext/acl.py b/hgext/acl.py
--- a/hgext/acl.py
+++ b/hgext/acl.py
@@ -46,6 +46,9 @@
 - a comma-separated list containing users and groups, or
 - an asterisk, to match anyone;
 
+You can add the "!" prefix to a user or group name to invert the sense
+of the match.
+
 Path-based Access Control
 .........................
 
@@ -146,6 +149,46 @@
 
   .hgtags = release_engineer
 
+Examples using the "!" prefix
+.............................
+
+Suppose there's a branch that only a given user (or group) should be able to
+push to, and you don't want to restrict access to any other branch that may
+be created.
+
+The "!" prefix allows you to prevent anyone except a given user or group to
+push changesets in a given branch or path.
+
+In the examples below, we will:
+1) Deny access to branch "ring" to anyone but user "gollum"
+2) Deny access to branch "lake" to anyone but members of the group "hobbit"
+3) Deny access to a file to anyone but user "gollum"
+
+::
+
+  [acl.allow.branches]
+  # Empty
+
+  [acl.deny.branches]
+
+  # 1) only 'gollum' can commit to branch 'ring';
+  # 'gollum' and anyone else can still commit to any other branch.
+  ring = !gollum
+
+  # 2) only members of the group 'hobbit' can commit to branch 'lake';
+  # 'hobbit' members and anyone else can still commit to any other branch.
+  lake = !@hobbit
+
+  # You can also deny access based on file paths:
+
+  [acl.allow]
+  # Empty
+
+  [acl.deny]
+  # 3) only 'gollum' can change the file below;
+  # 'gollum' and anyone else can still change any other file.
+  /misty/mountains/cave/ring = !gollum
+
 '''
 
 from mercurial.i18n import _