gitolite/doc/g2migr.mkd

#g2migr migrating from g2

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

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