migration document added

doc/1-migrate.mkd

@@ -1,3 +1,91 @@
 # migrating from gitosis to gitolite
 
+Migrating from gitosis to gitolite is pretty easy, because the basic design is
+the same.  The differences are:
 
+  * gitolite does not use a special repo for the configuration, pubkeys, etc.
+    You can choose to version that directory but it is not required that you
+    do so
+
+Here's how we migrated my work repos:
+
+1.  login as the `git` user on the server, and get a bash shell prompt
+
+2.  **disable gitosis** by renaming `/usr/bin/gitosis-serve` to something
+    else.  This will prevent users from pushing anything while you do the
+    backup, migration, etc.
+
+3.  For added safety, **delete** the post-update hook that gitosis-admin
+    installed
+
+        rm ~/repositories/gitosis-admin.git/hooks/post-update
+
+    or at least rename it to `.sample` like all the other hooks hanging
+    around, or edit it and comment out the line that calls `gitosis-run-hook
+    post-update`.
+
+    If you do not do this, an accidental push to the gitosis-admin repo will
+    mess up your `~/.ssh/authorized_keys` file
+
+4.  take a **backup** of the `~/repositories` directory
+
+5.  untar gitolite to some temporary directory and follow the instructions to
+    **install** it.  Some of the steps (like `mkdir ~/repositories`) will
+    fail, but this is expected.  Once this is done, cd to the `$GL_ADMINDIR`
+    (by default `~/.gitolite`)
+
+        cd ~/.gitolite
+
+6.  **convert** your gitosis config file:
+
+        src/conf-convert.pl < ~/.gitosis.conf > conf/gitolite.conf
+
+    be sure to check the file to make sure it converted correctly
+
+7.  **copy** the update hook to each of the existing repos
+
+        for i in ~/repositories/*.git
+        do
+            cp src/update-hook.pl $i/hooks/update
+        done
+
+8.  **copy** the keys from gitosis's keydir
+
+        cp ~/repositories/gitosis-admin.git/gitosis-export/keydir/* keydir
+
+9.  **Important: expand** any multi-key filess you may have.  See the "faq,
+    tips, etc" document in the doc directory for an explanation of what
+    multi-keys are, how gitosis does them and how gitolite does it
+    differently.
+
+    You can split the keys manually, or use the following code (just
+    copy-paste it into you xterm):
+
+        wc -l keydir/*.pub | grep -v total | grep -v -w 1 | while read a b
+        do
+            i=1
+            cat $b|while read l
+            do
+                echo "$l" > ${b%.pub}@$i.pub
+                (( i++ ))
+            done
+            v $b $b.done
+        done
+
+    This will split each multi-key file (say "sitaram.pub") into individual
+    files called "sitaram@1.pub", "sitaram@2.pub", etc., and rename the
+    original to "sitaram.pub.done" so gitolite won't pick it up.
+
+    At this point you can rename the split parts more appropriately, like
+    "sitaram@laptop.pub" and "sitaram@desktop.pub" or whatever.  *Please check
+    the files to make sure this worked properly*
+
+10. **edit** `~/.ssh/authorized_keys` and **carefully** remove all the lines
+    containing "gitosis-serve", as well as the marker line that says
+    "auto-generated by gitosis, DO NOT REMOVE", then save the file.  If the
+    file did not have any other keys and is now empty, don't worry -- save it
+    anyway because gitolite expects the file to be present (even if it is
+    empty).
+
+At this point you're ready to "compile" the configuration.  See the "admin"
+document for what to do, and how to check the outputs, etc.