diff --git a/doc/wildcard-repositories.mkd b/doc/wildcard-repositories.mkd index 974455e..2c7241f 100644 --- a/doc/wildcard-repositories.mkd +++ b/doc/wildcard-repositories.mkd @@ -8,19 +8,13 @@ created it, allowing him/her to hand out R and RW permissions to other users to collaborate, all these are possible. And any of these could have a bug in it. I haven't found any yet, but that doesn't mean there aren't any. -Also, there are some limitations. For example, you cannot specify gitconfig -values for a wildcard repo; it only works for actual repos. - -There may be other such missing features. Sometimes it's just not possible to -make it work. Or it may be cumbersome enough that unless there are *no* -workarounds I may not have the time to code it right away. - ---- In this document: + * quick introduction * rc file setting required - * wildcard repos + * examples of wildcard repos * wildcard repos with creator name in them * wildcard repos without creator name in them * side-note: line-anchored regexes @@ -28,7 +22,6 @@ In this document: * handing out rights to wildcard-matched repos * setting a gitweb description for a wildcard-matched repo * reporting - * other issues and discussion * how it actually works ---- @@ -37,6 +30,16 @@ This document is mostly "by example". ---- + + +### quick introduction + +The wildrepos feature allows you to specify access control rules using regular +expression patterns, so you can have many actual repos being served by a +single set of rules in the config file. The regex pattern can also include +the word `CREATOR` in it, allowing you to parametrise the name of the user +creating the repo. The examples below will make this clearer. + ### rc file setting required @@ -45,13 +48,24 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc` on the server. Please search for that variable and see comments around it in `conf/example.gitolite.rc` for more information on this. - + -### wildcard repos +### examples of wildcard repos + +As the introduction said, you can include the word `CREATOR` in the regex +pattern, though it is not mandatory. We'll look at examples of both types of +usage. Which of these alternatives you choose depends on your needs, and the social -aspects of your environment. The first one is a little more rigid, making it -harder to make mistakes, and the second is more flexible and trusting. +aspects of your environment. Including the creator name in the pattern keeps +users rigidly separated from each others repos, and is good for a largely +autonomous collection of users with a high probability of repo name clashes. + +Omitting the creator name from the pattern puts the repos in a common +namespace, and is suitable for environments where it is not very important to +keep track of who actually created the repo (except for granting access), but +needs more communication / co-operation among the users to avoid repo name +clashes. @@ -196,28 +210,6 @@ commands, thanks to Teemu. In order to see what repositories were created from a wildcard, use the "expand" command, described briefly in [doc/report-output.mkd][repout]. - - -### other issues and discussion - - * *what if the repo name being pushed matches more than one pattern*? - - I think it would be very hard to reason about access if we were to do - something like combine all the access rights in all the matching patterns. - No matter how you do it, and how carefully you document it, there'll be - someone who is surprised by the result. - - And in security, that's a ***Bad Thing***. - - So we don't combine permissions. At runtime, we die if we find more than - one match. Let 'em go holler at the admin for creating multiple matching - repo patterns :-) - - This can make some repos inaccessible if the patterns changed *after* they - were created. The administrator should be careful not to do this. Most - of the time, it won't be difficult; the fixed prefix will usually be - different anyway so there won't be overlaps. - ### how it actually works @@ -249,8 +241,8 @@ who actually *created* the repo (this name is recorded in a special file in the repo directory when the repo is first created, so it is available). Now find a repo pattern that matches the actual reponame being pushed -- this -tells you which set of rules to apply. Only one pattern is allowed to match; -matching more than one is an error. +tells you which set of rules to apply. There can be multiple matches; if so, +they will all be applied in the sequence they appear in the config file. If the invoking user has been given "RW" permissions using `setperms`, all occurrences of the word WRITERS are replaced by the invoking username.