X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/e46e5c6564cf76ab7be1e0b669d5e666f04f7802..575af4266797ed0be671630b62c5324d79c863ff:/doc/rcs/git.mdwn diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn index e71d47350..fa7a037ba 100644 --- a/doc/rcs/git.mdwn +++ b/doc/rcs/git.mdwn @@ -5,34 +5,34 @@ the Linux kernel. Ikiwiki supports storing a wiki in git. [git]: http://git.or.cz/ -[[!img wiki_edit_flow.svg size=490x align=right]] - 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 srcdir +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. -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 @@ -87,7 +87,7 @@ anyone to push changes in via git rather than using the web interface. ## 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 @@ -108,13 +108,46 @@ is the normal behaviour of ikiwiki, set the configuration of the local wiki: 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. +--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.