gitolite/doc/rc.mkd
Sitaram Chamarty 9e1cb5936c (some docfixes)
2012-04-24 14:10:40 +05:30

100 lines
4.1 KiB
Markdown

# 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",