docs/wild.mkd

   1 # "wild" repos (user created repos)
   2
   3 ----
   4
   5 The wildrepos feature allows you to specify access control rules using regular
   6 expression patterns, so you can have many actual repos being served by a
   7 single set of rules in the config file.  The [regex](regex) can also include the
   8 word `CREATOR` in it, allowing you to parametrise the name of the user
   9 creating the repo.
  10
  11 # quick intro/example
  12
  13 If you're curious about the feature but you aren't sure if you want to read
  14 the whole page, here's a very simple example.
  15
  16 This is what the admin added to the conf file:
  17
  18 ```gitolite
  19 @users = u1 u2 u3
  20
  21 repo foo/CREATOR/[a-z]..*
  22     C   =   u1 u2 u3
  23     RW+ =   CREATOR
  24     RW  =   WRITERS
  25     R   =   READERS
  26 ```
  27
  28 User 'u1' then runs `git clone git@host:foo/u1/bar`, creating the repo.
  29 Notice the repo name matches the regex, if you substitute the user's name
  30 for the word CREATOR.
  31
  32 This is the effective rule list for 'foo/u1/bar' immediately after the user
  33 creates it:
  34
  35 ```gitolite
  36 repo foo/u1/bar
  37     RW+ =   u1
  38     RW  =   WRITERS
  39     R   =   READERS
  40 ```
  41
  42 Most of this is fixed, but the creator (user 'u1') *can* use the [perms][]
  43 command to add other users as 'READERS' or 'WRITERS'.  For example he could
  44 add 'u2' as a writer and 'u3' and 'u5' as readers:
  45
  46 [perms]: user#setget-additional-permissions-for-repos-you-created
  47
  48 This is the effective rule list that applies to the repo if he does that:
  49
  50 ```gitolite
  51 repo foo/u1/bar
  52     RW+ =   u1
  53     RW  =   u2
  54     R   =   u3 u5
  55 ```
  56
  57 Note that both these "effective rule lists" were created without touching the
  58 actual conf file or any admin intervention.
  59
  60 And that's it for our quick intro example.  The rest of this page will explain
  61 all this in much more detail.
  62
  63 # declaring wild repos in the conf file
  64
  65 Here's a slightly more detailed example, starting with what the admin puts in
  66 the conf file:
  67
  68 ```gitolite
  69 @prof       =   u1
  70 @TAs        =   u2 u3
  71 @students   =   u4 u5 u6
  72
  73 repo    assignments/CREATOR/a[0-9][0-9]
  74     C   =   @students
  75     RW+ =   CREATOR
  76     RW  =   WRITERS @TAs
  77     R   =   READERS @prof
  78 ```
  79
  80 Note the "C" permission.  This is a standalone "C", which gives the named
  81 users the right to *create a repo*.  <span class="gray">This is not to be confused with
  82 the "RWC" permission or its variants described [elsewhere][write-types], which
  83 are about creating *branches*, not *repos*.</span>
  84
  85 [write-types]: conf-2#appendix-1-different-types-of-write-operations
  86
  87 # (**user**) creating a specific repo
  88
  89 For now, ignore the special usernames READERS and WRITERS, and just create a
  90 new repo, as user "u4" (a student):
  91
  92     $ git clone git@server:assignments/u4/a12
  93     Initialized empty Git repository in /home/git/repositories/assignments/u4/a12.git/
  94     warning: You appear to have cloned an empty repository.
  95
  96 # a slightly different example
  97
  98 Here's how the same example would look if you did not want the CREATOR's name
  99 to be part of the actual repo name.
 100
 101 ```gitolite
 102 repo    assignments/a[0-9][0-9]
 103     C   =   @students
 104     RW+ =   CREATOR
 105     RW  =   WRITERS @TAs
 106     R   =   READERS @prof
 107 ```
 108
 109 We haven't changed anything except the repo name regex.  This means that the
 110 first student that creates, say, `assignments/a12` becomes the owner.
 111 Mistakes (such as claiming a12 instead of a13) need to be rectified by an
 112 admin logging on to the back end, though it's not too difficult.
 113
 114 You could also replace the C line like this:
 115
 116         C   =   @TAs
 117
 118 and have a TA create the repos in advance.
 119
 120 # repo regex patterns
 121
 122 ## regex pattern versus normal repo
 123
 124 Due to projects like `gtk+`, the `+` character is now considered a valid
 125 character for an *ordinary* repo.  Therefore, a regex like `foo/.+` does not
 126 look like a [regex](regex) to gitolite.  Use `foo/..*` if you want that.
 127
 128 Also, `..*` by itself is not considered a valid repo regex.  Try
 129 `[a-zA-Z0-9].*`.  `CREATOR/..*` will also work.
 130
 131 ## line-anchored regexes
 132
 133 A regex like
 134
 135     repo assignments/S[0-9]+/A[0-9]+
 136
 137 would match `assignments/S02/A37`.  It will not match `assignments/S02/ABC`,
 138 or `assignments/S02/a37`, obviously.
 139
 140 But you may be surprised to find that it does not match even
 141 `assignments/S02/A37/B99`.  This is because internally, gitolite
 142 *line-anchors* the given regex; so that regex actually becomes
 143 `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
 144 metacharacters.
 145
 146 !!! warning "Side-note: contrast with refexes"
 147
 148     Just for interest, note that this is in contrast to the [refexes][refex]
 149     for the normal "branch" permissions. Refexes are only anchored at the
 150     start; a regex like `refs/heads/master` actually can match
 151     `refs/heads/master01/bar` as well, even if no one will actually push such
 152     a branch!  You can anchor both sides if you really care, by using
 153     `master$` instead of `master`, but that is *not* the default for refexes.
 154
 155 [refex]: conf#the-refex-field
 156
 157 # roles
 158
 159 The words READERS and WRITERS are called "role" names.  The access rules in
 160 the conf file decide what permissions these roles have, but they don't say
 161 what users are in each of these roles.
 162
 163 That needs to be done by the creator of the repo, using the `perms` command.
 164 You can run `ssh git@host perms -h` for detailed help, but in brief, that
 165 command lets you give and take away roles to users.  [This][perms] has some
 166 more detail.
 167
 168 ## adding other roles
 169
 170 If you want to have more than just the 2 default roles, say something like:
 171
 172 You can add the new names to the ROLES hash in the [rc file](rc); see comments
 173 in that file for how to do that.  Be sure to run the 2 commands mentioned
 174 there after you have added the roles.
 175
 176 ```gitolite
 177 repo foo/..*
 178   C                 =   u1
 179   RW    refs/tags/  =   TESTERS
 180   -     refs/tags/  =   @all
 181   RW+               =   WRITERS
 182   RW                =   INTERNS
 183   R                 =   READERS
 184   RW+D              =   MANAGERS
 185 ```
 186
 187 ### <font color="red">**IMPORTANT WARNING ABOUT THIS FEATURE**</font>
 188
 189 !!! danger ""
 190
 191     Please make sure that none of the role names conflict with any of the user
 192     names or group names in the system.  For example, if you have a user
 193     called "foo" or a group called "@foo", make sure you do not include "foo"
 194     as a valid role in the ROLES hash.
 195
 196 You can keep things sane by using UPPERCASE names for roles, while keeping all
 197 your user and group names lowercase; then you don't have to worry about this
 198 problem.
 199
 200 ## setting default roles
 201
 202 You can setup some default role assignments as soon as a new wild repo is
 203 created.
 204
 205 Here's how:
 206
 207   * Enable the 'set-default-roles' feature in the rc file by uncommenting it
 208     if it is already present or adding it to the ENABLE list if it is not.
 209
 210   * Supply a set of default role assignments for a wild repo regex by adding
 211     lines like this to the repo config para:
 212
 213         option default.roles-1  =   READERS @all
 214         option default.roles-2  =   WRITERS @senior-devs
 215
 216 This will then behave as if the [perms][] command was used immediately after
 217 the repo was created to add those two role assignments.
 218
 219 If you want to simulate the old (pre v3.5) `DEFAULT_ROLE_PERMS` rc file
 220 variable, just add them under a `repo @all` line.  (Remember that this only
 221 affects newly created wild repos, despite the '@all' name).
 222
 223 ## specifying owners
 224
 225 See the section on `OWNER_ROLENAME` in the [rc file page](rc).
 226
 227 # listing wild repos
 228
 229 In order to see what repositories were created from a wildcard, use the 'info'
 230 command.  Try `ssh git@host info -h` to get help on the info command.
 231
 232 # deleting a wild repo
 233
 234 Run the whimsically named "D" command -- try `ssh git@host D -h` for more info
 235 on how to delete a wild repo.  (Yes the command is "D"; it's meant to be a
 236 counterpart to the "C" permission that allowed you to create the repo in the
 237 first place).  Of course this only works if your admin has enabled the command
 238 (gitolite ships with the command disabled for remote use).
 239
 240 # appendix 1: owner and creator
 241
 242 A wild repo is created by one specific user.  This user is usually called the
 243 **creator** of the repo: his username is placed in a file called gl-creator in
 244 the (bare) repo directory, any permissions given in the gitolite.conf file to
 245 "CREATOR" will be applicable to this user, he is the only person who can give
 246 permissions to other users (by running the 'perms' command), etc.
 247
 248 But, as I said in [this mail](https://groups.google.com/d/msg/gitolite/nFbnQuO0ztM/tXiVs5ah2bcJ):
 249
 250 ```text
 251     Until about a year ago, Gitolite only knew the concept of a "creator", and
 252     there was only one.
 253
 254     But then people started seeing the need for more than one "owner", because
 255     wild repos may be *created* by one person, but they often needed to be
 256     *administered* by one of several people.
 257
 258     So now, even though large parts of the documentation probably conflate
 259     "creator" and "owner", you can see wild.html ([wild]) and rc.html ([rc])
 260     to actually understand how this larger group become the "owner".
 261 ```
 262
 263 <!--
 264
 265 # appendix 2: handing off the repo to someone else #TODO
 266
 267 -->