# example conf file for gitolite

# overall syntax:
#     - everything in this is space-separated; no commas, semicolons, etc
#     - 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
#       (usernames: only alphanumerics, ".", "_", "-";
#       reponames: same, plus "/", but not at the start)

# 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

# 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

# syntax:
#   @listname = name [...]
# lists can be used as shorthand for usernames as well as reponames

# 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:
@cust_A = cust1 cust2
@cust_A = cust99
# and this is the same as listing all three on the same line

# you can nest groups, but not recursively of course!
@interns = indy james
@staff = bob @interns

@staff = me alice
@secret_staff = bruce whitfield martin

@pubrepos = linux git

@privrepos = supersecretrepo anothersecretrepo

# ----------------------------------------------------------------------------
# REPOS, REFS, and PERMISSIONS

# syntax:
#   repo [one or more repos]
#   (R|RW|RW+) [zero or more refexes] = [one or more users]

# notes:

#     - 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

#     - RW+ means non-ff push is allowed
#     - you can't write just "W" or "+"; it has to be R, or RW, or RW+

#     - a refex is a regex that matches a ref :-)  If you see the examples
#       below you'll get it easy enough

#     - refexes are specified in perl regex syntax
#     - 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)

#     - 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)

# matching:

#     - 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

# anyone can play in the sandbox, including making non-fastforward commits
# (that's what the "+" means)
repo sandbox
    RW+     = @all

# my repo and alice's repo have the same memberships and access, so we just
# put them both in the same stanza
repo myrepo alicerepo
    RW+     = me  alice
    R       = bob  eve

# this repo is visible to customers from company A but they can't write to it
repo cust_A_repo
    R       = @cust_A
    RW      = @staff

# idea for the tags syntax shamelessly copied from git.git
# Documentation/howto/update-hook-example.txt :)
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

# ----------------------------------------------------------------------------
# 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 :-)