If you're curious why I wrote v3, and what was wrong with v2, read this.

First things first: v3 came out in April 2012. v2 will continue to be supported for critical bugs, although enhancements and new features won't happen. v1 is not supported anymore.

That said, if you're an existing (gitolite v1.x or v2.x) user, and wish to migrate, here are the steps:

This page is about migrating from older gitolite to "v3". If you're migrating from gitosis, let me first welcome you to the 21st century, and then point you here.

1 pre-migration checklist

Both Fedora/RH and Debian use 'gitolite3' as the package name for this version, because it is not auto-upgradable from v2. You may need to uninstall 'gitolite' then install 'gitolite3' in that case. Please take a backup of at least ~/repositories/gitolite-admin.git, ~/.gitolite.rc, and ~/.gitolite before doing that. You may need more specific help if you're using any of the settings marked as "requires presetting" in the "high impact" subsection below; please contact me if needed.

This section tells you what changes affect you and your users. The closer you were to a default install of the old gitolite, the less time a migration will take.

Note: as you read this section, and run the check-g2-compat program, be sure to make a note of any variables you have used which the pre-migration checklist describes as "requires presetting".

First things first: v2 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 for details.

The check-g2-compat program attempts to identify any big issues you will be facing; run that first. See later 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.

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

1.1.1 high impact

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

1.1.2 medium impact

(important functionality lost, but access control not compromised)

1.1.3 low impact

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

1.2 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:

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":

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

2 the actual migration

(Note: You may also like the example migration page).

Note: nothing in any of the gitolite install/setup/etc will ever touch the data in any repository except the gitolite-admin repo. The only thing it will normally touch in normal repos is the update hook.

Note: all migration happens on the server; you do not need your workstation.

  1. Carefully wipe out the old gitolite:

  2. Install gitolite v3; see install.

  3. If you're using any rc variables that the pre-migration checklist said would "require presetting", then read about presetting the rc file, and follow those instructions to create your new rc file.

  4. Setup gitolite; see setup. However, the 'setup' step need not supply a private key. You can run it as gitolite setup -a admin.

    NOTE: ignore any 'split conf not set, gl-conf present...' errors at this time. You may see none, some, or many. It does not matter right now.

  5. Make sure your gitolite-admin clone has the correct pubkey for the administrator in its keydir directory, then run gitolite push -f to overwrite the "default" admin repo created by the install.

    NOTE that is gitolite push not git push!

  6. Handle any errors, look for migration issues, etc., as described in the links at the top of this page.

    This also includes building up your new ~/.gitolite.rc file.

You're done.

3 appendix 1: v2-v3 incompatibilities

This page expands on some incompatibilities that were only briefly mentioned in the pre-migration section earlier.

3.1 NAME rules

  1. NAME/ rules must be changed to VREF/NAME/

  2. Fallthru on all VREFs is "success" now, so any NAME/ rules you have MUST change the rule list in some way to maintain the same restrictions. The simplest is to add the following line to the end of each repo's rule list:
        -   VREF/NAME/       =   @all

3.2 subconf command in admin repo

(This is also affected by the previous issue, 'NAME rules'; please read that as well).

If you're using delegation in your admin conf setup, please add the following lines to the end of the gitolite-admin rules in your conf/gitolite.conf file:

repo gitolite-admin
    -   VREF/NAME/       =   @all

subconf "fragments/*.conf"

The first part compensates for fallthru now being a success when processing VREF rules (NAME rules are just one specific VREF). Although, ideally, you should change your rule list so that you no longer require that line. As the vref page says:

Virtual refs are best used as additional "deny" rules, performing extra checks that core gitolite cannot.

The second part explicitly says when and where to include the subconf files. (Before subconf was invented, this used to happen implicitly at the end of the main conf file, and was hardcoded to that specific glob.)

3.3 gl-time for performance measurement

If you've been using gl-time for performance measurement, there's a much better system available now.

gl-time used to only log elapsed time. The new 'CpuTime' trigger module shipped with gitolite, if enabled in the rc file, can also report CPU times using perl's 'times()' function. See comments within that file and in the default rc file that contain the word "cpu", for more details.

Further, you can copy that module with a different name, add your own functionality, and invoke that from the rc file instead.

3.4 changes in mirroring setup

There are several changes with regard to mirroring: