docs/rc.mkd

   1 # the "rc" file (`$HOME/.gitolite.rc`)
   2
   3 ----
   4
   5 **IMPORTANT**: if you have a v3.0-v3.3 rc file it is documented [here](rc-33),
   6 and it will still work.  Please see appendix A below for details.
   7
   8 ----
   9
  10 The rc file is designed to be the only thing unique to your site for most
  11 setups.
  12
  13 The rc file is well commented.  Please look at the `~/.gitolite.rc` file that
  14 gets installed when you setup gitolite.  **You can always get a default copy
  15 for your current version by running `gitolite print-default-rc`.**  (Please
  16 see appendix A for upgrade instructions.)
  17
  18 # structure of the rc file
  19
  20 The rc file is perl code, but you do NOT need to know perl to edit it.  Just
  21 mind the commas, use single quotes unless you know what you're doing, and make
  22 sure the brackets and braces stay matched up!
  23
  24 As you can see there are 3 types of variables in it:
  25
  26   * A lot of simple variables (like `UMASK`, `GIT_CONFIG_KEYS`, etc.).
  27   * A hash or two (like `ROLES`).
  28   * And one large list of features to be enabled (`ENABLE`).
  29
  30 This page documents only some of them; for most of them it's best to look in
  31 the actual rc file or in each of their individual documentation files around;
  32 start with ["non-core" gitolite](non-core).  If a setting is used by a command
  33 then running that command with '-h' may give you additional information.
  34
  35 # specific variables
  36
  37   * `$UMASK`, octal, default `0077`
  38
  39     The default UMASK that gitolite uses gives `rwx------` permissions to all
  40     the repos and their contents.  People who want to run gitweb (or cgit,
  41     redmine, etc) realise that this will not do.
  42
  43     The correct way to deal with this is to give this variable a value like
  44     `0027` (note the syntax: the leading 0 is required), and then make the
  45     user running the webserver (apache, www-data, whatever) a member of the
  46     'git' group.
  47
  48     If you've already installed gitolite then existing files will have to be
  49     fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
  50     This is because umask only affects permissions on newly created files, not
  51     existing ones.
  52
  53   * `$GIT_CONFIG_KEYS`, string, default empty
  54
  55     <span class="box-r">See the [security note][privesc] at the end of this
  56     page for why we do this.</span>
  57
  58     This setting allows the repo admin to define acceptable gitconfig keys.
  59
  60     Gitolite allows you to set git config values using the "config" keyword;
  61     see [here](git-config) for details and syntax.
  62
  63     You have 3 choices.  By default `$GIT_CONFIG_KEYS` is left empty, which
  64     completely disables this feature (meaning you cannot set git configs via
  65     the repo config).
  66
  67     The second choice is to give it a space separated list of settings you
  68     consider safe.  (These are actually treated as a set of [regular
  69     expressions](regex), and any one of them must match).
  70
  71     For example:
  72
  73         $GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
  74
  75     Each regex should match the *whole* key (in other words, there
  76     is an implicit `^` at the start of each regex, and a `$` at the
  77     end).
  78
  79     The third choice (which you may have guessed already if you're familiar
  80     with regular expressions) is to allow anything and everything:
  81     `$GIT_CONFIG_KEYS = '.*';`
  82
  83   * `ROLES`, hash, default keys 'READERS' and 'WRITERS'
  84
  85     This specifies the role names allowed to be used by users running the
  86     [perms][] command.  The [wild](wild) repos doc has more info on roles.
  87
  88   * `OWNER_ROLENAME`, string, default undef
  89
  90     (requires v3.5 or later)
  91
  92     By default, permissions on a wild repo can only be set by the *creator* of
  93     the repo (using the [perms][] command).  But some sites want to allow
  94     other people to do this as well.
  95
  96     To enable this behaviour, the server admin must first set this variable to
  97     some string, say 'OWNERS'.  (He must also add 'OWNERS' to the ROLES hash
  98     described in the previous bullet).
  99
 100     The creator of the repo can then add other users to the OWNERS role using
 101     the [perms][] command.
 102
 103     The [perms][] command, the new "owns" command, and possibly other commands
 104     in future, will then give these users the same privileges that they give
 105     to the creator of the repo.
 106
 107     (Also see the full documentation on [roles][]).
 108
 109   * `LOCAL_CODE`, string
 110
 111     This is described in more detail [here][localcode].  Please be aware
 112     **this must be a FULL path**, not a relative path.
 113
 114 [privesc]: rc#security-note-gitolite-admin-and-shell-access
 115 [perms]: user#setget-additional-permissions-for-repos-you-created
 116 [roles]: wild#roles
 117 [localcode]: non-core#for-your-non-core-programs
 118
 119 # security note: gitolite admin and shell access
 120
 121 People sometimes ask why this file is also not revision controlled.  Here's
 122 why.
 123
 124 Gitolite maintains a clear distinction between
 125
 126 *   people who can push to the gitolite-admin repo, and
 127 *   people who can get a shell or run arbitrary commands on the server.
 128
 129 This may not matter to many (small) sites, but in large installations, the
 130 former is often a much larger set of people that you really don't want to give
 131 shell access to.
 132
 133 Therefore, gitolite tries very hard to make sure that people in the first set
 134 are not allowed to do anything that gets them into the second set.
 135
 136 !!! note ""
 137
 138     If you *must* revision control it, you can.  Just add it to your admin
 139     repo, push the change, then replace `~/.gitolite.rc` with a symlink to
 140     `~/.gitolite/.gitolite.rc`.</span>
 141
 142 # appendix A: upgrading the rc file
 143
 144 First, note that upgrading the rc file is always *optional*.  However, it may
 145 help if you want to use any of the new features available in later gitolite
 146 releases, in the sense that the lines you need to add may already be present
 147 (commented out) in the rc file, so you just need to uncomment them instead of
 148 typing them in yourself.
 149
 150 If you have a v3.0-v3.3 rc file it is documented [here](rc-33), and it will
 151 still work.  In fact internally the v3.4 rc file data gets converted to the
 152 v3.3 format.  There's a simple program to help you upgrade a v3.3 (or prior)
 153 rc file (in <span class="gray">v3.6.1+</span>, see contrib/utils/rc-format-v3.4), but it has
 154 probably not seen too much testing; please tread carefully and report any
 155 problems you find.
 156
 157 Upgrading from any v3.4+ rc file to any later gitolite is fairly easy, though
 158 still manual.  One useful aid is that, as of v3.6.4, you can run `gitolite query-rc -d`
 159 to dump the entire rc structure to STDOUT.  **This only requires
 160 that gitolite be v3.6.4+; your rc file can still be the old one.**  You can
 161 use this to confirm you did not miss something during the manual rc upgrade.
 162
 163 *   dump the current rc by running `gitolite query-rc -d > old.dump` (assuming
 164     you upgraded to v3.6.4 or higher)
 165
 166 *   save your old rc file: `mv ~/.gitolite.rc ~/old.gitolite.rc`
 167
 168 *   get a "default" rc for your current gitolite by running
 169
 170         gitolite print-default-rc > ~/.gitolite.rc
 171
 172 *   use your favourite diff-ing editor on the old and the new files and figure
 173     out what to carry over from the old rc file to the new one.
 174
 175         vimdiff ~/old.gitolite.rc ~/.gitolite.rc
 176         # or maybe kdiff3 or whatever
 177
 178     This is the tricky part of course!  Watch out for configs that got *moved*
 179     around, or in some cases removed completely, not just new config items.
 180
 181 *   dump the new rc by running `gitolite query-rc -d > new.dump`
 182
 183 *   compare the 2 rc dumps to make sure you've got everything covered.
 184
 185 # appendix B: making a trigger run *after* the built-in ones
 186
 187 For most purposes, the section on [adding your own scripts to a
 188 trigger][addtrig] works fine.
 189
 190 [addtrig]: triggers#adding-your-own-scripts-to-a-trigger
 191
 192 But triggers added that way, run *before* the built-in triggers, which you can
 193 also confirm by running `gitolite query-rc -d` and looking for your trigger in
 194 the output.
 195
 196 If you need your trigger to run *after* the built-in ones, it *is* possible,
 197 it's a wee bit more work.
 198
 199 Let's say you have a post-compile script called "my-custom-config", and you
 200 want it to run *after* the shipped post-compile scripts. Here's what you do:
 201
 202 *   add something like 'my-cust' (could be anything you like, as long as
 203     it matches the next step) to the ENABLE list in the rc file. Dont
 204     forget the trailing comma if it's not the last element (and in perl
 205     you can add a trailing comma even if it *is* the last element)
 206
 207 *   after the ENABLE list, but still within the RC hash, add this:
 208
 209         NON_CORE => "
 210         my-cust POST_COMPILE post-compile/my-custom-config
 211         ",
 212
 213     The words in caps are fixed. The others you know, and as you can see
 214     the "my-cust" here matches the "my-cust" in the ENABLE list.
 215
 216 After you do this, you can test whether it worked or not:
 217
 218     gitolite query-rc POST_COMPILE
 219
 220 and it should show you what it thinks are the items in that list, in the
 221 order it has them.
 222
 223 <!--
 224 -   from https://groups.google.com/forum#!searchin/gitolite/NON_CORE/gitolite/2kZaqLohSz0/LsIo_W8B2I8J
 225
 226 -   document 'before' option (default: goes to the end)
 227 -   document arguments supplied via ENABLE list
 228 -->
 229
 230 # appendix C: overriding safety-net patterns
 231
 232 Apart from [`UNSAFE_PATT`][unsafepatt], there are other patterns that
 233 gitolite uses to prevent various attacks.  They're all defined in `Rc.pm` in
 234 the source, but you can override any of them in `~/.gitolite.rc` if needed.
 235
 236 [unsafepatt]: git-config.html#compensating-for-unsafe_patt-and-other-patterns
 237
 238 !!! danger "DANGER!"
 239
 240     Overriding any of these regexes may impact the security of the
 241     installation severly if you are not careful.  You have been warned!
 242
 243 The patterns are:
 244
 245     $REMOTE_COMMAND_PATT  =                qr(^[-0-9a-zA-Z._\@/+ :,\%=]*$);
 246     $REF_OR_FILENAME_PATT =     qr(^[0-9a-zA-Z][-0-9a-zA-Z._\@/+ :,]*$);
 247     $REPONAME_PATT        =  qr(^\@?[0-9a-zA-Z][-0-9a-zA-Z._\@/+]*$);
 248     $REPOPATT_PATT        = qr(^\@?[[0-9a-zA-Z][-0-9a-zA-Z._\@/+\\^$|()[\]*?{},]*$);
 249     $USERNAME_PATT        =  qr(^\@?[0-9a-zA-Z][-0-9a-zA-Z._\@+]*$);
 250
 251 To override any of them, just add a new definition for the pattern at the
 252 **very end** of your rc file, just before the `1;` line.  E.g., to allow
 253 usernames to have a leading underscore, you might add:
 254
 255     $USERNAME_PATT        =  qr(^\@?[_0-9a-zA-Z][-0-9a-zA-Z._\@+]*$);
 256
 257 Needless to say you should be very comfortable with regexes to attempt this :)