X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/491847ed5311123b3ce58c636451c56a2a0f191b..0702e3aabe37736c6c53f15bad7ff7d144bd867e:/doc/rcs/git.mdwn diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn index 504ded17a..539c1e8b1 100644 --- a/doc/rcs/git.mdwn +++ b/doc/rcs/git.mdwn @@ -12,19 +12,149 @@ commits edited pages, and uses the Git history to generate the ## git repository setup -When using Git, you probably want to set up two repositories, of which -one should be bare (meaning that it does not have a working tree -checked out), and the other one with a working tree will be used as -ikiwiki's srcdir for compiling the wiki. [[ikiwiki-makerepo]] can automate -setting this up. Using a pair 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. +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): + +![Git repository relationships](http://people.debian.org/~srivasta/ikiwiki_git.png) + +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 +[[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 +trigger an update of this repository, and then an ikiwiki refresh +updates the published wiki itself. + +The other (optional) leaf node repositories 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 +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-b6a3d85f677763313159eb39f7dbf4579d4ee28b)). -Instead, if you want to work on the wiki from a remote machine, clone -the bare repository, using either the `git` transport (if available), or -`ssh`. +([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. + +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. Make both the post-update hook and ikiwiki.cgi be setgid +to the group, as well as suid to the user who admins the wiki. The +`wrappergroup` [[setup_file_option|usage]] can be used to make the wrappers +be setgid to the right group. Then the srcdir, including its 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.) + +## 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.