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>

----

[[TOC]]

----

First things first: g2 will be supported for a good long time for critical
bugs, although enhancements and new features won't happen.

Migration should be straightforward, but it is not automatic.  The biggest
differences are in the rc file, mirroring, "NAME/" rules, and delegation.

>   ----

>   **Presetting the rc file**

>   Some rc settings in the older gitolite are such that you cannot directly
>   run `gitolite setup` when you're ready to migrate.  **Doing that will
>   clobber something important**.  See [presetting the rc file][rc-preset]
>   for details.

>   ----

The `check-g2-compat` program attempts to identify any *big* issues you will
be facing; run that first.  See [later][cg2c] in this page for what its
messages mean.  If it does not report any issues, your migrate will probably
go quickly.  I still suggest you go through the links below in case that
program missed something.

## incompatible features

Here's a list of incompatible features and what you need to do to migrate.
Some of them have links where there is more detail than I want to put here.

### high impact

(serious loss of functionality and/or access control compromised)

  * [`NAME/`][g2i-name] rules: thes need to change to `VREF/NAME/`, and you
    need to add a deny rule at the end because fallthru is "success" for all
    [VREFs][vref] now, including the "NAME" VREF.

  * [subconf][g2i-subconf]: if you're using [delegation][deleg], there is no
    implicit "subconf" at the end; you'll have to add it in.

  * There are several important differences in mirroring.  You can start from
    scratch by reading the new [mirroring][mirroring] doc or
    [migrate][g2i-mirroring] (carefully!).

  * `ADMIN_POST_UPDATE_CHAINS_TO` -- **dropped**.  Add your script to the
    `POST_COMPILE` trigger chain.  Your script won't be getting the arguments
    that *git* sends to the post-update hook, but for the admin repo the only
    argument that even comes in (or is significant) is "refs/heads/master"
    anyway.

  * `GL_ALL_INCLUDES_SPECIAL` -- **dropped**, **requires presetting**.

    @all always includes gitweb and daemon now.  Use [deny-rules][] if you
    want to say `R = @all` but not have the repo(s) be visible to gitweb or
    daemon.

  * `GL_NO_CREATE_REPOS` -- **dropped**.  If you think you need this, email
    me.  I know one group who does need this so I will be putting it in
    eventually but not right away.  It's almost certain to be renamed anyway.

  * `GL_NO_DAEMON_NO_GITWEB` **dropped**, **requires presetting**.  Default
    will clobber your projects.list file and git-daemon-export-ok files.

    Comment out the appropriate lines in the rc file, in the `POST_COMPILE`
    *and* the `POST_CREATE` trigger sections.  As a bonus, gitweb and daemon
    can now be separately disabled, instead of both being tied to the same
    setting.

  * `GL_NO_SETUP_AUTHKEYS` **dropped**, **requires presetting**.  Default will
    clobber your authkeys file.

    Comment out all the line(s) that call ssh-authkeys in the rc file.

  * `UPDATE_CHAINS_TO` **dropped**, **requires presetting**.  Default will
    fail to run this extra check when users push.

    Use a [vref][] instead.  You can directly use any existing chained-to
    script as a VREF; they'll work.  Don't forget to add a rule that
    references the new VREF!

  * `GIT_PATH` **dropped**, **requires presetting**.

    If you need its functionality, add these lines to the end of the rc file:

        $ENV{PATH}="...whatever you want...";
        1;

### medium impact

(important functionality lost, but access control not compromised)

  * `GL_ADMINDIR` -- **dropped**, is now at a fixed location: `~/.gitolite`.
    If you want it somewhere else go ahead and move it, then place a symlink
    from the assumed location to the real one.

  * `GL_GET_MEMBERSHIPS_PGM` -- is now `GROUPLIST_PGM`, see
    [here][ldap].

  * `GL_WILDREPOS_DEFPERMS` -- is now `DEFAULT_ROLE_PERMS`.

  * `REPO_BASE` -- **dropped**, is now at a fixed location: `~/repositories`.
    If you want it somewhere else go ahead and move it, then place a symlink
    from the assumed location to the real one.

### low impact

(ancillary, non-core, or minor functionality lost)

  * Built-in command `expand` -- **dropped**.  The 'info' command shows you
    both normal and wild repos now.  The output format is also much simpler.

  * Built-in commands 'getperms', 'setperms' -- **merged** into external
    command 'perms'.  Run `ssh git@host perms -h` for details.

    Similarly, 'getdesc' and 'setdesc' have been merged into 'desc'.

  * Several 'ADC's -- see the [dev-status][] page for more on this.

  * [gl-time][g2i-gl-time]: the CpuTime module replaces gl-time.

  * `BIG_INFO_CAP` -- **dropped**.  If you think you must have this, try it
    without and see if there's a difference.  If you *know* you need this,
    convince me.

  * `GL_ADC_PATH` -- **dropped**.  It is obsolete; use [commands][] or add
    [your own][dev-notes].

  * `GL_ALL_READ_ALL` -- **dropped**.  If you think you must have this, try it
    without and see if there's a difference.  If you *know* you need this,
    convince me.

  * `GL_BIG_CONFIG` -- **dropped**.  This feature is default now.

  * `GL_CONF`, `GL_CONF_COMPILED`, and `GL_KEYDIR` -- **dropped**.  You had no
    business touching these anyway; if you did, move them into the expected
    default locations before attempting to run `gitolite setup`

  * `GL_GITCONFIG_KEYS` -- is now `GIT_CONFIG_KEYS`.

  * `GL_LOGT` -- now has a fixed value; email me if this is a problem.

  * `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` -- **dropped**.  They are not
    needed anymore, but check if you had any custom hooks set in the latter
    location and copy them across.

  * `GL_PERFLOGT` -- **dropped**.  See [gl-time][g2i-gl-time].

  * `GL_SITE_INFO` -- is now `SITE_INFO`.

  * `GL_WILDREPOS` -- **dropped**.  This feature is default now.

  * `GL_WILDREPOS_PERM_CATS` -- is now the ROLES hash in the rc file.

  * `RSYNC_BASE` -- needs work.  Email me if you are using this.

  * `NICE_VALUE` -- **dropped**.  Uncomment the 'renice 10' line in the rc
    file.  You can also change the 10 to something else if you wish.

  * `PROJECTS_LIST` -- is now `GITWEB_PROJECTS_LIST`.  More importantly, it is
    only used by update-gitweb-access-list in src/commands/post-compile.  This
    variable now has nothing to do with gitolite core, and the rc is just
    helping to store settings for external programs like that one.

  * `REPO_UMASK` -- is now `UMASK`.

  * `WEB_INTERFACE` and `GITWEB_URI_ESCAPE` -- **dropped**.  Patches to the
    update program to directly do those things are welcome.  Personally, I
    think people who use spaces and other funky characters in dir/file names
    should be shot but no one listens to me anyway.

## #cg2c using 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

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

  * `mirroring used`

    There have been quite a few changes to mirroring.  You can start from
    scratch by reading the new [mirroring][mirroring] doc or
    [migrate][g2i-mirroring] (carefully!).

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

        find `gitolite query-rc GL_REPO_BASE` -name gl-perms |
            xargs perl -pi -e 's/\bR\b/READERS/;s/\bRW\b/WRITERS/'

## #rc-preset presetting the rc file

Some rc settings in the older gitolite are such that you cannot directly run
`gitolite setup` when you're ready to migrate.  **Doing that will clobber
something important**.  You have to create a default rc file, edit it
appropriately, and *then* run `gitolite setup`.

The most serious example of this is `GL_NO_SETUP_AUTHKEYS`, which tells the
(old) gitolite that you want to manage `~/.ssh/authorized_keys` yourself and
it should not fiddle with it.

If you don't preset the rc (in this case, by commenting out the 'ssh-authkeys'
line) **before** running `gitolite setup`, **your `~/.ssh/authorized_keys`
file will get clobbered**.

The actual rc settings that require presetting are listed in the "high
impact" section above.  This section tells you how to do the presetting.

  * save your old (g2) rc file somewhere, just in case

  * run

        gitolite print-default-rc > $HOME/.gitolite.rc

  * edit the file

        ${EDITOR:-vim} $HOME/.gitolite.rc

    make appropriate changes as described elsewhere in this migration guide,
    and save it.

  * *then* you can run [gitolite setup][setup].