gitolite/doc/migrate.mkd

migrating from gitosis to gitolite

[TODO: make the migration tool fix up gitweb and daemon control also...]

Migrating from gitosis to gitolite is pretty easy, because the basic design is the same.

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. 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).

4. 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

5. If you already use the update hook for some reason, rename it (on each individual repository) to update.secondary. This is because gitolite uses the update hook for checking write access.

6. take a backup of the ~/repositories directory

Now, log off the server and get back to the client:

1. follow instructions to install gitolite; see the install document. Make sure that you don't change the default path for $REPO_BASE if you edit the config file!

   This will give you a gitolite config that has the required entries for the "gitolite-admin" repo.

2. convert your gitosis config file and append it to your gitolite config file. Substitute the path for your gitosis-admin clone in $GSAC below, and similarly the path for your gitolite-admin clone in $GLAC

   src/gl-conf-convert < $GSAC/gitosis.conf >> $GLAC/gitolite.conf
   

   Be sure to check the file to make sure it converted correctly

3. copy the keys from gitosis's keydir (same meanings for GSAC and GLAC)

   cp $GSAC/keydir/* $GLAC/keydir
   

4. IMPORTANT: if you have any users with names like user@foo, where the part after the @ does not have a . in it (i.e., does not look like an email address), you need to change them, because gitolite uses that syntax for enabling multi keys.

   You have two choices in how to fix this. You can change the gitolite config so that all mention of user@foo is changed to just user.

   Or you can change each occurrence of user@foo to, say, user_foo and change the pubkey filename in keydir/ also the same way (user_foo.pub).

   Just to repeat, you do NOT need to do this if the username was like user@foo.bar, i.e., the part after the @ had a . in it, because then it looks like an email address.

   This will tell you more about these nuances.

5. IMPORTANT: expand any multi-key files you may have. Here's 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 your xterm after "cd"-ing to your gitolite-admin repo clone):

   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
       mv $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

6. Check all your changes to your gitolite-admin clone, commit, and push