docs/odds-and-ends.mkd

   1 # miscellaneous features
   2
   3 ----
   4
   5 This page has a bunch of features that didn't seem to fit anywhere.
   6
   7 # disabling pushes to take backups
   8
   9 The `writable` command allows you to disable pushes to all repos or just the
  10 named repo, in order to do file-system level things to the repo directory that
  11 require it not to change, like using normal backup software.
  12
  13 Run `gitolite writable -h` for more info.
  14
  15 # putting 'repositories' and '.gitolite' elsewhere
  16
  17 Gitolite insists that the "repositories" and ".gitolite" directories be in
  18 `$HOME`.  If you want them somewhere else:
  19
  20   * do the install as normal,
  21   * *then* move those directories to wherever you want and replace them with
  22     symlinks pointing to the new location.
  23
  24 # using pubkeys obtained from elsewhere
  25
  26 If you're not managing keys via the gitolite-admin repo, but getting them from
  27 somewhere else, you'll want to periodically "update" the keys.
  28
  29 To do that, first edit your rc file and add something like this:
  30
  31     SSH_AUTHKEYS                =>
  32         [
  33             'post-compile/ssh-authkeys',
  34         ],
  35
  36 Then write a script that
  37
  38   * gets all the keys and dumps them into `$HOME/.gitolite/keydir` (or into a
  39     subdirectory of it), and
  40   * runs `gitolite trigger SSH_AUTHKEYS`.
  41
  42 Run this from cron or however you want.
  43
  44 # giving users their own repos
  45
  46 (Please see [this](wild) for background on the ideas in this section).
  47
  48 It's very easy to give users their own set of repos to create, with the
  49 username at the top level.  The simplest setup is:
  50
  51 ```gitolite
  52 repo CREATOR/..*
  53     C   =   @all
  54     RW+ =   CREATOR
  55     RW  =   WRITERS
  56     R   =   READERS
  57 ```
  58
  59 Now users can create any repo under their own name simply by cloning it or
  60 pushing to it, then use the [perms][] command to add other users to their
  61 WRITERS and READERS lists.
  62
  63 [perms]: user#setget-additional-permissions-for-repos-you-created
  64
  65 Of course you can get much more creative if you add a few more [roles][].
  66
  67 [roles]: wild#roles
  68
  69 <font color="gray">(I prefer using some prefix, say "u", as in
  70 `repo u/CREATOR/..*`.  This helps to keep user-created repos separate, and
  71 avoid name clashes in some far-fetched scenarios).</font>
  72
  73 # administering gitolite directly on the server
  74
  75 The main use of managing gitolite via the admin repo is that you get to
  76 version control the access rules.  But for large sites, there's another use:
  77 you can share the admin load with more people, **without** having to give all
  78 of them shell access on the server.
  79
  80 However, people who use puppet and similar systems already have a conf
  81 versioning and management system.  And they'd like to continue to use that to
  82 manage gitolite repos and users, rather than be forced to do it through the
  83 gitolite-admin repo.
  84
  85 Such sites don't really need the admin repo at all, so here's how to get rid
  86 of it and run things directly on the server (which you can script into your
  87 puppet or similar software quite easily).
  88
  89 First the one-time stuff:
  90
  91   * [install](install) the software as normal
  92
  93   * run `gitolite setup -a dummy` instead of the normal [setup](install#setup)
  94     command
  95
  96   * delete (or move away) `~/repositories/gitolite-admin.git`
  97
  98   * edit `~/.gitolite/conf/gitolite.conf` and remove the gitolite-admin repo
  99     and its access line.
 100
 101   * `mkdir ~/.gitolite/keydir` (because "setup -a" does not create it, but you
 102     will need it later to add keys).
 103
 104   * run `gitolite compile; gitolite trigger POST_COMPILE`
 105
 106 To manage gitolite, you can directly edit files in `~/.gitolite` (or cause
 107 puppet to place files there), and then run the commands in the last step
 108 above.  For example:
 109
 110   * copy someone's pubkey file to `~/.gitolite/keydir`
 111   * edit `~/.gitolite/conf/gitolite.conf` and add a repo or three, giving
 112     access to some user(s)
 113   * run `gitolite compile; gitolite trigger POST_COMPILE`
 114
 115 That's it.
 116