doc/rcs/git.mdwn

   1 [[meta title="Git"]]
   2
   3 [Git][git] is a distributed revison control system originally developed for
   4 the Linux kernel. Ikiwiki supports storing a wiki in git.
   5
   6 [git]: http://git.or.cz/
   7
   8 Ikiwiki can run as a `post-update` hook to update a wiki whenever commits
   9 come in. When running as a [[cgi]] with Git, ikiwiki automatically
  10 commits edited pages, and uses the Git history to generate the
  11 [[RecentChanges]] page.
  12
  13 ## git repository setup
  14
  15 When using Git, you probably want to set up two repositories, of which
  16 one should be bare (meaning that it does not have a working tree
  17 checked out), and the other one with a working tree will be used as
  18 ikiwiki's srcdir for compiling the wiki. [[ikiwiki-makerepo]] can automate
  19 setting this up. Using a pair of repositories isn't the most obvious set up,
  20 but it works the best for typical ikiwiki use.
  21 [[tips/Laptop_wiki_with_git]] describes a different way to set up ikiwiki
  22 and git.
  23
  24 It is **paramount** that you **never** push to the non-bare repository
  25 ([this FAQ entry explains why](http://git.or.cz/gitwiki/GitFaq#head-b6a3d85f677763313159eb39f7dbf4579d4ee28b)).
  26 Instead, if you want to work on the wiki from a remote machine, clone
  27 the bare repository, using either the `git` transport (if available), or
  28 `ssh`.
  29
  30 The ikiwiki `post-commit` hook should be put in the bare repository.
  31
  32 ## git repository with multiple committers
  33
  34 It can be tricky to get the permissions right to allow multiple people to
  35 commit to an ikiwiki git repository. As the [[security]] page mentions,
  36 for a secure ikiwiki installation, only one person should be able to write
  37 to ikiwiki's srcdir. When other committers make commits, their commits
  38 should go to the bare repository, which has a `post-update` hook that uses
  39 ikiwiki to pull the changes to the srcdir.
  40
  41 One setup that will work is to put all committers in a group (say,
  42 "ikiwiki"), and use permissions to allow that group to commit to the bare git
  43 repository. Make both the post-update hook and ikiwiki.cgi be setgid
  44 to the group, as well as suid to the user who admins the wiki. The
  45 `wrappergroup` [[setup_file_option|usage]] can be used to make the wrappers
  46 be setgid to the right group. Then the srcdir, including its git
  47 repository, should only be writable by the wiki's admin, and *not* by the
  48 group. Take care that ikiwiki uses a umask that does not cause files in
  49 the srcdir to become group writable. (umask 022 will work.)