gitolite/doc/g2migr.mkd

## #g2migr migrating from g2

<font color="red">

**This document is a *MUST* read if you are currently using g2 and want to
move to g3.**

</font>

First things first: g2 will be supported for a good long time.  My current
*expert* users do not cause me any load anyway.

Migration should be straightforward, but it is not automatic.  You should run
the "check-g2-compat" program first, to see any *major* differences that
affect you.  The bulk of the changes are in the RC file, which must be
manually handled (links below).  The conf files have very few changes -- they
apply only if you use "NAME/" or delegation.

You must first read about [incompatible][g2incompat] features and
[dropped][g2dropped] features.  Some features have been replaced with
[alternatives][g2alt].

Since the majority of changes are in the rc file, they're all listed
[here][g2rcdiff].

The rest of this page describes the completely standalone "check-g2-compat"
script that you can find in the repo root (i.e., not in "src/").

### the "check-g2-compat" program

This program checks a few things only, not everything.  In particular, it
looks for settings and status that might:

  * make g3 unusable for lots of users
  * make g3 give *more* access than g2 under some conditions.

It does NOT look for or warn about anything else; you're expected to read (and
act upon, if needed) the rest of the migration guide links given a few paras
above to cover everything else.

Here's an explanation of those messages that the check-g2-compat program may
put that contain the words "see docs":

  * `GL_ADMINDIR in the wrong place -- aborting`

    It expects to find `GL_ADMINDIR` and `REPO_BASE` pointing to the right
    places.  It aborts if these conditions are not met and does not scan
    further since that sort of guesswork is not good.  If you are in that
    position, make a symlink from the real location to the expected location,
    change the RC accordingly, and re-try.

  * `REPO_BASE in the wrong place -- aborting`

    same as above

  * `fallthru in NAME rules`

    **This is a significant difference and affects access badly (gives access
    that would otherwise not be given)**.  Please see the [list of non-RC
    incompatibilities][g2incompat].

  * `subconf command in admin repo`

    This is not so bad security wise but it might *reduce* access by not
    processing files you intended to.  Again, see the same link as in the
    previous bullet.

  * `found N gl-creater files`

    These need to be renamed to `gl-creator` (the correct spelling at last,
    hooray!).  Suggested command sequence:

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

    Once you do this, the g2 will not work completely unless you change them
    back.

  * `found N gl-perms files with R or RW`

    Setting perms of R and RW will no longer work; you have to say READERS and
    WRITERS now.  Suggested command:

The following variables need to be [preset][rc-preset] in the rc file
**before** running `gitolite setup`.  Otherwise the default actions will
clobber something and require some recovery.

  * `GL_NO_SETUP_AUTHKEYS` (default will clobber your authkeys file)

  * `GL_NO_DAEMON_NO_GITWEB` (default will clobber your projects.list file and
    git-daemon-export-ok files)

  * `UPDATE_CHAINS_TO` (default will fail to run this extra check when users
    push)

  * `ADMIN_POST_UPDATE_CHAINS_TO` (severity depends on what your code is
    doing; see [g2rcdiff][] for how to fix this)

  * `GL_ALL_INCLUDES_SPECIAL` (default will allow gitweb and daemon to be able
    to read any repos that have `R = @all`)

  * `GIT_PATH` (presumably your git is in some non-std path so unless you
    preset `$ENV{PATH}` per instructions in the [rc file
    differences][g2rcdiff] doc, nothing will work).