gitolite/doc/rc.mkd

# the "rc" file (`$HOME/.gitolite.rc`)

**NOTE**: if you're migrating from g2, there are some settings that MUST be
dealt with **before** running `gitolite setup`; please read the [g2
migration][g2migr] page and linked pages, and especially the one on
[presetting the rc file][rc-preset].

----

The rc file for g3 is *quite* different from that of g2.

As before, it is designed to be the only thing unique to your site for most
setups.  What is new is that it is easy to extend it when new needs come up,
without having to touch core gitolite.

The rc file is perl code, but you do NOT need to know perl to edit it.  Just
mind the commas, use single quotes unless you know what you're doing, and make
sure the brackets and braces stay matched up!

Please look at the `~/.gitolite.rc` file that gets installed when you setup
gitolite.  As you can see there are 3 types of variables in it:

  * simple variables (like `UMASK`)
  * lists (like `POST_COMPILE`, `POST_CREATE`)
  * hashes (like `ROLES`, `COMMANDS`)

While some of the variables are documented in this file, many of them are not.
Their purposes are to be found in each of their individual documentation files
around; start with [customising gitolite][cust].  If a setting is used by an
external command then running that command with '-h' may give you additional
information.

## specific variables

  * `$UMASK`, octal, default `0077`

    The default UMASK that gitolite uses makes all the repos and their
    contents have `rwx------` permissions.  People who want to run gitweb
    realise that this will not do.

    The correct way to deal with this is to give this variable a value like
    `0027` (note the syntax: the leading 0 is required), and then make the
    user running the webserver (apache, www-data, whatever) a member of the
    'git' group.

    If you've already installed gitolite then existing files will have to be
    fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
    This is because umask only affects permissions on newly created files, not
    existing ones.

  * `$GIT_CONFIG_KEYS`, string, default empty

    This setting allows the repo admin to define acceptable gitconfig keys.

    Gitolite allows you to set git config values using the "config" keyword;
    see [here][git-config] for details and syntax.

    However, if you are in an installation where the repo admin does not (and
    should not) have shell access to the server, then allowing him to set
    arbitrary repo config options *may* be a security risk -- some config
    settings allow executing arbitrary commands!

    You have 3 choices.  By default `$GIT_CONFIG_KEYS` is left empty, which
    completely disables this feature (meaning you cannot set git configs via
    the repo config).

    The second choice is to give it a space separated list of settings you
    consider safe.  (These are actually treated as a set of [regular
    expression][regex] patterns, and any one of them must match).

    For example:

        $GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';

    Each pattern should match the *whole* key (in other words, there
    is an implicit `^` at the start of each pattern, and a `$` at the
    end).

    The third choice (which you may have guessed already if you're familiar
    with regular expressions) is to allow anything and everything:
    `$GIT_CONFIG_KEYS = '.*';`

  * `DEFAULT_ROLE_PERMS`, string, default undef

    This sets default wildcard permissions for newly created wildcard repos.

    If set, this value will be used as the default role permissions for new
    wildcard repositories. The user can change this value with the perms
    command as desired after repository creation; it is only a default.

    Please be aware this is potentially a multi-line variable.  In most
    setups, it will be left undefined.  Some installations may benefit from
    setting it to `READERS @all`.

    If you want multiple roles to be assigned by default, here is how.  Note
    double quotes this time, due to the embedded newline, which in turn
    require the '@' to be escaped:

        DEFAULT_ROLE_PERMS  =>  "READERS \@all\nWRITERS \@senior_devs",

  * `LOCAL_CODE`, string

    This is described in more detail [here][localcode].  Please be aware
    **this must be a FULL path**, not a relative path.