## git repository setup
-When using Git, you probably want to set up two repositories, of which
-one should be bare (meaning that it does not have a working tree
-checked out), and the other one with a working tree will be used as
-ikiwiki's srcdir for compiling the wiki. [[ikiwiki-makerepo]] can automate
-setting this up. Using a pair of repositories isn't the most obvious set up,
-but it works the best for typical ikiwiki use.
-[[tips/Laptop_wiki_with_git]] describes a different way to set up ikiwiki
-and git.
+The suggested setup for git is a set of repositories setup like a
+shallow, single level tree, with a bare repository (meaning that it
+does not have a working tree checked out) at the root, and various
+working clones (with working directories) as leaf nodes. The root
+(bare) repository is meant to be pushed to and pulled from the various
+working clones. The image below displays the relationship between the
+root repository and the clone repositories (this is not a directory
+layout):
+
+
+
+One of the leaf node clone repositories is special; it has working
+directory which is used to compile the wiki from, and is also used by the
+[[cgi]] to commit changes made via the web interface. It is special
+since the `post-commit` hook for the bare root repository is used to
+trigger an update of this repository, and then an ikiwiki refresh
+updates the published wiki itself.
+
+The other (optional) leaf node repositories are meant for you to work
+on, and commit to, changes should then be pushed to the bare root
+repository. In theory, you could work on the same leaf node repository
+that ikiwiki uses to compile the wiki from, and the [[cgi]] commits
+to, as long as you ensure that permissions and ownership don't hinder
+the working of the [[cgi]]. This can be done, for example, by using
+ACL's, in practice, it is easier to just setup separate clones for
+yourself.
+
+So, to reiterate, when using Git, you probably want to set up three
+repositories:
+
+* The root repository. This should be a bare repository (meaning that
+ it does not have a working tree checked out), which the other
+ repositories will push to/pull from. It is a bare repository, since
+ there are problems pushing to a repository that has a working
+ directory. This is called _repository_ in [[ikiwiki-makerepo]]'s
+ manual page.
+
+ Nominally, this bare repository has a `post-commit` hook that either
+ is or calls ikiwiki's git wrapper, which changes to the working
+ directory for ikiwiki, does a _git pull_, and refreshes ikiwiki to
+ regenerate the wiki with any new content.
+
+ The configuration sections below show how to let the post-commit
+ hook be replaced by the ikiwiki git wrapper.
+* The second repository is a clone of the bare root repository, and
+ has a working tree which is used as ikiwiki's srcdir for compiling
+ the wiki. **Never** push to this repository. When running as a
+ [[cgi]], the changes are committed to this repository, and pushed to
+ the master repository above. This is called _srcdir_ in
+ [[ikiwiki-makerepo]]'s manual page.
+* The other (third, fourth, fifth, sixth -- however many pleases you)
+ repositories are also clones of the bare root repository above --
+ and these have a working directory for you to work on. Use either
+ the `git` transport (if available), or `ssh`. These repositories may
+ be on remote machines, your laptop, whereever you find convenient to
+ hack on your wiki. you can commit local changes to the version on
+ the laptop, perhaps while offline. You can browse and edit the wiki
+ using a local web server. Any new content should be pushed to the
+ bare master repository when you are ready to publish it, and then
+ the post-commit hook of the bare repository will ensure that the
+ ikiwiki's source directory is updated, and the ikiwiki refreshed
+ with the new content.
+
+Using three or more of repositories isn't the most obvious set up, but
+it works the best for typical ikiwiki use. [[ikiwiki-makerepo]] can
+automate setting this up for the common case where there is no
+pre-existing wiki. [[tips/Laptop_wiki_with_git]] describes a different
+way to set up ikiwiki and git.
It is **paramount** that you **never** push to the non-bare repository
-([this FAQ entry explains why](http://git.or.cz/gitwiki/GitFaq#head-b6a3d85f677763313159eb39f7dbf4579d4ee28b)).
-Instead, if you want to work on the wiki from a remote machine, clone
-the bare repository, using either the `git` transport (if available), or
-`ssh`.
+([this FAQ entry explains why](http://git.or.cz/gitwiki/GitFaq#head-b96f48bc9c925074be9f95c0fce69bcece5f6e73)).
+Instead, clone the bare repository as mentioned above, and push
+**only** to the bare repository.
The ikiwiki `post-commit` hook should be put in the bare repository.
+
+## git repository with multiple committers
+
+It can be tricky to get the permissions right to allow multiple people to
+commit to an ikiwiki git repository. As the [[security]] page mentions,
+for a secure ikiwiki installation, only one person should be able to write
+to ikiwiki's srcdir. When other committers make commits, their commits
+should go to the bare repository, which has a `post-update` hook that uses
+ikiwiki to pull the changes to the srcdir.
+
+One setup that will work is to put all committers in a group (say,
+"ikiwiki"), and use permissions to allow that group to commit to the bare git
+repository. Make both the post-update hook and ikiwiki.cgi be setgid
+to the group, as well as suid to the user who admins the wiki. The
+`wrappergroup` [[setup_file_option|usage]] can be used to make the wrappers
+be setgid to the right group. Then the srcdir, including its git
+repository, should only be writable by the wiki's admin, and *not* by the
+group. Take care that ikiwiki uses a umask that does not cause files in
+the srcdir to become group writable. (umask 022 will work.)
+
+## Configuration of working clone repositories
+
+These are repositories (Clone 1 .. N in the image) usually setup to
+avoid permission problems with the working directory used by ikiwiki
+itself. They also represent the most convenient way to add content to
+the wiki on a different machine (that is, not the machine the wiki is
+published on) which is more convenient.
+
+The use case for these clones is this: If you want to edit your wiki
+on your development box, or on your laptop, you usually set up a clone
+as above. But very often, you also want to test what the changes look
+like, locally, before pushing it to the root repository and publishing
+the wiki for the world to see.
+
+In order to do this, you should another setup file and setup a private
+ikiwiki on the local machine (your laptop, for instance) where you do
+most of your editing. You will also need to set up a webserver, and
+install ikiwiki on this machine. Only when you are happy with any
+changes do you push them to the root repository.
+
+Here are some things to be aware of when configuring ikiwiki on the
+local machine:
+
+* By default, ikiwiki pulls and pushes from `origin`. This is not
+ ideal for the working clones on the local machine, since you might
+ go through several iterations of a page before pushing to the bare
+ root of the repository tree and publishing it on your public
+ wiki. In the configuration, set:
+
+ gitorigin_branch => "",
+ ## git post-commit wrapper
+ wrapper => "/working/dir/.git/hooks/post-commit",
+
+ Then just committing should refresh the private ikiwiki on the local
+ host.
+
+* You can optionally enable to the [[plugins/mirrorlist]] plugin,
+ and configure it so that each page links to the corresponding page on the
+ server.
+
+Now just run `ikiwiki -setup wiki.setup -getctime` and you should be
+good to go. (You only need the slow `-getctime` option the first time you
+run setup.)
+
+Use standard git commands to handle pulling from and pushing to the server.
+
+Note: Currently, after pulling changes, you will need to manually update
+the wiki, with a command such as `ikiwiki -setup wiki.setup -refresh`. This
+is because git 1.5.4 doesn't have a hook that is run locally after pulling
+changes. Newer versions of git will have a `post-merge` hook that should
+work for this purpose.