Simplify and document the git repository setup

There's now a new gitrepo variable whose value is used for setting
srcdir, templatedir, and underlaydir.

diff --git a/ikiwiki.setup b/ikiwiki.setup
index 42404089678d7ad7faa1fa313582fd9bf3d5bcba..1159b521cf9c075201a553284725f545adb9cc6a 100644 (file)
--- a/ikiwiki.setup
+++ b/ikiwiki.setup
@@ -5,26 +5,55 @@
 #
 # Remember to re-run ikiwiki --setup any time you edit this file.
 
+# The gitrepo parameter should point to a bare git repository which is
+# cloned from and pushed to by anyone using git to maintain the wiki.
+#
+# The checkout parameter should point to a clone of that repository,
+# but this clone is owned by ikiwiki so its working-copy content
+# should never be edited manually, nor should anybody clone from or
+# push to this repository. To make this quite clear, I suggest hiding
+# the checkout inside the repository as show below.
+#
+# To set this up, just do:
+#
+#      mkdir -p $gitrepo
+#      cd $gitrepo
+#      GIT_DIR=. git init-db
+#      git clone $gitrepo ikiwiki-checkout
+#
+# And then push into $gitrepo this ikiwiki.setup file, a templates/
+# directory, and a src/ directory with your wiki content.
+#
+# Also, see the destdir and url parameters below which must also be
+# configured before things will work at all.
+
+my gitrepo = '/path/to/bare/git/repo';
+my checkout = "$gitrepo/ikiwiki-checkout";
+
 use IkiWiki::Setup::Standard {
-       wikiname => "MyWiki",
-       #adminuser => ["yourname", ],
-       adminemail => 'me@example.org',
 
-       # Be sure to customise these..
-       srcdir => "/path/to/source",
+        # These (along with gitrepo above) must be configured
+        # correctly before anything will work
        destdir => "/var/www/wiki",
-
        url => "http://example.org/wiki",
        cgiurl => "http://example.org/ikiwiki.cgi",
-       #templatedir => "/usr/share/ikiwiki/templates",
-       #underlaydir => "/usr/share/ikiwiki/basewiki",
+
+       # And you'll likely want to customise these as well
+       wikiname => "MyWiki",
+       #adminuser => ["yourname", ],
+       adminemail => 'me@example.org',
+
+       # Everything else can be customised on an as-needed basis
+       srcdir => "$checkout/src";
+       templatedir => "$checkout/templates",
+       underlaydir => "$checkout/underlay";
 
        # Git stuff.
-       #rcs => "git",
+       rcs => "git",
        #historyurl => "http://git.example.org/gitweb.cgi?p=wiki.git;a=history;f=[[file]]",
        #diffurl => "http://git.example.org/gitweb.cgi?p=wiki.git;a=blobdiff;h=[[sha1_to]];hp=[[sha1_from]];hb=[[sha1_parent]];f=[[file]]",
-       #gitorigin_branch => "origin",
-       #gitmaster_branch => "master",
+       gitorigin_branch => "origin",
+       gitmaster_branch => "master",
 
        wrappers => [
                #{
@@ -33,16 +62,15 @@ use IkiWiki::Setup::Standard {
                #       wrapper => "/var/www/wiki/ikiwiki.cgi",
                #       wrappermode => "06755",
                #},
-               #{
-               #       # The git post-update wrapper.
-               #       # Note that this will overwrite any existing
-               #       # post-update hook script, which may not be
-               #       # what you want.
-               #       wrapper => "/git/wiki.git/hooks/post-update",
-               #       wrappermode => "04755",
-               #       # Enable mail notifications of commits.
-               #       notify => 1,
-               #},
+               {
+                       # Instead of overwriting git's post-update script
+                       # we generate a new program that can be called by
+                       # post-update as desired.
+                       wrapper => "$gitrepo/hooks/post-update",
+                       wrappermode => "04755",
+                       # Enable mail notifications of commits.
+                       #notify => 1,
+               },
        ],
 
        # Generate rss feeds for blogs?