git repo move

[ikiwiki.git] / doc / setup.mdwn

diff --git a/doc/setup.mdwn b/doc/setup.mdwn
index 3c7230f20883b970c42bdc4e406951973593e205..a28e7918f8dcacf7126dc474e87f137253e9ddbd 100644 (file)
--- a/doc/setup.mdwn
+++ b/doc/setup.mdwn
@@ -119,16 +119,55 @@ 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".
+       There are [other
+       ways](http://blog.madduck.net/vcs/2007.07.11_publishing-git-repositories)
+       to do the following, but this might be easiest:
+
+                       REPO=./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'
+                       # Stop git performing fast forwards -- this is to avoid
+                       # overwriting the remote ref and losing other peoples'
+                       # commits from there.
+                       git config receive.denyNonFastForwards true
+                       git config core.bare true
+                       mv .git $REPO
+                       test -d .ikiwiki && mv .ikiwiki ..
+                       cd ..
+                       rm -r $SRCDIR
+                       git clone -l -s $REPO $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
+       `$REPO`, using either the `git` transport (if available), or
+       `ssh`.
+
+       To automatically update the wiki when you push changes to
+       `$REPO`, `ikiwiki` can install a `post-update` hook. You need to
+       enable this hook in `ikiwiki.setup` and the path to use should be
+       `$REPO/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 `$REPO`.
    """]]
 
    [[toggle id=tla text="TLA"]]
@@ -154,6 +193,32 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
                        hg commit -m "initial import"
    """]]
 
+   [[toggle id=monotone text="Monotone"]]
+   [[toggleable id=monotone text="""
+                       # These instructions are standard instructions to import a directory into monotone
+                       # and set it up so that you don't need any passwords to use it
+                       REPOSITORY=~/.ikiwiki/mtn.db
+                       BRANCH=com.company.wikiname
+                       # remember the password you use in the next step and
+                       # substitute it for 'wikiKeyPass' in the get_passphrase() hook below
+                       # note the you should never generate two monotone keys with the same name
+                       mtn genkey web@machine.company.com
+                       mtn db init --db=$REPOSITORY
+                       mv $SRCDIR $SRCDIR-old
+                       cd $SRCDIR-old
+                       echo ".ikiwiki" > $SRCDIR-old/.mtn-ignore
+                       mtn --db=$REPOSITORY --branch=$BRANCH import . -m "initial import"
+                       cd ..
+                       mtn --db=$REPOSITORY --branch=$BRANCH checkout $SRCDIR
+                       mv $SRCDIR-old/.ikiwiki $SRCDIR
+                       cat << EOF > $SRCDIR/_MTN/monotonerc
+                       function get_passphrase (branchname)
+                           return "wikiKeyPass"
+                       end
+                       EOF
+                       rm -r $SRCDIR-old
+   """]]
+
 9. Configure ikiwiki to use revision control.
 
    Once your wiki is checked in to the revision control system,
@@ -170,4 +235,5 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
    And in the web interface, RecentChanges should work, and files changed
    by web users will also be committed using revision control.
 
-10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]].
+10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]]. And check out
+    [[tips]] to find out how to get more out of ikiwiki.