This is a simple set of files for bootstrapping a git-backed instance
of ikiwiki.

I put this together to make it easier for people who are already
comfortable with git to start using ikiwiki with git. If you're not
already comfortable with git, then you're probably much better off
learning to use ikiwiki from its standard instructions:

	http://ikiwiki.info/setup/

Features
========
Here are some of the key features of what I've got set up, (and that
are different than following the standard instruction for integrating
ikiwiki with git).

1. Self-contained.

	The ikiwiki configuration file, the templates, and source
	files are all together in one repository.

2. Minimal

	The default ikiwiki setup instructions would pull in a bunch
	of "stock" wiki pages and some underlay content. This setup
	saves you the hassle of having to prune any of that out.

3. Pre-configured for git

	Most of the git-specific settings you need are already set up
	in ikiwiki.setup. One that is not is that the generated
	wrapper is placed into ikiwiki-post-update rather than going
	directly into git's post-update---so you will have to manually
	edit post-update to call ikiwiki-post-update, (perhaps in
	addition to anything else you want to do in post-update). See
	below.

Usage
=====
To start, choose where the bare git repository will exist on your web
server and where you'd like the HTML results to be published to. Edit
ikiwiki.setup and fill these in for gitrepo and destdir. Commit these
changes, (git commit -a).

Then use the following commands on the server to set up the bare git
repository there:

	mkdir -p $gitrepo
	cd $gitrepo
	GIT_DIR=. git init-db

Then, push the contents of this repository out to $gitrepo. To do
this, you'll probably want to edit .git/config to point origin at the
repository you just setup on your web server at $gitrepo. Then do:

	git push origin master:refs/heads/master

Then, back on the server, (and still with $gitrepo as the current
working directory) do:

	git clone $gitrepo ikiwiki-checkout
	cd ikiwiki-checkout
	ikiwiki --setup ikiwiki.setup

[And yes, if you're paying attention there, you just cloned from the
bare repository into a directory that is also inside that same
repository. I found this a neat place to hide away the
clone-with-working-tree that ikiwiki needs to edit but that you
shouldn't touch. If you think this is too creepy, you could put it
anywhere else, and configure ikiwiki.setup to point to it there.]

And finally, edit $gitrepo/hooks/post-update to call the new
$gitrepo/hooks/ikiwiki-post-update program and also don't forget to
actually enable the hook with:

	chmod a+x $gitrepo/hooks/post-update

Now, you're finally ready to go. You should be able to just start
adding content under the src directory. You can give files a .mdwn
extension to use markdown syntax to turn the contents into HTML. Here
are some hints on doing that:

	http://ikiwiki.info/helponformatting/

To preview things locally, you can run "ikiwiki --setup
ikiwiki.setup", (and ensure the destdir path exists on the local
machine). When you're ready to publish to your server, it should be as
simple as "git push".

Problems
========
Here is a useful, (self explanatory), command-line options for
debugging ikiwiki problems:

	ikiwiki --verbose --setup ikiwiki.setup

	ikiwiki --verbose --rebuild --setup ikiwiki.setup

I've had occasions where the hook-based update fails for one reason or
another, (for example, once when I moved the location of $gitrepo, but
the compiled hook still had the old location). The basic recipe for
unwedging things in this case was as simple as running the following
on the server:

	cd $gitrepo/ikiwiki-checkout
	git pull
	ikiwiki --setup ikiwiki.setup

I hope that's all helpful, and please feel free to let me know if you
have any problems or questions,

Carl Worth <cworth@cworth.org>