doc/file-conditions
branchdebian
changeset 115 731a72b742db
parent 112 3035990989ee
equal deleted inserted replaced
99:e99262dfa950 115:731a72b742db
     1 FILE CONDITIONS
     1 FILE CONDITIONS
     2 
     2 
     3 Read configuring-access before you read this.
     3 Read configuring-access before you read this.
     4 
     4 
     5 mercurial-server supports file and branch conditions, which restrict an
     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.
     6 operation depending on what files it modifies and what branch the work is
     7 However, the way these conditions work is subtle and can be counterintuitive -
     7 on. However, the way these conditions work is subtle and can be
     8 if you want to keep things simple, stick to user and repo conditions, and then
     8 counterintuitive - if you want to keep things simple, stick to user and
     9 things are likely to work the way you would expect.
     9 repo conditions, and then things are likely to work the way you would
       
    10 expect.
    10 
    11 
    11 File and branch conditions are added to the conditions against which a rule
    12 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 matches, just like user and repo conditions; they have this form:
    13 
    14 
    14     file=<globpattern> - file in the repo
    15     file=<globpattern> - file in the repo
    15     branch=<globpattern> - name of the branch
    16     branch=<globpattern> - name of the branch
    16 
    17 
    17 However, in order to understand what effect adding these conditions will have,
    18 However, in order to understand what effect adding these conditions will
    18 it helps to understand how and when these rules are applied.
    19 have, it helps to understand how and when these rules are applied.
    19 
    20 
    20 The rules file is used to make four decisions:
    21 The rules file is used to make four decisions:
    21 
    22 
    22 - Whether to allow a repository to be created
    23 - Whether to allow a repository to be created
    23 - Whether to allow access to a repository
    24 - 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 on a particular branch at all
    25 - Whether to allow a changeset to change a particular file
    26 - Whether to allow a changeset to change a particular file
    26 
    27 
    27 When the first two of these decisions are being made, nothing is known about
    28 When the first two of these decisions are being made, nothing is known
    28 what files might be changed, and so all file conditions automatically succeed
    29 about what files might be changed, and so all file conditions automatically
    29 for the purpose of such decisions. This means that doing tricky things with
    30 succeed for the purpose of such decisions. This means that doing tricky
    30 file conditions can have counterintuitive consequences:
    31 things with file conditions can have counterintuitive consequences:
    31 
    32 
    32 - You cannot limit read access to a subset of a repository with a "read" rule
    33 - You cannot limit read access to a subset of a repository with a "read"
    33 and a file condition: any user who has access to a repository can read all of
    34 rule and a file condition: any user who has access to a repository can read
    34 it and its full history. Such a rule can only have the effect of masking a
    35 all of it and its full history. Such a rule can only have the effect of
    35 later "write" rule, as in this example:
    36 masking a later "write" rule, as in this example:
    36 
    37 
    37    read repo=specialrepo file=dontwritethis
    38    read repo=specialrepo file=dontwritethis
    38    write repo=specialrepo
    39    write repo=specialrepo
    39 
    40 
    40 allows all users to read specialrepo, and to write to all files *except* that
    41 allows all users to read specialrepo, and to write to all files *except*
    41 any changeset which writes to "dontwritethis" will be rejected.
    42 that any changeset which writes to "dontwritethis" will be rejected.
    42 
    43 
    43 - For similar reasons, don't give "init" rules file conditions.
    44 - For similar reasons, don't give "init" rules file conditions.
    44 
    45 
    45 - Don't try to deny write access to a particular file on a particular branch -
    46 - Don't try to deny write access to a particular file on a particular
    46 a developer can write to the file on another branch and then merge it in.
    47 branch - a developer can write to the file on another branch and then merge
    47 Either deny all writes to the branch from that user, or allow them to write to
    48 it in. Either deny all writes to the branch from that user, or allow them
    48 all the files they can write to on any branch. In other words, something like
    49 to write to all the files they can write to on any branch. In other words,
    49 this will have the intended effect:
    50 something like this will have the intended effect:
    50 
    51 
    51   write user=docs/* branch=docs file=docs/*
    52   write user=docs/* branch=docs file=docs/*
    52 
    53 
    53 But something like this will not have the intended effect; it will effectively
    54 But something like this will not have the intended effect; it will
    54 allow these users to write to any file on any branch, by writing it to "docs"
    55 effectively allow these users to write to any file on any branch, by
    55 first:
    56 writing it to "docs" first:
    56 
    57 
    57   write user=docs/* branch=docs
    58   write user=docs/* branch=docs
    58   write user=docs/* file=docs/*
    59   write user=docs/* file=docs/*
    59   read user=docs/*
    60   read user=docs/*
    60 
    61