diff --git a/doc/g2migr-example.mkd b/doc/g2migr-example.mkd new file mode 100644 index 0000000..18c2ba8 --- /dev/null +++ b/doc/g2migr-example.mkd @@ -0,0 +1,269 @@ +# migration example + +This shows what a typical migration would look like, using a test setup. + +[[TOC]] + +## existing setup + +The existing gitolite is the latest in the "g2" (v2.x) branch. + +First, the rc file has the following lines different from the default: + + -$GL_WILDREPOS = 0; + +$GL_WILDREPOS = 1; + + -$GL_GITCONFIG_KEYS = ""; + +$GL_GITCONFIG_KEYS = ".*"; + +Next, the conf/gitolite.conf file in `~/.gitolite`: + + repo gitolite-admin + RW+ = tester u1 + + repo testing + RW+ = @all + + repo foo + RW+ = u1 u2 + RW+ NAME/ = u1 + RW+ NAME/u2 = u2 + + repo bar + RW = u2 + + repo baz/..* + C = u3 u4 + RW+ = CREATOR + config foo.bar = baz + +(Note that this conf file has NAME/ rules, which **have changed** +significantly in g3; see [here][g2i-name] for details). + +These are the repos already existing + + $ find repositories -name "*.git" | sort + repositories/bar.git + repositories/baz/u3.git + repositories/baz/u4.git + repositories/baz/uthree.git + repositories/foo.git + repositories/gitolite-admin.git + repositories/testing.git + +The config entries exist for all the baz/ repos: + + $ grep -2 foo `find repositories -name "config" ` + repositories/baz/uthree.git/config-[gitweb] + repositories/baz/uthree.git/config- owner = u3 + repositories/baz/uthree.git/config:[foo] + repositories/baz/uthree.git/config- bar = baz + -- + repositories/baz/u4.git/config-[gitweb] + repositories/baz/u4.git/config- owner = u4 + repositories/baz/u4.git/config:[foo] + repositories/baz/u4.git/config- bar = baz + -- + repositories/baz/u3.git/config-[gitweb] + repositories/baz/u3.git/config- owner = u3 + repositories/baz/u3.git/config:[foo] + repositories/baz/u3.git/config- bar = baz + +## preparing for the migration + +### getting g3 + +Fortunately this is easy here; I just happened to have the repo already +fetched so I just had to switch branches. You may have to 'git clone ...' +from github. + + $ cd gitolite + $ git checkout master + Branch master set up to track remote branch master from origin. + Switched to a new branch 'master' + +### run check-g2-compat + +This is a quick and dirty program to catch some of the big issues. + + $ cd + $ gitolite/check-g2-compat + INFO This program only checks for uses that make the new g3 completely unusable + or that might end up giving *more* access to someone if migrated as-is. + It does NOT attempt to catch all the differences described in the docs. + + INFO 'see docs' usually means doc/g2migr.mkd + (online at http://sitaramc.github.com/gitolite/g3/g2migr.html) + + checking rc file... + NOTE GL_ADMINDIR is in the right place; assuming you did not mess with + GL_CONF, GL_LOGT, GL_KEYDIR, and GL_CONF_COMPILED + + checking conf file(s)... + SEVERE NAME rules; see docs + + checking repos... + WARNING found 3 gl-creater files; see docs + + ...all done... + +## the actual migration + +Here's the actual migration, step by step + +### step 1 + + $ ls -a bin + . gl-admin-push gl-install gl-setup-authkeys gl-VREF-DUPKEYS + .. gl-auth-command gl-mirror-push gl-system-install gl-VREF-EMAIL_CHECK + gitolite_env.pm gl-compile-conf gl-mirror-shell gl-time gl-VREF-FILETYPE + gitolite.pm gl-conf-convert gl-query-rc gl-tool gl-VREF-MERGE_CHECK + gitolite_rc.pm gl-dryrun gl-setup gl-VREF-COUNT sshkeys-lint + $ rm -rf bin;mkdir bin + + $ grep GL_PACKAGE .gitolite.rc + $GL_PACKAGE_CONF = "/home/g3/share/gitolite/conf"; + $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks"; + $ rm -rf share + + $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks"; + $ rm -rf share + + $ mv .gitolite.rc old.grc + +(still on step 1, this is substep 3) notice we are cloning **on the server**, +using a **full path** to the repo. + + $ git clone repositories/gitolite-admin.git old.ga + Cloning into 'old.ga'... + done. + $ rm -rf repositories/gitolite-admin.git/ + +Since I'm not interested in preserving the logs and don't have any custom +hooks: + + $ rm -rf .gitolite + +### step 2 + +I have no variables that *must* be preset, since the report by +`check-g2-compat` is clear. + +### step 3 + +Here we install the new gitolite. Remember we already got the new software +(in order to run 'check-g2-compat'). + +Just check that bin is empty, then run 'install -ln' from the gitolite source +tree: + + $ ls -al bin + total 8 + drwxrwxr-x 2 g3 g3 4096 Apr 24 10:57 . + drwx------ 8 g3 g3 4096 Apr 24 10:59 .. + $ gitolite/install -ln + $ ls -al bin + total 8 + drwxrwxr-x 2 g3 g3 4096 Apr 24 11:01 . + drwx------ 8 g3 g3 4096 Apr 24 10:59 .. + lrwxrwxrwx 1 g3 g3 30 Apr 24 11:01 gitolite -> /home/g3/gitolite/src/gitolite + +OK that went well. Now setup gitolite. You don't need a key here; just use a +random name: + + $ gitolite setup -a admin + Initialized empty Git repository in /home/g3/repositories/gitolite-admin.git/ + +### step 4 + +Now go to your old clone, and push it: + + $ cd old.ga + $ gitolite push -f + ...usual git progress output deleted... + remote: FATAL: git config foo.bar not allowed + remote: check GIT_CONFIG_KEYS in the rc file + To /home/g3/repositories/gitolite-admin.git + + 7eb8163...1474770 master -> master (forced update) + +Aaha! I forgot to set `CONFIG_KEYS` (new name for `GL_GIT_CONFIG_KEYS`) in +the new rc file so fix that: + + $ vim ~/.gitolite.rc + (edit and set it to `.*` for now) + +and push again: + + $ gitolite push -f + Everything up-to-date + +Damn. We have to make a dummy commit to allow the push to do something. + +But wait! We forgot fix the [NAME/][g2i-name] rules, so may as well fix +those, add, and push: + + $ vim conf/gitolite.conf + # change all NAME/ to VREF/NAME/ + # append a '- VREF/NAME/ = @all' at the end + # save + git add conf + + $ git commit -m name-rules + ... some output for add... + + $ gitolite push -f + Counting objects: 1, done. + Writing objects: 100% (1/1), 181 bytes, done. + Total 1 (delta 0), reused 0 (delta 0) + Unpacking objects: 100% (1/1), done. + To /home/g3/repositories/gitolite-admin.git + 1474770..4c2b41d master -> master + +### step 5 + +The only thing left is to fix up the gl-creater files: + + $ cd $HOME/repositories + $ find . -type d -name "*.git" -prune | while read r + > do + > mv $r/gl-creater $r/gl-creator + > done 2>/dev/null + +And we're done! + +## checking things out + +Let's see what repos u3 has: + + ssh u3 info + hello u3, this is g3@sita-lt running gitolite3 v3.0-11-g090b0f5 on git 1.7.7.6 + + C baz/..* + R W baz/u3 + R W baz/uthree + R W gitolite-admin + R W testing + +That's a combination of 'info' and 'expand', by the way. There is no expand +command any more. + +How about adding a new repo and checking if the config entries made it? + + $ git ls-remote u4:baz/ufour + Initialized empty Git repository in /home/g3/repositories/baz/ufour.git/ + $ grep -A1 foo `find repositories -name "config" ` + repositories/baz/u3.git/config:[foo] + repositories/baz/u3.git/config- bar = baz + -- + repositories/baz/u4.git/config:[foo] + repositories/baz/u4.git/config- bar = baz + -- + repositories/baz/ufour.git/config:[foo] + repositories/baz/ufour.git/config- bar = baz + -- + repositories/baz/uthree.git/config:[foo] + repositories/baz/uthree.git/config- bar = baz + +And there it is, in the second block of lines... + +And now we're really done. diff --git a/doc/g2migr.mkd b/doc/g2migr.mkd index 46079a8..e7f2864 100644 --- a/doc/g2migr.mkd +++ b/doc/g2migr.mkd @@ -145,7 +145,7 @@ Some of them have links where there is more detail than I want to put here. 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 `GITCONFIG_KEYS`. + * `GL_GITCONFIG_KEYS` -- is now `GIT_CONFIG_KEYS`. * `GL_LOGT` -- now has a fixed value; email me if this is a problem. diff --git a/doc/install.mkd b/doc/install.mkd index 65697ab..ad681ec 100644 --- a/doc/install.mkd +++ b/doc/install.mkd @@ -166,13 +166,21 @@ are the steps: you were to a default install of the old gitolite, the less time a migration will take.) + This includes at least running `check-g2-compat` to see what are the big + issues you might need to address during the migration. + ### the actual migration +(Note: You may also like the [example migration][g2migr-example] 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. -1. **On the server**, carefully wipe out the old gitolite: +**Note: all migration happens on the server; you do not need your +workstation**. + +1. Carefully wipe out the old gitolite: * The **code** @@ -209,7 +217,11 @@ will normally touch in normal repos is the `update` hook. your new rc file. 3. Install gitolite g3; see [quick install and setup][qi] or [install][] - followed by [setup][]. + followed by [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. 4. Make sure your gitolite-admin clone has the correct pubkey for the administrator in its `keydir` directory, then run [`gitolite push