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

# ----------------------------------------------------------------------------

# 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

                # 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:
#       (R|RW|RW+) [zero or more refexes] = [one or more users]

# there are 3 types of permissions: R, RW, and RW+.  The "+" means permission
# to "rewind" (force push a non-fast forward to) a branch

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

# 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 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
#     - refexes are matched without any anchoring, which means a refex like
#       "refs/tags/v[0-9]" matches anything *containing* that pattern.  There
#       may be text before and after it (example: refs/tags/v4-r3p7), and it
#       will still match
#     - 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      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 NOTE: if you use deny rules, the order of the rules also makes
# a difference, where earlier it did not.  Please review your ruleset
# carefully or test it.  In particular, do not use `@all` in a deny rule -- it
# won't work as you might expect***.

# 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

# Briefly, the rule is: the first matching refex that has the operation you're
# looking for (`W` or `+`), or a minus (`-`), results in success, or failure,
# respectively.  A fallthrough also results in failure

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