gitolite/doc/g2migr-example.mkd

# migration example

This shows what a typical migration would look like, using a test setup.

[[TOC]]

## existing setup

The existing gitolite is the latest in the "g2" (v2.x) branch.

First, the rc file has the following lines different from the default:

    -$GL_WILDREPOS = 0;
    +$GL_WILDREPOS = 1;

    -$GL_GITCONFIG_KEYS = "";
    +$GL_GITCONFIG_KEYS = ".*";

Next, the conf/gitolite.conf file in `~/.gitolite`:

    repo    gitolite-admin
            RW+             =   tester u1

    repo    testing
            RW+     =   @all

    repo foo
            RW+             =   u1 u2
            RW+ NAME/       =   u1
            RW+ NAME/u2     =   u2

    repo bar
            RW  =   u2

    repo baz/..*
            C   =   u3 u4
            RW+         =   CREATOR
            config foo.bar = baz

(Note that this conf file has NAME/ rules, which **have changed**
significantly in g3; see [here][g2i-name] for details).

These are the repos already existing

    $ find repositories -name "*.git" | sort
    repositories/bar.git
    repositories/baz/u3.git
    repositories/baz/u4.git
    repositories/baz/uthree.git
    repositories/foo.git
    repositories/gitolite-admin.git
    repositories/testing.git

The config entries exist for all the baz/ repos:

    $ grep -2 foo `find repositories -name "config" `
    repositories/baz/uthree.git/config-[gitweb]
    repositories/baz/uthree.git/config- owner = u3
    repositories/baz/uthree.git/config:[foo]
    repositories/baz/uthree.git/config- bar = baz
    --
    repositories/baz/u4.git/config-[gitweb]
    repositories/baz/u4.git/config-     owner = u4
    repositories/baz/u4.git/config:[foo]
    repositories/baz/u4.git/config-     bar = baz
    --
    repositories/baz/u3.git/config-[gitweb]
    repositories/baz/u3.git/config-     owner = u3
    repositories/baz/u3.git/config:[foo]
    repositories/baz/u3.git/config-     bar = baz

## preparing for the migration

### getting g3

Fortunately this is easy here; I just happened to have the repo already
fetched so I just had to switch branches.  You may have to 'git clone ...'
from github.

    $ cd gitolite
    $ git checkout master
    Branch master set up to track remote branch master from origin.
    Switched to a new branch 'master'

### run check-g2-compat

This is a quick and dirty program to catch some of the big issues.

    $ cd
    $ gitolite/check-g2-compat
    INFO        This program only checks for uses that make the new g3 completely unusable
                or that might end up giving *more* access to someone if migrated as-is.
                It does NOT attempt to catch all the differences described in the docs.

    INFO        'see docs' usually means doc/g2migr.mkd
                (online at http://sitaramc.github.com/gitolite/g2migr.html)

    checking rc file...
    NOTE        GL_ADMINDIR is in the right place; assuming you did not mess with
                GL_CONF, GL_LOGT, GL_KEYDIR, and GL_CONF_COMPILED

    checking conf file(s)...
    SEVERE      NAME rules; see docs

    checking repos...
    WARNING     found 3 gl-creater files; see docs

    ...all done...

## the actual migration

Here's the actual migration, step by step

### step 1

    $ ls -a bin
    .                gl-admin-push    gl-install       gl-setup-authkeys  gl-VREF-DUPKEYS
    ..               gl-auth-command  gl-mirror-push   gl-system-install  gl-VREF-EMAIL_CHECK
    gitolite_env.pm  gl-compile-conf  gl-mirror-shell  gl-time            gl-VREF-FILETYPE
    gitolite.pm      gl-conf-convert  gl-query-rc      gl-tool            gl-VREF-MERGE_CHECK
    gitolite_rc.pm   gl-dryrun        gl-setup         gl-VREF-COUNT      sshkeys-lint
    $ rm -rf bin;mkdir bin

    $ grep GL_PACKAGE .gitolite.rc
    $GL_PACKAGE_CONF = "/home/g3/share/gitolite/conf";
    $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks";
    $ rm -rf share

    $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks";
    $ rm -rf share

    $ mv .gitolite.rc old.grc

(still on step 1, this is substep 3) notice we are cloning **on the server**,
using a **full path** to the repo.

    $ git clone repositories/gitolite-admin.git old.ga
    Cloning into 'old.ga'...
    done.
    $ rm -rf repositories/gitolite-admin.git/

Since I'm not interested in preserving the logs and don't have any custom
hooks:

    $ rm -rf .gitolite

### step 2

I have no variables that *must* be preset, since the report by
`check-g2-compat` is clear.

### step 3

Here we install the new gitolite.  Remember we already got the new software
(in order to run 'check-g2-compat').

Just check that bin is empty, then run 'install -ln' from the gitolite source
tree:

    $ ls -al bin
    total 8
    drwxrwxr-x 2 g3 g3 4096 Apr 24 10:57 .
    drwx------ 8 g3 g3 4096 Apr 24 10:59 ..
    $ gitolite/install -ln
    $ ls -al bin
    total 8
    drwxrwxr-x 2 g3 g3 4096 Apr 24 11:01 .
    drwx------ 8 g3 g3 4096 Apr 24 10:59 ..
    lrwxrwxrwx 1 g3 g3   30 Apr 24 11:01 gitolite -> /home/g3/gitolite/src/gitolite

OK that went well.  Now setup gitolite.  You don't need a key here; just use a
random name:

    $ gitolite setup -a admin
    Initialized empty Git repository in /home/g3/repositories/gitolite-admin.git/

### step 4

Now go to your old clone, and push it:

    $ cd old.ga
    $ gitolite push -f
        ...usual git progress output deleted...
    remote: FATAL: git config foo.bar not allowed
    remote: check GIT_CONFIG_KEYS in the rc file
    To /home/g3/repositories/gitolite-admin.git
     + 7eb8163...1474770 master -> master (forced update)

Aaha!  I forgot to set `CONFIG_KEYS` (new name for `GL_GIT_CONFIG_KEYS`) in
the new rc file so fix that:

    $ vim ~/.gitolite.rc
    (edit and set it to `.*` for now)

and push again:

    $ gitolite push -f
    Everything up-to-date

Damn.  We have to make a dummy commit to allow the push to do something.

But wait!  We forgot fix the [NAME/][g2i-name] rules, so may as well fix
those, add, and push:

    $ vim conf/gitolite.conf
    # change all NAME/ to VREF/NAME/
    # append a '- VREF/NAME/ = @all' at the end
    # save
    git add conf

    $ git commit -m name-rules
        ... some output for add...

    $ gitolite push -f
    Counting objects: 1, done.
    Writing objects: 100% (1/1), 181 bytes, done.
    Total 1 (delta 0), reused 0 (delta 0)
    Unpacking objects: 100% (1/1), done.
    To /home/g3/repositories/gitolite-admin.git
       1474770..4c2b41d  master -> master

### step 5

The only thing left is to fix up the gl-creater files:

    $ cd $HOME/repositories
    $ find . -type d -name "*.git" -prune | while read r
    > do
    >     mv $r/gl-creater $r/gl-creator
    > done 2>/dev/null

And we're done!

## checking things out

Let's see what repos u3 has:

    ssh u3 info
    hello u3, this is g3@sita-lt running gitolite3 v3.0-11-g090b0f5 on git 1.7.7.6

         C      baz/..*
     R W        baz/u3
     R W        baz/uthree
     R W        gitolite-admin
     R W        testing

That's a combination of 'info' and 'expand', by the way.  There is no expand
command any more.

How about adding a new repo and checking if the config entries made it?

    $ git ls-remote u4:baz/ufour
    Initialized empty Git repository in /home/g3/repositories/baz/ufour.git/
    $ grep -A1 foo `find repositories -name "config" `
    repositories/baz/u3.git/config:[foo]
    repositories/baz/u3.git/config- bar = baz
    --
    repositories/baz/u4.git/config:[foo]
    repositories/baz/u4.git/config- bar = baz
    --
    repositories/baz/ufour.git/config:[foo]
    repositories/baz/ufour.git/config-      bar = baz
    --
    repositories/baz/uthree.git/config:[foo]
    repositories/baz/uthree.git/config-     bar = baz

And there it is, in the second block of lines...

And now we're really done.