doc/tips/laptop_wiki_with_git.mdwn

   1 Using ikiwiki with the [[rcs/git]] backend, some interesting things can be done
   2 with creating mirrors (or, really, branches) of a wiki. In this tip, I'll
   3 assume your wiki is located on a server, and you want to take a copy with
   4 you on your laptop.
   5
   6 With the configuration described here, you can commit local changes to the
   7 version on the laptop, perhaps while offline. You can browse and edit the
   8 wiki using a local web server. When you're ready, you can manually push the
   9 changes to the main wiki on the server.
  10
  11 First, set up the wiki on the server, if it isn't already. Nothing special
  12 needs to be done here, just follow the regular instructions in [[setup]]
  13 for setting up ikiwiki with git.
  14
  15 Next, `git clone` the source (`$REPOSITORY`, not `$SRCDIR`)
  16 from the server to the laptop.
  17
  18 Now, set up a web server on your laptop, if it doesn't already have one.
  19
  20 Now you need to write a setup file for ikiwiki on the laptop. Mostly this
  21 is standard, but a few special settings are needed:
  22
  23 * Configure a cgi wrapper as usual, but configure the git wrapper to
  24   be written to the `post-commit` hook of the git clone.
  25
  26 * By default, ikiwiki pulls and pushes from `origin`. This shouldn't be
  27   done on the laptop, because the origin may not be accessible (when the
  28   laptop is offline). Also, commits made on the laptop should stay there,
  29   until manually pushed, so that the laptop can serve as a staging area.
  30
  31   Make sure you have ikiwiki 2.11 or better installed, and set:
  32
  33         gitorigin_branch => "",
  34
  35 * You can optionally enable to the [[plugins/mirrorlist]] plugin,
  36   and configure it so that each page links to the corresponding page on the
  37   server.
  38
  39 Now just run `ikiwiki -setup wiki.setup -getctime` and you should be
  40 good to go. (You only need the slow `-getctime` option the first time you
  41 run setup.)
  42
  43 Use standard git commands to handle pulling from and pushing to the server.
  44
  45 Note: Currently, after pulling changes, you will need to manually update
  46 the wiki, with a command such as `ikiwiki -setup wiki.setup -refresh`. This
  47 is because git 1.5.4 doesn't have a hook that is run locally after pulling
  48 changes. Newer versions of git will have a `post-merge` hook that should
  49 work for this purpose.