]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/rcs/git.mdwn
comment
[git.ikiwiki.info.git] / doc / rcs / git.mdwn
index cefa649ff7c52533d20c5888046bf4191af141b4..fa7a037baea7288c51a1a23d3ca6fdab5981d6c8 100644 (file)
-[[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,68 +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
-
-### Ikiwiki working directory
-
-* Configure a cgi wrapper as usual, but configure the git wrapper to
-  be written to the post-commit hook of the bare root repository. Set
-  in the configuration:
-
-        gitorigin_branch=> "origin",
-        ## git post-commit wrapper
-        wrapper => "/path/to/bare/repo/.git/hooks/post-commit",
-
-
-
-### Working clones (Clone 1 .. N in the image)
-
-These are repositories 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.