X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README;h=8ec1f7cf2e422bcdcd3f06f8eba5a365f53ba14c;hb=HEAD;hp=c2589e09e3a4de914304b96c5105ef4d5455681c;hpb=b188add49367232448e5349691fd1447eb0ded77;p=ikiwiki-bootstrap diff --git a/README b/README index c2589e0..8ec1f7c 100644 --- a/README +++ b/README @@ -1,14 +1,18 @@ This is a simple set of files for bootstrapping a git-backed instance of ikiwiki. -I put this together to make it easier to get started with ikiwiki than -following the standad instructions: +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 setup: +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. @@ -23,26 +27,86 @@ Here are some of the key features of what I've got setup: 3. Pre-configured for git - Most of the git-specific settings you need are already setup - in ikiwiki.setup. + 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 +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. +ikiwiki.setup and fill these in for gitrepo and destdir. Commit these +changes, (git commit -a). -Next, follow these steps to setup gitrepo along with a nested checkout -inside of it that ikiwiki will use: +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: -Finally, push this repository out to $gitrepo, then start adding -content in files under src. + cd $gitrepo/ikiwiki-checkout + git pull + ikiwiki --setup ikiwiki.setup -Let me know if you have any problems or questions, +I hope that's all helpful, and please feel free to let me know if you +have any problems or questions, Carl Worth