# example conf file for gitolite # ---------------------------------------------------------------------------- # overall syntax: # - everything is space-separated; no commas, semicolons, etc (except in # the description string for gitweb) # - comments in the normal shell-ish style; no surprises there # - there are NO continuation lines of any kind # - user/repo names as simple as possible; they must start with an # alphanumeric, but after that they can also contain ".", "_", "-". # - usernames can optionally be followed by an "@" and a domainname # containing at least one "." (this allows you to use an email # address as someone's username) # - reponames can contain "/" characters (this allows you to # put your repos in a tree-structure for convenience) # objectives, over and above gitosis: # - simpler syntax # - easier gitweb/daemon control # - specify who can push a branch/tag # - specify who can rewind a branch/rewrite a tag # ---------------------------------------------------------------------------- # GROUPS # ------ # syntax: # @groupname = [one or more names] # groups let you club (user or group) names together for convenience # * a group is like a #define in C except that it can *accumulate* values # * the config file is parsed in a single-pass, so later *additions* to a # group name cannot affect earlier *uses* of it # The following examples should illustrate all this: # you can have a group of people... @staff = sitaram some_dev another-dev # ...or a group of repos @oss_repos = gitolite linux git perl rakudo entrans vkc # ...or even a group of refexes @important = master$ QA_done refs/tags/v[0-9] # (see later for what "refex"s are; I'm only mentioning it # here to emphasise that you can group them too) # even sliced and diced differently @admins = sitaram admin2 # notice that sitaram is in 2 groups (staff and admins) # if you repeat a group name in another definition line, the # new ones get added to the old ones (they accumulate) @staff = au.thor # so now "@staff" expands to all 4 names # groups can include other groups, and the included group will # be expanded to whatever value it currently has @interns = indy james @staff = bob @interns # "@staff" expands to 7 names now @interns = han # "@interns" now has 3 names in it, but note that this does # not change @staff # REPO AND BRANCH PERMISSIONS # --------------------------- # syntax: # start line: # repo [one or more repos and/or repo groups] # followed by one or more permissions lines: # (C|R|RW|RW+|RWC|RW+C|RWD|RW+D|RWCD|RW+CD) [zero or more refexes] = [one or more users] # there are 6 types of permissions: R, RW, and RW+ are simple (the "+" means # permission to "rewind" -- force push a non-fast forward to -- a branch). # The *standalone* C permission pertains to creating a REPO and is described # in doc/wildcard-repositories.mkd. The C and D *suffixes* to the RW/RW+ # permissions pertain to creating or deleting a BRANCH, and are described in # doc/3-faq-tips-etc.mkd, in the sections on "separating push and create # rights" and "separating delete and rewind rights" respectively. # how permissions are matched: # - user, repo, and access (W or +) are known. For that combination, if # any of the refexes match the refname being updated, the push succeeds. # If none of them match, it fails # what's a refex? a regex to match against the ref being updated (get it?) # See next section for more on refexes # BASIC PERMISSIONS (repo level only; apply to all branches/tags in repo) # most important rule of all -- specify who can make changes # to *this* file take effect repo gitolite-admin RW+ = @admins # "@all" is a special, predefined, group name of all users # (everyone who has a pubkey in keydir) repo testing RW+ = @all # this repo is visible to staff but only sitaram can write to it repo gitolite R = @staff RW+ = sitaram # you can split up access rules for a repo for convenience # (notice that @oss_repos contains gitolite also) repo @oss_repos R = @all # set permissions to all repos. *Please* do see # doc/3-faq-tips-etc.mkd for notes on this feature repo @all RW+ = @admins # SPECIFYING AND USING A REFEX # - refexes are specified in perl regex syntax # - refexes are prefix-matched (they are internally anchored with "^" # before being used), which means a refex like "refs/tags/v[0-9]" # matches anything *starting with* that pattern. There may be text # after it (example: refs/tags/v4-r3/p7), and it will still match # ADVANCED PERMISSIONS USING REFEXES # - if no refex appears, the rule applies to all refs in that repo # - a refex is automatically prefixed by "refs/heads/" if it doesn't start # with "refs/" (so tags have to be explicitly named as # refs/tags/pattern) # here's the example from # Documentation/howto/update-hook-example.txt: # refs/heads/master junio # +refs/heads/pu junio # refs/heads/cogito$ pasky # refs/heads/bw/.* linus # refs/heads/tmp/.* .* # refs/tags/v[0-9].* junio # and here're the equivalent gitolite refexes repo git RW = bobzilla RW master = junio RW+ pu = junio RW cogito$ = pasky RW bw/ = linus RW tmp/ = @all RW refs/tags/v[0-9] = junio # DENY/EXCLUDE RULES # ***IMPORTANT NOTES ABOUT "DENY" RULES***: # - deny rules do NOT affect read access. They only apply to write access. # # - when using deny rules, the order of your rules starts to matter, where # earlier it did not. The first matching rule applies, where "matching" is # defined as either permitting the operation you're attempting (`W` or `+`), # which results in success, or a "deny" (`-`), which results in failure. # (As before, a fallthrough also results in failure). # in the example above, you cannot easily say "anyone can write any tag, # except version tags can only be written by junio". The following might look # like it works but it doesn't: # RW refs/tags/v[0-9] = junio # RW refs/tags/ = junio linus pasky @others # if you use "deny" rules, however, you can do this (a "deny" rule just uses # "-" instead of "R" or "RW" or "RW+" in the permission field) RW refs/tags/v[0-9] = junio - refs/tags/v[0-9] = linus pasky @others RW refs/tags/ = junio linus pasky @others # FILE/DIR NAME BASED RESTRICTIONS # -------------------------------- # Here's a hopefully self-explanatory example. Assume the project has the # following contents at the top level: a README, a "doc/" directory, and an # "src/" directory. repo foo RW+ = lead_dev # rule 1 RW = dev1 dev2 dev3 dev4 # rule 2 RW NAME/ = lead_dev # rule 3 RW NAME/doc/ = dev1 dev2 # rule 4 RW NAME/src/ = dev1 dev2 dev3 dev4 # rule 5 # Notes # - the "NAME/" is part of the syntax; think of it as a keyword if you like. # The rest of it is treated as a refex to match against each file being # touched (see "SPECIFYING AND USING A REFEX" above for details) # - file/dir NAME-based restrictions are *in addition* to normal (branch-name # based) restrictions; they are not a *replacement* for them. This is why # rule #2 (or something like it, maybe with a more specific branch-name) is # needed; without it, dev1/2/3/4 cannot push any branches. # - if a repo has *any* NAME/ rules, then NAME-based restrictions are checked # for *all* users. This is why rule 3 is needed, even though we don't # actually have any NAME-based restrictions on lead_dev. Notice the pattern # on rule 3. # - *each* file touched by the commits being pushed is checked against those # rules. So, lead_dev can push changes to any files, dev1/2 can push # changes to files in "doc/" and "src/" (but not the top level README), and # dev3/4 can only push changes to files in "src/". # GITWEB AND DAEMON STUFF # ----------------------- # No specific syntax for gitweb and daemon access; just make the repo readable # ("R" access) to the special users "gitweb" and "daemon" # make "@oss_repos" (all 7 of them!) accessible via git daemon repo @oss_repos R = daemon # make the two *large* repos accessible via gitweb repo linux perl R = gitweb # REPO OWNER/DESCRIPTION LINE FOR GITWEB # syntax, one of: # reponame = "some description string in double quotes" # reponame "owner name" = "some description string in double quotes" # note: setting a description also gives gitweb access; you do not have to # give gitweb access as described above if you're specifying a description gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment" foo = "Foo is a nice test repo" foobar "Bob Zilla" = "Foobar is top secret" bar = "A nice place to get drinks" # REPO SPECIFIC GITCONFIG # ----------------------- # update 2010-02-06; this won't work unless the rc file has the right # settings; please see comments around the variable $GL_GITCONFIG_KEYS in # conf/example.gitolite.rc for details and security information. # (Thanks to teemu dot matilainen at iki dot fi) # this should be specified within a "repo" stanza # syntax: # config sectionname.keyname = [optional value_string] # example usage: if you placed a hook in hooks/common that requires # configuration information that is specific to each repo, you could do this: repo gitolite config hooks.mailinglist = gitolite-commits@example.tld config hooks.emailprefix = "[gitolite] " config foo.bar = "" config foo.baz = # This does either a plain "git config section.key value" (for the first 3 # examples above) or "git config --unset-all section.key" (for the last # example). Other forms (--add, the value_regex, etc) are not supported. # INCLUDE SOME OTHER FILE # ----------------------- include "foo.conf" # this includes the contents of $GL_ADMINDIR/conf/foo.conf here # Notes: # - the include statement is not allowed inside delegated fragments for # security reasons. # - you can also use an absolute path if you like, although in the interests # of cloning the admin-repo sanely you should avoid doing this! # EXTERNAL COMMAND HELPERS -- RSYNC # --------------------------------- # If $RSYNC_BASE is non-empty, the following config entries come into play # (otherwise they are ignored): # a "fake" git repository to collect rsync rules. Gitolite does not # auto-create any repo whose name starts with EXTCMD/ repo EXTCMD/rsync # grant permissions to files/dirs within the $RSYNC_BASE tree. A leading # NAME/ is required as a prefix; the actual path starts after that. Matching # follows the same rules as given in "FILE/DIR NAME BASED RESTRICTIONS" above RW NAME/ = sitaram RW NAME/foo/ = user1 R NAME/bar/ = user2 # just to remind you that these are perl regexes, not shell globs RW NAME/baz/.*/*.c = user3