the v3.0 to v3.3 "rc" file ($HOME/.gitolite.rc)

NOTE 1: if you're using v3.4 and above, see this.

NOTE 2: if you're migrating from v2, there are some settings that MUST be dealt with before running gitolite setup; please read the migration page and linked pages, and especially the one on "presetting the rc file"

The rc file for v3 is quite different from that of v2.

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 "non-core" gitolite. If a setting is used by a 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 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 expressions, and any one of them must match).

    For example:

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

    Each regex should match the whole key (in other words, there is an implicit ^ at the start of each regex, 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 = '.*';

  • ROLES, hash, default keys 'READERS' and 'WRITERS'

    This specifies the role names allowed to be used by users running the perms command. The wild repos doc has more info on roles.

  • 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. Please be aware this must be a FULL path, not a relative path.