the "rc" file (
IMPORTANT: if you have a v3.0-v3.3 rc file it is documented here, and it will still work. Please see appendix A below for details.
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
- A hash or two (like
- And one large list of features to be enabled (
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. If a setting is used by a command then running that command with '-h' may give you additional information.
$UMASK, octal, default
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
See the security note 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 for details and syntax.
You have 3 choices. By default
$GIT_CONFIG_KEYSis 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).
$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'
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).
This is described in more detail here. Please be aware this must be a FULL path, not a relative path.
security note: gitolite admin and shell access
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.
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
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, 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 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.
appendix B: making a trigger run after the built-in ones
For most purposes, the section on adding your own scripts to a trigger works fine.
But triggers added that way, run before the built-in triggers, which you can
also confirm by running
gitolite query-rc -d and looking for your trigger in
If you need your trigger to run after the built-in ones, it is possible, it's a wee bit more work.
Let's say you have a post-compile script called "my-custom-config", and you want it to run after the shipped post-compile scripts. Here's what you do:
add something like 'my-cust' (could be anything you like, as long as it matches the next step) to the ENABLE list in the rc file. Dont forget the trailing comma if it's not the last element (and in perl you can add a trailing comma even if it is the last element)
after the ENABLE list, but still within the RC hash, add this:
NON_CORE => " my-cust POST_COMPILE post-compile/my-custom-config ",
The words in caps are fixed. The others you know, and as you can see the "my-cust" here matches the "my-cust" in the ENABLE list.
After you do this, you can test whether it worked or not:
gitolite query-rc POST_COMPILE
and it should show you what it thinks are the items in that list, in the order it has them.