doc/file-conditions
author Paul Crowley <paul@lshift.net>
Sun, 08 Mar 2009 15:12:20 +0000
changeset 89 30a8be7ce326
parent 83 86ec1268d306
child 112 3035990989ee
permissions -rw-r--r--
reword comment for clarity
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
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     6
operation depending on what files it modifies and what branch the work is on.
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     7
However, the way these conditions work is subtle and can be counterintuitive -
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     8
if you want to keep things simple, stick to user and repo conditions, and then
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
things are likely to work the way you would expect.
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    10
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    11
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
    12
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
    13
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    14
    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
    15
    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
    16
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    17
However, in order to understand what effect adding these conditions will have,
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    18
it helps to understand how and when these rules are applied.
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    19
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    20
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
    21
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    22
- 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
    23
- 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
    24
- 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
    25
- 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
    26
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    27
When the first two of these decisions are being made, nothing is known about
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    28
what files might be changed, and so all file conditions automatically succeed
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    29
for the purpose of such decisions. This means that doing tricky things with
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    30
file conditions can have counterintuitive consequences:
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    31
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    32
- You cannot limit read access to a subset of a repository with a "read" rule
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    33
and a file condition: any user who has access to a repository can read all of
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    34
it and its full history. Such a rule can only have the effect of masking a
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    35
later "write" rule, as in this example:
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    36
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    37
   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
    38
   write repo=specialrepo
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    39
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    40
allows all users to read specialrepo, and to write to all files *except* that
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    41
any changeset which writes to "dontwritethis" will be rejected.
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    42
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    43
- 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
    44
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    45
- Don't try to deny write access to a particular file on a particular branch -
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    46
a developer can write to the file on another branch and then merge it in.
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    47
Either deny all writes to the branch from that user, or allow them to write to
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    48
all the files they can write to on any branch. In other words, something like
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    49
this will have the intended effect:
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    50
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    51
  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
    52
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    53
But something like this will not have the intended effect; it will effectively
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    54
allow these users to write to any file on any branch, by writing it to "docs"
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    55
first:
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    56
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    57
  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
    58
  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
    59
  read user=docs/*
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    60
86ec1268d306 Move some docs out of the README to make it less daunting
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    61