--- a/README	Mon Apr 21 12:37:56 2008 +0100
+++ b/README	Tue Apr 22 09:46:29 2008 +0100
@@ -53,6 +53,10 @@
 hook in this repository re-runs "refresh-auth" on the most recent
 version after every push.
 
+Finally, a hook in an extension is run for each changeset that is
+remotely committed, which uses the rules file to determine whether to
+allow the changeset.
+
 GETTING STARTED
 
 This is only one setup - it can be tweaked in many ways, and is as
@@ -79,10 +83,10 @@
    mkdir -p admin repos/hgadmin/keys/admin .ssh
    cd admin
    hg clone http://hg.opensource.lshift.net/hg-admin-tools
-   cp hg-admin-tools/hg-ssh-wrapper ~
+   cp hg-admin-tools/hg-ssh-wrapper hg-admin-tools/remote-hgrc ~
    cd ../repos/hgadmin
    hg init .
-   echo "init admin/* *" > hg-ssh-access.conf
+   echo "init user=admin/*" > hg-ssh-access.conf
    cp /tmp/my-ssh-public-key keys/admin/myname
    hg add
    hg commit -m "initial commit"
@@ -105,7 +109,8 @@
 editing hg-ssh-access.conf.  Changes will take effect as soon as you
 push them to "ssh://hg@repository-host/hgadmin".
 
-Users authorized to do so can now also create new repositories on this host with "clone":
+Users authorized to do so can now also create new repositories on this
+host with "clone":
 
   hg clone . ssh://hg@repository-host/my-project-name
 
@@ -113,15 +118,63 @@
 
 Each line of hg-ssh-access.conf has the following syntax:
 
-<rule> <keypattern> <repositorypattern>
+<rule> <condition> <condition> ...
+
+Rule is one of
+
+init - allow any operation, including the creation of new repositories
+write - allow reads and writes to this file in this repository
+read - allow the repo to be read but reject matching writes
+deny - deny all requests
+
+A condition is a globpattern matched against a relative path, one of:
+
+user=<globpattern> - user's key
+repo=<globpattern> - repo (as the user supplies it)
+file=<globpattern> - file in the repo
+
+The first rule in the file which has all its conditions satisfied is
+used to determine whether an action is allowed.
+
+Paths cannot contain any special characters except "/"; glob patterns
+cannot contain any special characters except "/" and "*".  "*" matches
+zero or more characters not including "/" while "**" matches zero or
+more characters including "/".
+
+Blank lines and lines that start with "#" are ignored.
+
+FILE CONDITIONS
+
+The rules file is used to make three decisions:
 
-The "rule" is either "init", "allow", or "deny".  "keypattern" is a
-glob pattern matched against the name of the key used - for example,
-in our initial setup "admin/myname" matches "admin/*".
-"repositorypattern" is a pattern matched againt the repository name -
-so "hgadmin" matches "*".  Only boring characters are allowed in
-patterns and key and repository names - see the source for details.
-Blank lines and lines that start with "#" are ignored.  The first rule
-to match both the key and the repository applies: "deny" will deny all
-matching requests, "allow" allows read/write access to existing
-repositories, and "init" allows that and creation of new repositories.
+- Whether to allow a repository to be created
+- Whether to allow access to a repository
+- Whether to allow a changeset to change a particular file
+
+When the first two of these decisions are being made, nothing is known
+about what files might be changed, and so all file conditions
+automatically succeed for the purpose of such decisions.  This means
+that doing tricky things with file conditions can have
+counterintuitive consequences:
+
+- You cannot limit read access to a subset of a repository with a
+"read" rule and a file condition: any user who has access to a
+repository can read all of it and its full history.  Such a rule can
+only have the effect of masking a later "write" rule, as in this
+example:
+
+   read repo=specialrepo file=dontwritethis
+   write repo=specialrepo
+
+allows all users to read specialrepo, and to write to all files
+*except* that any changeset which writes to "dontwritethis" will be
+rejected.
+
+- For similar reasons, don't give "init" rules file conditions.
+
+THANKS
+
+Thanks for reading this far.  If you use hg-admin-tools, please tell
+me about it.
+
+Paul Crowley, 2008