# #g2migr migrating from g2 **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. ## 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].