X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/0702e3aabe37736c6c53f15bad7ff7d144bd867e..2da6600def155d2330c61ab058c7e91f19fb6c6d:/doc/rcs/git.mdwn?ds=sidebyside diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn index 539c1e8b1..c82adbd04 100644 --- a/doc/rcs/git.mdwn +++ b/doc/rcs/git.mdwn @@ -1,101 +1,51 @@ -[[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 -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): +[[!img wiki_edit_flow.svg size=490x align=right]] -![Git repository relationships](http://people.debian.org/~srivasta/ikiwiki_git.png) +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 from, 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-commit` hook for the bare root repository is used to +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. 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 +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. -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. +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 @@ -107,54 +57,97 @@ 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. +## 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.