gitolite/doc/migrate.mkd

F=migr migrating from gitosis to gitolite

HELP WANTED: these instructions have been revamped a bit recently [2011-07-18], so if something doesn't work let me know.

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

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

There's only one thing that might trip up people: the userid. Gitosis uses gitosis. Gitolite can use any userid you want; most of the documentation uses git, while DEB/RPM packages use gitolite.

Here are the steps on the server:

• (as 'gitosis' on the server) Rename ~/.ssh/authorized_keys to something else so that no one can accidentally push while you're doing this.

• (as 'gitosis' on the server) 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.

• (as 'gitosis' on the server) If you already use the update hook for some reason, rename it (on each individual repository that has it) to update.secondary. This is because gitolite uses the update hook for checking write access.

• (as 'root' on the server) copy all of ~/repositories to the gitolite hosting user's home directory. Something like

  cp -a /home/gitosis/repositories /home/git
  chown -R git.git /home/git/repositories
  

• (as 'root' and/or 'git' on the server) Follow instructions to install gitolite; see the [install document][install]. 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.

Now, log off the server and get back to the client. All subsequent instructions are to be read as "on gitolite admin's workstation".

• clone the new gitolite-admin repo to your workstation. (You already have a clone of the gitosis-admin repo so now you have both).

• 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. (The gl-conf-convert program is a standalone program that you can bring over from any gitolite clone; you don't have to install all of gitolite on your workstation to use this):

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

  Be sure to check the file to make sure it converted correctly. Then remove the entry for the 'gitosis-admin' repo. You do not need it here and it may cause confusion.

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

  cp $GSAC/keydir/* $GLAC/keydir
  

  If your gitosis-admin key was you@machine.pub, and you supplied the same one to gitolite's gl-setup program as you.pub when you installed gitolite, then you should remove you@machine.pub from the new keydir now. Otherwise you will have 2 pubkey files (you.pub and you@machine.pub) which are identical, which is not a good idea.

  Similarly, you should replace all occurrences of you@machine.pub with you in the conf/gitolite.conf file.

• 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][oldmultikeys].

  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][multikey] will tell you more about these nuances. If you can understand it.

• IMPORTANT: expand any multi-key files you may have. [Here][multikey]'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

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