1 FILE CONDITIONS

     2 

     3 Read configuring-access before you read this.

     4 

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

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

     7 However, the way these conditions work is subtle and can be counterintuitive -

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

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

    10 

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

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

    13 

    14     file=<globpattern> - file in the repo

    15     branch=<globpattern> - name of the branch

    16 

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

    18 it helps to understand how and when these rules are applied.

    19 

    20 The rules file is used to make four decisions:

    21 

    22 - Whether to allow a repository to be created

    23 - Whether to allow access to a repository

    24 - Whether to allow a changeset on a particular branch at all

    25 - Whether to allow a changeset to change a particular file

    26 

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

    28 what files might be changed, and so all file conditions automatically succeed

    29 for the purpose of such decisions. This means that doing tricky things with

    30 file conditions can have counterintuitive consequences:

    31 

    32 - You cannot limit read access to a subset of a repository with a "read" rule

    33 and a file condition: any user who has access to a repository can read all of

    34 it and its full history. Such a rule can only have the effect of masking a

    35 later "write" rule, as in this example:

    36 

    37    read repo=specialrepo file=dontwritethis

    38    write repo=specialrepo

    39 

    40 allows all users to read specialrepo, and to write to all files *except* that

    41 any changeset which writes to "dontwritethis" will be rejected.

    42 

    43 - For similar reasons, don't give "init" rules file conditions.

    44 

    45 - Don't try to deny write access to a particular file on a particular branch -

    46 a developer can write to the file on another branch and then merge it in.

    47 Either deny all writes to the branch from that user, or allow them to write to

    48 all the files they can write to on any branch. In other words, something like

    49 this will have the intended effect:

    50 

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

    52 

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

    54 allow these users to write to any file on any branch, by writing it to "docs"

    55 first:

    56 

    57   write user=docs/* branch=docs

    58   write user=docs/* file=docs/*

    59   read user=docs/*

    60 

    61