git-config.mkd

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