This document is a MUST read if you are currently using g2 and want to move to g3.
[[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.
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.
(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;
(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.
(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.
This program checks a few things only, not everything. In particular, it looks for settings and status that might:
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:
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].