1 This is a simple set of files for bootstrapping a git-backed instance
4 I put this together to make it easier for people who are already
5 comfortable with git to start using ikiwiki with git. If you're not
6 already comfortable with git, then you're probably much better off
7 learning to use ikiwiki from its standard instructions:
9 http://ikiwiki.info/setup/
13 Here are some of the key features of what I've got set up, (and that
14 are different than following the standard instruction for integrating
19 The ikiwiki configuration file, the templates, and source
20 files are all together in one repository.
24 The default ikiwiki setup instructions would pull in a bunch
25 of "stock" wiki pages and some underlay content. This setup
26 saves you the hassle of having to prune any of that out.
28 3. Pre-configured for git
30 Most of the git-specific settings you need are already set up
31 in ikiwiki.setup. One that is not is that the generated
32 wrapper is placed into ikiwiki-post-update rather than going
33 directly into git's post-update---so you will have to manually
34 edit post-update to call ikiwiki-post-update, (perhaps in
35 addition to anything else you want to do in post-update). See
40 To start, choose where the bare git repository will exist on your web
41 server and where you'd like the HTML results to be published to. Edit
42 ikiwiki.setup and fill these in for gitrepo and destdir. Commit these
43 changes, (git commit -a).
45 Then use the following commands on the server to set up the bare git
52 Then, push the contents of this repository out to $gitrepo. To do
53 this, you'll probably want to edit .git/config to point origin at the
54 repository you just setup on your web server at $gitrepo. Then do:
56 git push origin master:refs/heads/master
58 Then, back on the server, (and still with $gitrepo as the current
59 working directory) do:
61 git clone $gitrepo ikiwiki-checkout
63 ikiwiki --setup ikiwiki.setup
65 [And yes, if you're paying attention there, you just cloned from the
66 bare repository into a directory that is also inside that same
67 repository. I found this a neat place to hide away the
68 clone-with-working-tree that ikiwiki needs to edit but that you
69 shouldn't touch. If you think this is too creepy, you could put it
70 anywhere else, and configure ikiwiki.setup to point to it there.]
72 And finally, edit $gitrepo/hooks/post-update to call the new
73 $gitrepo/hooks/ikiwiki-post-update program and also don't forget to
74 actually enable the hook with:
76 chmod a+x $gitrepo/hooks/post-update
78 Now, you're finally ready to go. You should be able to just start
79 adding content under the src directory. You can give files a .mdwn
80 extension to use markdown syntax to turn the contents into HTML. Here
81 are some hints on doing that:
83 http://ikiwiki.info/helponformatting/
85 To preview things locally, you can run "ikiwiki --setup
86 ikiwiki.setup", (and ensure the destdir path exists on the local
87 machine). When you're ready to publish to your server, it should be as
92 Here is a useful, (self explanatory), command-line options for
93 debugging ikiwiki problems:
95 ikiwiki --verbose --setup ikiwiki.setup
97 ikiwiki --verbose --rebuild --setup ikiwiki.setup
99 I've had occasions where the hook-based update fails for one reason or
100 another, (for example, once when I moved the location of $gitrepo, but
101 the compiled hook still had the old location). The basic recipe for
102 unwedging things in this case was as simple as running the following
105 cd $gitrepo/ikiwiki-checkout
107 ikiwiki --setup ikiwiki.setup
109 I hope that's all helpful, and please feel free to let me know if you
110 have any problems or questions,
112 Carl Worth <cworth@cworth.org>