web commit by http://madduck.myopenid.com/: rewrite the git setup instructions

1 files changed, 46 insertions, 10 deletions

diff --git a/doc/setup.mdwn b/doc/setup.mdwn
index 8e5653442..98ac90460 100644
--- a/doc/setup.mdwn
+++ b/doc/setup.mdwn
@@ -119,16 +119,52 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
    
    [[toggle id=git text="Git"]]
    [[toggleable id=git text="""
-   			REPOSITORY=~/wikirepo
-   			mkdir $REPOSITORY
-   			cd $REPOSITORY
-   			git init-db
-   			cp -a $SRCDIR/* .
-   			git add .
-   			git commit -m "initial import" -a
-			mv $SRCDIR/.ikiwiki .
-   			rm -rf $SRCDIR
-   			git clone -l -s $REPOSITORY $SRCDIR
+	For Git, you need two repositories, of which one should be bare
+	(meaning that it does not have a working tree checked out). We call
+	the bare repository the "repo" and the other the "srcdir" ($srcdir).
+	There are [other
+	ways](http://blog.madduck.net/vcs/2007.07.11_publishing-git-repositories)
+	to do the following, but this might be easiest:
+
+			REPOSITORY=./wiki.git
+			# SRCDIR is where ikiwiki compiles from. You thus need
+			# to set $srcdir in ikiwiki.setup appropriately. The
+			# -wc in the name suggests "working clone" because
+			# $SRCDIR holds a Git repository with a working tree.
+			SRCDIR=./wiki-wc
+			cd $SRCDIR
+			git init
+			echo "Initial index page" > index.mdwn
+			echo .ikiwiki > .gitignore
+			git add index.mdwn .gitignore
+			git commit -m'Initial commit'
+			git config receive.denyNonFastForwards true
+			git config core.bare true
+			mv .git $REPOSITORY
+			test -d .ikiwiki && mv .ikiwiki ..
+			cd ..
+			rm -r $SRCDIR
+			git clone -l -s $REPOSITORY $SRCDIR
+			test -d .ikiwiki && mv .ikiwiki $SRCDIR
+
+	It is **paramount** that you **never** push to the Git repository in
+	`$SRCDIR` ([this FAQ entry explains
+	why](http://git.or.cz/gitwiki/GitFaq#head-b6a3d85f677763313159eb39f7dbf4579d4ee28b)).
+	Instead, if you want to work on the wiki from a remote machine, clone
+	`$REPOSITORY`, using either the `git` transport (if available), or
+	`ssh`.
+
+	To automatically update the wiki when you push changes to
+	`$REPOSITORY`, `ikiwiki` can install a `post-update` hook. You need to
+	enable this hook in `ikiwiki.setup` and the path to use should be
+	`$REPOSITORY/hooks/post-update`.
+
+	Finally, then, setup `ikiwiki`:
+
+			ikiwiki --setup ikiwiki.setup
+
+	If you commit changes in `$SRCDIR`, make sure to `git push` them to
+	the `$REPOSITORY`.
    """]]
 
    [[toggle id=tla text="TLA"]]