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