# 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+|RWD|RW+D) [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 C permission is described in doc/4-wildcard-repositories.mkd.  The D
# addition to RW/RW+ is described in doc/3-faq-tips-etc.mkd, in the section on
# "separating delete and rewind rights".

# 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      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 `W` and `+`.
#
# - 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).
#
# - do not use `@all` when your config has any deny rules; it won't work as
#   you probably expect it to!

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

# 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