misc

[gitolite-doc.git] / rc.mkd

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

include sidebar-toc

**IMPORTANT**: if you have a v3.0-v3.3 rc file it is documented [here][rc-33],
and it will still work.  In fact internally the v3.4 rc file data gets
converted to the v3.3 format.  That is, you don't have to upgrade your rc file
just because you upgraded gitolite; you only need to do that if you wish to
use any new features.  There's a simple program to help you do that
(@@gray(v3.6.1)@@ -- see contrib/utils/rc-format-v3.4).

@@gray(**If you're migrating from v2**, there are some settings that MUST be
dealt with **before** running `gitolite setup`; please read the
[migration][migr] page and linked pages, and especially the one on "presetting
the rc file".)@@

----

@@box-r(Note: This page has several [forward references][fr]!)@@

The rc file 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!

The rc file is well commented.  Please look at the `~/.gitolite.rc` file that
gets installed when you setup gitolite.  You can always get a default copy for
your current version by running `gitolite print-default-rc`.

As you can see there are 3 types of variables in it:

  * A lot of simple variables (like `UMASK`, `GIT_CONFIG_KEYS`, etc.).
  * A hash or two (like `ROLES`).
  * And one large list of features to be enabled (`ENABLE`).

This page documents only some of them; for most of them it's best to look in
the actual rc file or in each of their individual documentation files around;
start with ["non-core" gitolite][non-core].  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 gives `rwx------` permissions to all
    the repos and their contents.  People who want to run gitweb (or cgit,
    redmine, etc) 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

    @@box-r(See the [security note][privesc] at the end of this page for why we do
    this.)@@

    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.

    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][regex], 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.

  * `OWNER_ROLENAME`, string, default undef

    (requires v3.5 or later)

    By default, permissions on a wild repo can only be set by the *creator* of
    the repo (using the [perms][] command).  But some sites want to allow
    other people to do this as well.

    To enable this behaviour, the server admin must first set this variable to
    some string, say 'OWNERS'.  (He must also add 'OWNERS' to the ROLES hash
    described in the previous bullet).

    The creator of the repo can then add other users to the OWNERS role using
    the [perms][] command.

    The [perms][] command, the new "owns" command, and possibly other commands
    in future, will then give these users the same privileges that they give
    to the creator of the repo.

    (Also see the full documentation on [roles][]).

  * `LOCAL_CODE`, string

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

# security note: gitolite admin and shell access {#privesc}

@@box-r(If you *must* revision control it, you can.  Just add it to your admin
repo, push the change, then replace `~/.gitolite.rc` with a symlink to
`~/.gitolite/.gitolite.rc`.)@@

People sometimes ask why this file is also not revision controlled.  Here's
why.

Gitolite maintains a clear distinction between

*   people who can push to the gitolite-admin repo, and
*   people who can get a shell or run arbitrary commands on the server.

This may not matter to many (small) sites, but in large installations, the
former is often a much larger set of people that you really don't want to give
shell access to.

Therefore, gitolite tries very hard to make sure that people in the first set
are not allowed to do anything that gets them into the second set.