[git]: http://git.or.cz/
-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.
+Ikiwiki can run as a git `post-update` hook to update a wiki
+whenever commits come in. When running as a [[cgi]],
+ikiwiki automatically commits edited pages, and uses the
+git history to generate the [[RecentChanges]] page.
+
+Normally you can just follow the instructions in [[setup]] to create
+the git repositories and get started. To understand the details, read on.
## 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.
+[[!img wiki_edit_flow.svg size=490x align=right]]
+
+The suggested setup for git has a bare repository, and various
+working clones (with working directories). The bare
+repository is pushed to and pulled from the various working clones.
-One of the leaf node clone repositories is special; it has working
-directory which is used to compile the wiki, and is also used by the
+One of the clones is special; it is the srcdir
+which is used to compile the wiki, and is also used by the
[[cgi]] to commit changes made via the web interface. It is special
since the `post-update` 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.
+updates the published wiki itself.
-The other (optional) leaf node repositories are meant for you to work
+The other (optional) clones are meant for you to work
on, and commit to, changes should then be pushed to the bare root
repository.
-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
- git does not support pushing to a repository that has a working
- directory. This is called _repository_ in [[ikiwiki-makerepo]]'s
- manual page. This bare repository has a `post-update` 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, but note, if you are importing from an existing git repository, that ikiwiki will not create the `git_wrapper` unless its path is explicitely set in your `.setup` file.
-
-* 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. It is wise to not make
- changes or commits directly to this repository, to avoid conflicting
- with ikiwiki's own changes. 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, wherever 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-update 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
+Using three or more 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-update` 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
## Optionally using a local wiki to preview changes
-When working on the "working clones" to add content to your wiki,
+When working on 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
git_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
+host. Now just run `ikiwiki -setup localwiki.setup -gettime` and
+you should be good to go. (You only need the slow `-gettime` option
the first time you run setup.) Use standard git commands to handle
-pulling from and pushing to the server. **Note**: Currently, after
+pulling from and pushing to the server. **Note**: 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.
-
-## Fix for error on git pull origin
-
-Error message when running git pull origin:
-
- You asked me to pull without telling me which branch you
- want to merge with, and 'branch.master.merge' in
- your configuration file does not tell me either. Please
- name which branch you want to merge on the command line and
- try again (e.g. 'git pull <repository> <refspec>').
- See git-pull(1) for details on the refspec.
-
- If you often merge with the same branch, you may want to
- configure the following variables in your configuration
- file:
-
- branch.master.remote = <nickname>
- branch.master.merge = <remote-ref>
- remote.<nickname>.url = <url>
- remote.<nickname>.fetch = <refspec>
-
- See git-config(1) for details.
-
-The solution is to run this command in your srcdir:
-
- git config branch.master.remote origin
+-setup localwiki.setup -refresh`. You could use git's `post-merge` hook
+to automate that command.
+
+## Using ikiwiki with Gerrit
+
+[Gerrit Code Review](https://code.google.com/p/gerrit/) manages a set of Git
+repositories and provides a web interface to review and merge commits. You can
+configure ikiwiki to work with a Gerrit-managed repository, allowing you to
+review and merge commits to your wiki.
+
+First, create your initial wiki repository with Gerrit. On the server, as the
+user that will own the wiki, clone that repository to create a working
+directory for ikiwiki, such as /srv/wiki/ikiwiki-checkout. Create a setup file
+and target directory as usual, referencing that working directory path, and
+creating a post-update hook in Gerrit's repository. You'll need to set
+appropriate permissions on the hook directory for the repository so that the
+user running ikiwiki can compile and install the post-update hook. Also note
+that you must disable web editing by disabling the editpage plugin, and you
+must not enable any other plugin that commits to the repository, since ikiwiki
+will not have permission to push to the repository. (Allowing web edits to
+have such permission would bypass Gerrit's code review, defeating the purpose.)
+
+Gerrit does not run per-repository hooks, such as the post-update hook ikiwiki
+installs to update the wiki after pushes. However, Gerrit has site-wide hooks,
+including a ref-updated hook that runs whenever a ref changes. You can use
+that hook to trigger ikiwiki's post-update hook. The following script,
+installed as Gerrit's ref-updated hook, will run the post-update hook on any
+repository that has a "gerrit-run-post-update-hook" file in it:
+
+ #!/bin/sh
+ if [ -e "$GIT_DIR/gerrit-run-post-update-hook" ] ; then
+ exec "$GIT_DIR/hooks/post-update"
+ fi
+
+Then just create gerrit-run-post-update-hook in the wiki repository, run
+ikiwiki --setup on the setup file, add your wiki to /etc/ikiwiki/wikilist, and
+start reviewing and committing wiki changes via Gerrit.