doc/tips/laptop_wiki_with_git.mdwn

   1 [[!toc]]
   2 [[!meta date="2007-10-22 01:45:55 +0000"]]
   3
   4 Using ikiwiki with the [[rcs/git]] backend, some interesting things can be done
   5 with creating mirrors (or, really, branches) of a wiki. In this tip, I'll
   6 assume your wiki is located on a server, and you want to take a copy with
   7 you on your laptop.
   8
   9 With the configuration described here, you can commit local changes to the
  10 version on the laptop, perhaps while offline. You can browse and edit the
  11 wiki using a local web server. When you're ready, you can manually push the
  12 changes to the main wiki on the server.
  13
  14 ## simple clone approach
  15
  16 First, set up the wiki on the server, if it isn't already. Nothing special
  17 needs to be done here, just follow the regular instructions in [[setup]]
  18 for setting up ikiwiki with git.
  19
  20 Next, `git clone` the source (`$REPOSITORY`, not `$SRCDIR`)
  21 from the server to the laptop.
  22
  23 Now you need to write a setup file for ikiwiki on the laptop. Mostly this
  24 is standard, but a few special settings are needed:
  25
  26 * Configure a cgi wrapper as usual, but configure the git wrapper to
  27   be written to the `post-commit` hook of the git clone, rather than the
  28   usual `post-update` hook.
  29
  30     git_wrapper: /home/user/foo-wiki/.git/hooks/post-commit
  31
  32 * By default, ikiwiki pulls and pushes from `origin`. This shouldn't be
  33   done on the laptop, because the origin may not be accessible (when the
  34   laptop is offline). Also, commits made on the laptop should stay there,
  35   until manually pushed, so that the laptop can serve as a staging area.
  36
  37   Make sure you have ikiwiki 2.11 or better installed, and set:
  38
  39         gitorigin_branch:
  40
  41 * You can optionally enable to the [[plugins/mirrorlist]] plugin,
  42   and configure it so that each page links to the corresponding page on the
  43   server.
  44
  45 Now just run `ikiwiki --setup wiki.setup --getctime` and you should be
  46 good to go. (You only need the slow `-getctime` option the first time you
  47 run setup.) If you have taken your `wiki.setup` file from an existing
  48 wiki, you may need to change certain parameters to adapt to the paths
  49 on your laptop, a few examples:
  50
  51     srcdir: /home/user/foo-wiki
  52     destdir: /home/user/public_html
  53     # optional
  54     url: http://foo-wiki.localhost
  55     libdir: /home/user/foo-wiki/.ikiwiki
  56     ENV:
  57         TMPDIR: /home/user/tmp
  58     cookiejar:
  59         file:
  60
  61 Now, set up a [[web_server|dot_cgi]] on your laptop, if it doesn't
  62 already have one. You can also skip that step if you want only to
  63 render the wiki and not allow edition, in which case you'll want the
  64 following:
  65
  66     # disable CGI, unless you want to get really funky
  67     cgiurl:
  68     cgi_wrapper:
  69
  70 You can also direct people to the main server for web edition there.
  71
  72 Use standard git commands to handle pulling from and pushing to the server.
  73
  74 Note that if changes are pulled from the server, you will need to manually
  75 update the wiki, with a command such as `ikiwiki --setup wiki.setup --refresh`.
  76 If you'd like it to automatically update when changes are merged in, you
  77 can simply make a symlink `post-merge` hook pointing at the `post-update`
  78 hook ikiwiki created.
  79
  80 ## bare mirror approach
  81
  82 As above, set up a normal ikiwiki on the server, with the usual bare repository.
  83
  84 Next, `git clone --mirror server:/path/to/bare/repository`
  85
  86 This will be used as the $REPOSITORY on the laptop.  Then you can follow
  87 the instructions in [[setup by hand|/setup/byhand]] as per a normal ikiwiki
  88 installation. This means that you can clone from the local bare repository
  89 as many times as you want (thus being able to have a repository which is
  90 used by the ikiwiki CGI, and another which you can use for updating via
  91 git).
  92
  93 Use standard git commands, run in the laptop's bare git repository
  94 to handle pulling from and pushing to the server.