b12a967272
thanks to karihre on #gitolite for catching the first of the corrections (GL_GET_MEMBERSHIPS_PGM) and so reminding me...
277 lines
10 KiB
Markdown
277 lines
10 KiB
Markdown
# #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:
|
|
|
|
## #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].
|