diff --git a/conf/example.conf b/conf/example.conf index 81b6148..752c279 100644 --- a/conf/example.conf +++ b/conf/example.conf @@ -1,9 +1,11 @@ # example conf file for gitolite +# ---------------------------------------------------------------------------- # overall syntax: -# - everything in this is space-separated; no commas, semicolons, etc +# - 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 +# - there are NO continuation lines of any kind # - user/repo names as simple as possible # (usernames: only alphanumerics, ".", "_", "-"; # reponames: same, plus "/", but not at the start) @@ -14,56 +16,79 @@ # - specify who can push a branch/tag # - specify who can rewind a branch/rewrite a tag -# convenience: allow specifying the access control in bits and pieces, even if -# they overlap. Keeps the config file smaller and saner. See the example in -# the "faq, tips, etc" document - # ---------------------------------------------------------------------------- -# LISTS + +# GROUPS +# ------ # syntax: -# @listname = name [...] -# lists can be used as shorthand for usernames as well as reponames +# @groupname = [one or more names] -# a list is equivalent to typing out all the right hand side names, so why do -# we need lists at all? (1) to be able to reuse the same set of usernames in -# the paras for different repos, (2) to keep the lines short, because lists -# accumulate, like squid ACLs, so you can say: +# groups let you club names together for convenience in specifying +# permissions. A group is simply expanded to whatever names are on the right +# hand side when it is actually used -# @cust_A = cust1 cust2 -# @cust_A = cust99 + # you can have a group of people... +@staff = sitaram some_dev another-dev -# and this is the same as listing all three on the same line + # ...or a group of repos +@oss_repos = gitolite linux git perl rakudo entrans vkc -# you can nest groups, but not recursively of course! + # even sliced and diced differently +@admins = sitaram admin2 + # notice that sitaram is in 2 groups (staff and admins) -# @interns = indy james -# @staff = bob @interns + # 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 -# @staff = me alice -# @secret_staff = bruce whitfield martin + # groups can include other groups (but not recursively) +@interns = indy james +@staff = bob @interns + # "@staff" expands to 7 names now -# @pubrepos = linux git - -# @privrepos = supersecretrepo anothersecretrepo - -# ---------------------------------------------------------------------------- -# REPOS, REFS, and PERMISSIONS +# REPO AND BRANCH PERMISSIONS +# --------------------------- # syntax: -# repo [one or more repos] -# (R|RW|RW+) [zero or more refexes] = [one or more users] +# start line: +# repo [one or more repos and/or repo groups] +# followed by one or more permissions lines: +# (R|RW|RW+) [zero or more refexes] = [one or more users] -# notes: +# there are 3 types of permissions: R, RW, and RW+. The "+" means permission +# to "rewind" (force push a non-fast forward to) a branch -# - the reponame is a simple name. Do not add the ".git" extension -- -# that will be added by the program when the actual repo is created +# 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 -# - RW+ means non-ff push is allowed -# - you can't write just "W" or "+"; it has to be R, or RW, or RW+ +# what's a refex? a regex to match against the ref being updated (get it?) -# - a refex is a regex that matches a ref :-) If you see the examples -# below you'll get it easy enough +# 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 +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 as convenient + # (notice that @oss_repos contains gitolite also) +repo @oss_repos + R = @all + +# ADVANCED PERMISSIONS USING REFEXES # - refexes are specified in perl regex syntax # - if no refex appears, the rule applies to all refs in that repo @@ -71,53 +96,47 @@ # with "refs/" (so tags have to be explicitly named as # refs/tags/pattern) -# - the list of users or repos can inlude any group name defined earlier -# - "@all" is a special, predefined, groupname that means "all users" -# (there is no corresponding shortcut for all repos) + # here's the example from + # Documentation/howto/update-hook-example.txt: -# matching: + # 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 -# - 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 + # and here're the equivalent gitolite refexes +repo git + RW master = junio + RW+ pu = junio + RW cogito$ = pasky + RW bw/ = linus + RW tmp/ = @all + RW refs/tags/v[0-9] = junio -# anyone can play in the sandbox, including making non-fastforward commits -# (that's what the "+" means) -# repo sandbox -# RW+ = @all +# GITWEB AND DAEMON STUFF +# ----------------------- -# my repo and alice's repo have the same memberships and access, so we just -# put them both in the same stanza +# No specific syntax for gitweb and daemon access; just make the repo readable +# ("R" access) to the special users "gitweb" and "daemon" -# repo myrepo alicerepo -# RW+ = me alice -# R = bob eve + # make "@oss_repos" (all 7 of them!) accessible via git daemon +repo @oss_repos + R = daemon -# this repo is visible to customers from company A but they can't write to it + # make the two *large* repos accessible via gitweb +repo linux perl + R = gitweb -# repo cust_A_repo -# R = @cust_A -# RW = @staff +# GITWEB DESCRIPTION LINE -# idea for the tags syntax shamelessly copied from git.git -# Documentation/howto/update-hook-example.txt :) +# syntax: +# reponame = "some description string in double quotes" -# repo @privrepos thirdsecretrepo -# RW+ pu = bruce -# RW master next = bruce -# RW refs/tags/v[0-9].* = bruce -# RW refs/tags/ss/ = @secret_staff -# RW tmp/.* = @secret_staff -# R = @secret_staff +# 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 -# ---------------------------------------------------------------------------- -# GITWEB AND DAEMON CONTROL - -# there is no special syntax for this. If a repo gives read permissions to -# the special user "gitweb" or "daemon", the corresponding changes are made -# when you compile; see "faq, tips, etc" document for details. - -# this means you cannot have a real user called "gitweb" or "daemon" but I -# don't think that is a problem :-) +gitolite = "fast, secure, access control for git in a corporate environment"