HOWTO: ikiwiki + git

Ikiwiki is a nice wiki and a nice idea. Git (with its friend Cogito) is a nice source code management system. However, after spending many, many hours trying to figure out how to get them to work right together, it took Jamey coaching me to finally get the combination going. Since this seems to be due to the combination of a bizarre model with a strong insufficiency of documentation, I thought I should leave a record here…

I've installed ikiwiki and gitweb successfully on my Debian box. I then create a new group for my wiki. I may also want a new user; if so, I create it being careful that it has both a shell (needed for ikiwiki) and a GECOS field (needed for git).
I then follow the normal instructions for setting up an ikiwiki without source code management. I end up with an ikiwiki.setup file that contains a bunch of commented-out git stuff.
Note that the permissions for the previous step are not trivial to get right, and they matter. You'll need a user or group that is able to write, create files, etc in $srcdir and its environs, and in $destdir and its environs.

My setup makes a ikiwiki master directory we'll call /ikiwiki, and a subdirectory per wiki, e.g. /ikiwiki/mywiki. In /ikiwiki/mywiki is the ikiwiki setup file mywiki.setup and the $srcdir mywiki-master. The $srcdir is in group mywiki and is mode 02775. Sitting in $srcdir is the index file index.mdwn with group mywiki and mode 0664. I also create directory .ikiwiki with group mywiki and mode 02775: this avoids permission problems later.

If you are using a vhost-style setup for your wiki, you can use suexec to get around some of the permission problems; no need to go there now, though.

Once I've got index.mdwn to a reasonable initial state, I run
```
ikiwiki --setup mywiki.setup
```
from /ikiwiki/mywiki and/or set up /etc/ikiwiki/wikilist and run ikiwiki-mass-rebuild (which may be Debian-specific, I guess). I'm set up to build into the $destdir /var/www/mywiki. At this point I'll check that my browser will let me hit the site, and fix any problems I find.
I run most of my wikis with just BasicAuth instead of ikiwiki's auth (requires a recent ikiwiki version). At this point I stick an appropriate .htaccess in $destdir, pointing at the password file /ikiwiki/mywiki/htpasswd. Then I check that this is working properly.
Finally, I am ready to put this all under git control. The important point here is that this requires not one but two git repositories! As near as Jamey and I can figure, this is because the git interface wants to act like the svn interface: the "origin" repository for the site is "remote" from the "master" repository. The ikiwiki.cgi script and the git post-update hook will be set up to make, push and pull modifications of files in mywiki-master as needed. If the primary git repo is in mywiki-master/.git this will break badly!
While sitting in mywiki-master, I move .ikiwiki aside somewhere for a moment where it won't get in the way. I check to make sure that my GIT_AUTHOR_NAME and GIT_COMMITTER_NAME environment variables are set to something sensible. I then run git-init-db --shared. The result is a lovely .git directory which is the work product from this step. I then
```
mv .git ../mywiki.git
cd ..
mv mywiki-master mywiki-master.bak
git-clone -l -s mywiki.git mywiki-master
```
Finally, I move .ikiwiki back to mywiki-master.

This is the right structure. The ikiwiki.cgi script will make changes to mywiki-master, git-commit them, git-push them back to mywiki.git then propagate them back to $destdir.

I need to make sure permissions are set properly. For dir = mywiki-master and mywiki.git I run
```
chgrp -R mywiki $dir
find $dir -perm -0400 -print0 |
  xargs -0 chmod g+w
find $dir -type d -print0 |
  xargs -0 chmod g+s
```
Then I poke around to see where it all went horribly wrong.
I symlink mywiki.git to the place where git repos live on my system, /var/cache/git. This lets gitweb find the original copy. This is also where people will normally clone from for remote access to the repository—which is half the point, after all.
Now I edit mywiki.setup. I uncomment the git stuff, and then edit it appropriately. The only tricky part is that the git post-update wrapper script thingy should point at /ikiwiki/mywiki/mywiki.git/hooks/update-db and have mode 02775. When everything looks good, I rerun
```
ikiwiki --setup mywiki.setup
```
to propagate the changes.

This will allow folks pushing to origin to do the right thing; ikiwiki will install a post-update hook that will pull $srcdir (mywiki-master) from origin (mywiki.git) and then propagate the result into $destdir (/var/www/mywiki).

And there you have it! As easy painful as falling off a log.

Obviously, I should script this. It looks like it's time to resurrect the wiki farm stuff. These notes should help me do so. (B)