diff --git a/doc/migrate.mkd b/doc/migrate.mkd index 475adc6..52856f6 100644 --- a/doc/migrate.mkd +++ b/doc/migrate.mkd @@ -1,27 +1,25 @@ # 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 pretty easy, because the basic design is +Migrating from gitosis to gitolite is fairly easy, because the basic design is the same. -Here's how we migrated my work repos: +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`. -1. login as the `git` user on the server, and get a bash shell prompt +Here are the steps on the server: -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. + * (as 'gitosis' on the server) **Rename** `~/.ssh/authorized_keys` to + something else so that no one can accidentally push while you're doing + this. -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 + * (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 @@ -29,37 +27,57 @@ Here's how we migrated my work repos: 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 + * (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. -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. + * (as 'root' on the server) copy all of `~/repositories` to the gitolite + hosting user's home directory. Something like -6. take a **backup** of the `~/repositories` directory + cp -a /home/gitosis/repositories /home/git + chown -R git.git /home/git/repositories -Now, log off the server and get back to the client: - -1. follow instructions to install gitolite; see the [install document][inst]. - Make sure that you **don't** change the default path for `$REPO_BASE` if - you edit the config file! + * (as 'root' and/or 'git' on the server) Follow instructions to install + gitolite; see the [install document][inst]. 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 +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 gito**lite**-admin clone in `$GLAC` + and similarly the path for your gito**lite**-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): - src/gl-conf-convert < $GSAC/gitosis.conf >> $GLAC/gitolite.conf + ./gl-conf-convert < $GSAC/gitosis.conf >> $GLAC/conf/gitolite.conf - Be sure to check the file to make sure it converted correctly + 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. -3. **copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC) + * **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 + 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. @@ -76,7 +94,7 @@ Now, log off the server and get back to the client: [This][mk] will tell you more about these nuances. -5. **IMPORTANT: expand any multi-key files you may have**. [Here][mk]'s an + * **IMPORTANT: expand any multi-key files you may have**. [Here][mk]'s an explanation of what multi-keys are, how gitosis does them and how gitolite does it differently. @@ -103,7 +121,7 @@ Now, log off the server and get back to the client: "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 + * Check all your changes to your gitolite-admin clone, commit, and push [mk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#multikeys [inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html