gitolite/doc/migrate.mkd

# 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][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.

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.

    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.

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

  * 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