docs/git-config.mkd

   1 # specifying "git-config" keys and values
   2
   3 ----
   4
   5 <span class="gray">(Original version thanks to teemu dot matilainen at iki dot fi.)</span>
   6
   7 !!! danger ""
   8
   9     **Important**: This won't work unless the rc file has the right settings;
  10     please see `$GIT_CONFIG_KEYS` in the [rc file doc](rc#specific-variables).
  11
  12 # basic syntax
  13
  14 The syntax is simple:
  15
  16     config sectionname.keyname = value
  17
  18 For example:
  19
  20 ```gitolite
  21 repo gitolite
  22     config hooks.mailinglist = gitolite-commits@example.tld
  23     config hooks.emailprefix = "[gitolite] "
  24     config foo.bar = ""
  25 ```
  26
  27 This does either a plain "git config section.key value" (for the first 2
  28 examples above) or "git config --unset-all section.key" (for the last
  29 example).  Other forms of the `git config` command (`--add`, the
  30 `value_regex`, etc) are not supported.
  31
  32 ## <span class="red">an important warning about **deleting** a config line</span>
  33
  34 !!! danger ""
  35
  36     Simply deleting the config line from the `conf/gitolite.conf` file will
  37     *not* delete the variable from `repo.git/config`.  You have to use the
  38     syntax in the last example to make gitolite execute a `--unset-all`
  39     operation on the given key.
  40
  41 # substituting the repo name and the creator name
  42
  43 You can also use the special values `%GL_REPO` and `%GL_CREATOR` in the
  44 string.  The former is available to all repos, while the latter is only
  45 available to [wild](wild) repos.
  46
  47 ```gitolite
  48 repo foo bar baz
  49     config hooks.mailinglist = %GL_REPO-commits@example.tld
  50     config hooks.emailprefix = "[%GL_REPO] "
  51 ```
  52
  53 # <span class="gray">(v3.6.7+)</span> expanding a group name
  54
  55 If you add
  56
  57     EXPAND_GROUPS_IN_CONFIG     =>  1,
  58
  59 to the rc file (suggested location: just after the `GIT_CONFIG_KEYS` line),
  60 then the *value* of a config line will have groupnames expanded.  For example:
  61
  62 ```gitolite
  63 @admins = sitaramc@gmail.com jdoe@example.com
  64 ...
  65 repo foo
  66     ...
  67     config hooks.mailinglist = @admins
  68 ```
  69
  70 will behave as if the two email addresses were explicitly listed in the config
  71 line.  However, if there is no such group, the text will be left as-is.  Also,
  72 for safety, only word characters (alphanumerics and underscore) are expected
  73 as part of the group name.
  74
  75 # overriding config values
  76
  77 You can repeat the 'config' line as many times as you like, and the *last*
  78 occurrence will be the one in effect.  This allows you to override settings
  79 just for one project, as in this example:
  80
  81 ```gitolite
  82 repo @all
  83     config hooks.mailinglist = %GL_REPO-commits@example.tld
  84     config hooks.emailprefix = "[%GL_REPO] "
  85
  86 # ... later ...
  87
  88 repo customer-project
  89     # different mailing list
  90     config hooks.mailinglist = announce@customer.tld
  91 ```
  92
  93 The "delete config variable" syntax can also be used, if you wish:
  94
  95 ```gitolite
  96 repo secret     # no emails for this one please
  97     config hooks.mailinglist = ""
  98     config hooks.emailprefix = ""
  99 ```
 100
 101 As you can see, the general idea is to place the most generic ones (`repo @all`,
 102 or repo regex like `repo foo.*`) first, and place more specific ones
 103 later to override the generic settings.
 104
 105 # compensating for UNSAFE\_PATT (and other patterns)
 106
 107 An important feature in gitolite is that you can share the admin load with
 108 more people, **without** having to give all of them shell access on the
 109 server.  Thus there are some restrictions designed to prevent someone who can
 110 push the gitolite-admin repo, from somehow managing to run arbitrary commands
 111 on the server.
 112
 113 This section is about one of these restrictions.
 114
 115 Gitolite, by default, does not allow the following characters in the value of
 116 a config variable: `` ` ~ # $ & ( ) | ; < > ``.  This is due to unspecified
 117 paranoia; see [this discussion][ud] for some context.  This restriction is
 118 enforced by a regex called `UNSAFE_PATT`, whose default value is
 119 ``[`~#\$\&()|;<>]``.
 120
 121 [ud]: https://groups.google.com/d/topic/gitolite/9WNsA-Axmg4/discussion
 122
 123 But let's say you need to do this, which fails due to the semicolon.
 124
 125 ```gitolite
 126     config hooks.showrev = "git show -C %s; echo"
 127 ```
 128
 129 There are two ways to fix this.
 130
 131 **If all your admins already have shell access**, you can override this by
 132 placing a modified version in the rc file.  For our example, you'd just put
 133 the following line at the **very end** of your rc file, just before the `1;`
 134 line (notice there is no semicolon in the regex here):
 135
 136     $UNSAFE_PATT          = qr([`~#\$\&()|<>]);
 137
 138 Similarly, you can remove other characters from that regex (to allow those
 139 characters in your config values).
 140
 141 **If all your admins do not have shell access**, you need a more fine-grained
 142 method:
 143
 144   * In the rc file, add the following within the '%RC' hash (for example, just
 145     after the UMASK line would do fine):
 146
 147         SAFE_CONFIG => {
 148             SHOWREV         =>  "git show -C %s; echo"
 149         },
 150
 151   * In your gitolite.conf file, add this instead of the line we saw earlier:
 152
 153 ```gitolite
 154     config hooks.showrev = %SHOWREV
 155 ```
 156
 157 This mechanism allows you to add any number of **specific** violations to the
 158 `UNSAFE_PATT` rule instead of denaturing the regex itself and potentially
 159 allowing something that could be (ab)used by a repo admin to obtain shell
 160 access at some later point in time.
 161
 162 A similar problem arises with email addresses, which contain the `<` and `>`
 163 characters.  Here's how to deal with that easily:
 164
 165   * In the rc file:
 166
 167         SAFE_CONFIG => {
 168             LT              =>  '<',
 169             GT              =>  '>',
 170         },
 171
 172   * In the gitolite.conf file:
 173
 174 ```gitolite
 175     config hooks.mailinglist = "Sitaram Chamarty %LTsitaramc@gmail.com%GT"
 176 ```
 177
 178 Admittedly, that looks a wee bit ugly, but it gets the job done without having
 179 to remove angle brackets from UNSAFE\_PATT.
 180