293 <title>File conditions</title>

   293 <title>File and branch conditions</title>

   294 <para>

   294 <para>

   295 Here be dragons...

   295 mercurial-server supports file and branch conditions, which restrict an

   296 </para>

   296 operation depending on what files it modifies and what branch the work is

   297 on. </para>

   298 <caution>

   299 The way these conditions work is subtle and can be counterintuitive - if

   300 you want to keep things simple, stick to user and repo conditions, and then

   301 things are likely to work the way you would expect.

   302 </caution>

   303 <para>

   304 File and branch conditions are added to the conditions against which a rule

   305 matches, just like user and repo conditions; they have this form:

   306 </para>

   307 <itemizedlist>

   308 <listitem>

   309 <code><literal>file=</literal><replaceable>globpattern</replaceable></code>: file within the repo

   310 </listitem>

   311 <listitem>

   312 <code><literal>branch=</literal><replaceable>globpattern</replaceable></code>: Mercurial branch name

   313 </listitem>

   314 </itemizedlist>

   315 <para>

   316 However, in order to understand what effect adding these conditions will

   317 have, it helps to understand how and when these rules are applied.

   318 </para>

   319 <para>

   320 The rules file is used to make three decisions:

   321 </para>

   322 <itemizedlist>

   323 <listitem>

   324 Whether to allow a repository to be created

   325 </listitem>

   326 <listitem>

   327 Whether to allow any access to a repository

   328 </listitem>

   329 <listitem>

   330 Whether to allow a changeset, which is on a some branch

   331 </listitem>

   332 <listitem>

   333 Whether to allow a changeset which changes a particular file

   334 </listitem>

   335 </itemizedlist>

   336 <para>

   337 When the first two of these decisions are being made, nothing is known

   338 about what files might be changed, and so all file and branch conditions

   339 automatically succeed for the purpose of such decisions. This means that

   340 doing tricky things with file conditions can have counterintuitive

   341 consequences:

   342 </para>

   343 <itemizedlist>

   344 <listitem>

   345 <para>You cannot limit read access to a subset of a repository with a "read"

   346 rule and a file condition: any user who has access to a repository can read

   347 all of it and its full history. Such a rule can only have the effect of

   348 masking a later "write" rule, as in this example:</para>

   349 <programlisting>

   350    read repo=specialrepo file=dontwritethis

   351    write repo=specialrepo

   352 </programlisting>

   353 <para>

   354 allows all users to read specialrepo, and to write to all files

   355 <emphasis>except</emphasis> that any changeset which writes to

   356 <filename>dontwritethis</filename> will be rejected.

   357 </para>

   358 </listitem>

   359 <listitem>

   360 For similar reasons, don't give <literal>init</literal> rules file conditions.

   361 </listitem>

   362 <listitem>

   363 <para>Don't try to deny write access to a particular file on a particular

   364 branch - a developer can write to the file on another branch and then merge

   365 it in. Either deny all writes to the branch from that user, or allow them

   366 to write to all the files they can write to on any branch. In other words,

   367 something like this will have the intended effect:

   368 </para>

   369 <programlisting>

   370    write user=docs/* branch=docs file=docs/*

   371 </programlisting>

   372 <para>

   373 But something like this will not have the intended effect; it will

   374 effectively allow these users to write to any file on any branch, by

   375 writing it to "docs" first:

   376 </para>

   377 <programlisting>

   378   write user=docs/* branch=docs

   379   write user=docs/* file=docs/*

   380   read user=docs/*

   381 </programlisting>

   382 </listitem>

   383 </itemizedlist>