minor stuff

[gitolite-doc.git] / rc.mkd

<!-- options: toc -->

% 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.  Please see appendix A below for details.

@@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.

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`.**  (Please
see appendix A for upgrade instructions.)

# structure of the rc file

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!

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.

# appendix A: upgrading the rc file

First, note that upgrading the rc file is always *optional*.  However, it may
help if you want to use any of the new features available in later gitolite
releases, in the sense that the lines you need to add may already be present
(commented out) in the rc file, so you just need to uncomment them instead of
typing them in yourself.

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.  There's a simple program to help you upgrade a v3.3 (or prior)
rc file (in @@gray(v3.6.1+)@@, see contrib/utils/rc-format-v3.4), but it has
probably not seen too much testing; please tread carefully and report any
problems you find.

Upgrading from any v3.4+ rc file to any later gitolite is fairly easy, though
still manual.  One useful aid is that, as of v3.6.4, you can run `gitolite
query-rc -d` to dump the entire rc structure to STDOUT.  **This only requires
that gitolite be v3.6.4+; your rc file can still be the old one.**  You can
use this to confirm you did not miss something during the manual rc upgrade.

*   dump the current rc by running `gitolite query-rc -d > old.dump` (assuming
    you upgraded to v3.6.4 or higher)

*   save your old rc file: `mv ~/.gitolite.rc ~/old.gitolite.rc`

*   get a "default" rc for your current gitolite by running

        gitolite print-default-rc > ~/.gitolite.rc

*   use your favourite diff-ing editor on the old and the new files and figure
    out what to carry over from the old rc file to the new one.

        vimdiff ~/old.gitolite.rc ~/.gitolite.rc
        # or maybe kdiff3 or whatever

    This is the tricky part of course!  Watch out for configs that got *moved*
    around, or in some cases removed completely, not just new config items.

*   dump the new rc by running `gitolite query-rc -d > new.dump`

*   compare the 2 rc dumps to make sure you've got everything covered.