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

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