-[[meta title="Git"]]
+[[!meta title="Git"]]
[Git][git] is a distributed revison control system originally developed for
the Linux kernel. Ikiwiki supports storing a wiki in git.
[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
-When using Git, you probably want to set up three repositories:
+[[!img wiki_edit_flow.svg size=490x align=right]]
-* One of these repositories should be a bare repository (meaning that it does not have a working tree checked out), which the other two 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 would change directory to the second repository (the working directory for ikiwiki), do a _git pull_, and refresh ikiwiki to regenerate the wiki with any new content.
-* The second repository 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]]'smanual page.
-* The third (and fourth, fifth, sixth -- however many pleases you) repository is a clone of the bare master repository above -- and this has 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. 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.
+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.
-[[ikiwiki-makerepo]] can automate setting this up. Using three or more 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.
+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.
-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 other (optional) clones are meant for you to work
+on, and commit to, changes should then be pushed to the bare root
+repository.
-The ikiwiki `post-commit` hook should be put in the bare repository.
+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.
## git repository with multiple committers
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.
+should be pushed 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, 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.)
+
+## git repository with untrusted committers
+
+By default, anyone who can commit to the git repository can modify any file
+on the wiki however they like. A `pre-receive` hook can be set up to limit
+incoming commits from untrusted users. Then the same limits that are placed
+on edits via the web will be in effect for commits to git for the users.
+They will not be allowed to edit locked pages, they will only be able to
+delete pages that the [[plugins/remove]] configuration allows them to
+remove, and they will only be allowed to add non-page attachments that the
+[[plugins/attachment]] configuration allows.
+
+To enable this, you need to set up the git repository to have multiple
+committers. Trusted committers, including the user that ikiwiki runs as,
+will not have their commits checked by the `pre-receive` hook. Untrusted
+committers will have their commits checked. The configuration settings to
+enable are `git_test_receive_wrapper`, which enables generation of a
+`pre-receive` hook, and `untrusted_committers`, which is a list of
+usernames of the untrusted committers.
+
+Note that when the `pre-receive` hook is checking incoming changes, it
+ignores the git authorship information, and uses the username of the unix
+user who made the commit. Then tests including the `locked_pages`
+[[ikiwiki/PageSpec]]
+are checked to see if that user can edit the pages in the commit.
+
+You can even set up an [[anonymous_user|tips/untrusted_git_push]], to allow
+anyone to push changes in via git rather than using the web interface.
+
+## Optionally using a local wiki to preview changes
+
+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
+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
+ 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 -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**: 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`. 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.