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][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
    file.  Substitute the path for your gitosis-admin clone in `$GSAC` below,
    and similarly the path for your gito**lite**-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][mk] will tell you more about these nuances.

5.  **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.

    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

[mk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#multikeys
[inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html