--- a/doc/manual.docbook	Wed Oct 14 14:29:39 2009 +0100
+++ b/doc/manual.docbook	Wed Oct 14 14:48:33 2009 +0100
@@ -290,10 +290,97 @@
 while "**" matches zero or more characters including "/".
 </para>
 <section>
-<title>File conditions</title>
+<title>File and branch conditions</title>
+<para>
+mercurial-server supports file and branch conditions, which restrict an
+operation depending on what files it modifies and what branch the work is
+on. </para>
+<caution>
+The way these conditions work is subtle and can be counterintuitive - if
+you want to keep things simple, stick to user and repo conditions, and then
+things are likely to work the way you would expect.
+</caution>
+<para>
+File and branch conditions are added to the conditions against which a rule
+matches, just like user and repo conditions; they have this form:
+</para>
+<itemizedlist>
+<listitem>
+<code><literal>file=</literal><replaceable>globpattern</replaceable></code>: file within the repo
+</listitem>
+<listitem>
+<code><literal>branch=</literal><replaceable>globpattern</replaceable></code>: Mercurial branch name
+</listitem>
+</itemizedlist>
+<para>
+However, in order to understand what effect adding these conditions will
+have, it helps to understand how and when these rules are applied.
+</para>
+<para>
+The rules file is used to make three decisions:
+</para>
+<itemizedlist>
+<listitem>
+Whether to allow a repository to be created
+</listitem>
+<listitem>
+Whether to allow any access to a repository
+</listitem>
+<listitem>
+Whether to allow a changeset, which is on a some branch
+</listitem>
+<listitem>
+Whether to allow a changeset which changes a particular file
+</listitem>
+</itemizedlist>
 <para>
-Here be dragons...
+When the first two of these decisions are being made, nothing is known
+about what files might be changed, and so all file and branch conditions
+automatically succeed for the purpose of such decisions. This means that
+doing tricky things with file conditions can have counterintuitive
+consequences:
+</para>
+<itemizedlist>
+<listitem>
+<para>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:</para>
+<programlisting>
+   read repo=specialrepo file=dontwritethis
+   write repo=specialrepo
+</programlisting>
+<para>
+allows all users to read specialrepo, and to write to all files
+<emphasis>except</emphasis> that any changeset which writes to
+<filename>dontwritethis</filename> will be rejected.
 </para>
+</listitem>
+<listitem>
+For similar reasons, don't give <literal>init</literal> rules file conditions.
+</listitem>
+<listitem>
+<para>Don't try to deny write access to a particular file on a particular
+branch - a developer can write to the file on another branch and then merge
+it in. Either deny all writes to the branch from that user, or allow them
+to write to all the files they can write to on any branch. In other words,
+something like this will have the intended effect:
+</para>
+<programlisting>
+   write user=docs/* branch=docs file=docs/*
+</programlisting>
+<para>
+But something like this will not have the intended effect; it will
+effectively allow these users to write to any file on any branch, by
+writing it to "docs" first:
+</para>
+<programlisting>
+  write user=docs/* branch=docs
+  write user=docs/* file=docs/*
+  read user=docs/*
+</programlisting>
+</listitem>
+</itemizedlist>
 </section>
 </section>
 <section>