[git]: http://git.or.cz/
-Ikiwiki can run as a post-update hook to update a wiki whenever commits
+Ikiwiki can run as a `post-update` hook to update a wiki whenever commits
come in. When running as a [[cgi]] with Git, ikiwiki automatically
commits edited pages, and uses the Git history to generate the
[[RecentChanges]] page.
-[[Setup]] documents current best practice for using git with ikiwiki. This
-involves setting up a pair of git repositories. This method isn't the most
-obvious, but it works the best.
+## git repository setup
+
+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 [[setup]] page describes
+ how to do this.
+
+* 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. 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-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.)
+
+## Optionally using a local wiki to preview changes
+
+When working on the "working clones" to add content to your wiki,
+it is common (but optional) practice to preview your changes using a
+private wiki on the local host before publishing the updates by
+sending it to the root repository. If you do want to setup a private
+wiki, you will have to have another setup file and and an ikiwiki
+installation on your local machine. You will need all the packages
+this implies -- a web server, git, ikiwiki, etc. However, there is a
+_caveat_: 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 thus publishing it on your public wiki).
+You do not want the action of refreshing the local wiki in order to
+review your work to accidentally publish the
+contents before you are ready. In order to prevent the git push that
+is the normal behaviour of ikiwiki, set the configuration of the local wiki:
+
+ 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. Now just run `ikiwiki -setup localwiki.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 from the bare root repository, you will need to
+manually update the local wiki, with a command such as `ikiwiki
+-setup localwiki.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.
-See also: [[common_git_pitfalls|/setup/git_pitfalls]]