docs/g2migr-example.mkd

   1 # migration example
   2
   3 This shows what a typical migration would look like, using a test setup.
   4
   5 # existing setup
   6
   7 The existing gitolite is the latest in the "g2" (v2.x) branch.
   8
   9 First, the rc file has the following lines different from the default:
  10
  11     -$GL_WILDREPOS = 0;
  12     +$GL_WILDREPOS = 1;
  13
  14     -$GL_GITCONFIG_KEYS = "";
  15     +$GL_GITCONFIG_KEYS = ".*";
  16
  17 Next, the conf/gitolite.conf file in `~/.gitolite`:
  18
  19 ```gitolite
  20 repo    gitolite-admin
  21         RW+             =   tester u1
  22
  23 repo    testing
  24         RW+     =   @all
  25
  26 repo foo
  27         RW+             =   u1 u2
  28         RW+ NAME/       =   u1
  29         RW+ NAME/u2     =   u2
  30
  31 repo bar
  32         RW  =   u2
  33
  34 repo baz/..*
  35         C   =   u3 u4
  36         RW+         =   CREATOR
  37         config foo.bar = baz
  38 ```
  39
  40 (Note that this conf file has NAME/ rules, which **have changed**
  41 significantly in v3; see [here][g2i-name] for details).
  42
  43 These are the repos already existing
  44
  45     $ find repositories -name "*.git" | sort
  46     repositories/bar.git
  47     repositories/baz/u3.git
  48     repositories/baz/u4.git
  49     repositories/baz/uthree.git
  50     repositories/foo.git
  51     repositories/gitolite-admin.git
  52     repositories/testing.git
  53
  54 The config entries exist for all the baz/ repos:
  55
  56     $ grep -2 foo `find repositories -name "config" `
  57     repositories/baz/uthree.git/config-[gitweb]
  58     repositories/baz/uthree.git/config- owner = u3
  59     repositories/baz/uthree.git/config:[foo]
  60     repositories/baz/uthree.git/config- bar = baz
  61     --
  62     repositories/baz/u4.git/config-[gitweb]
  63     repositories/baz/u4.git/config-     owner = u4
  64     repositories/baz/u4.git/config:[foo]
  65     repositories/baz/u4.git/config-     bar = baz
  66     --
  67     repositories/baz/u3.git/config-[gitweb]
  68     repositories/baz/u3.git/config-     owner = u3
  69     repositories/baz/u3.git/config:[foo]
  70     repositories/baz/u3.git/config-     bar = baz
  71
  72 # preparing for the migration
  73
  74 ## getting v3
  75
  76 Fortunately this is easy here; I just happened to have the repo already
  77 fetched so I just had to switch branches.  You may have to 'git clone ...'
  78 from github.
  79
  80     $ cd gitolite
  81     $ git checkout master
  82     Branch master set up to track remote branch master from origin.
  83     Switched to a new branch 'master'
  84
  85 ## run check-g2-compat
  86
  87 This is a quick and dirty program to catch some of the big issues.
  88
  89     $ cd
  90     $ gitolite/check-g2-compat
  91     INFO        This program only checks for uses that make the new v3 completely unusable
  92                 or that might end up giving *more* access to someone if migrated as-is.
  93                 It does NOT attempt to catch all the differences described in the docs.
  94
  95     INFO        'see docs' usually means the pre-migration checklist in
  96                 "g2migr.html"; to get there, start from the main migration
  97                 page at https://sitaramc.github.com/gitolite/migr/
  98
  99     checking rc file...
 100     NOTE        GL_ADMINDIR is in the right place; assuming you did not mess with
 101                 GL_CONF, GL_LOGT, GL_KEYDIR, and GL_CONF_COMPILED
 102
 103     checking conf file(s)...
 104     SEVERE      NAME rules; see docs
 105
 106     checking repos...
 107     WARNING     found 3 gl-creater files; see docs
 108
 109     ...all done...
 110
 111 # the actual migration
 112
 113 Here's the actual migration, step by step
 114
 115 ## step 1
 116
 117     $ ls -a bin
 118     .                gl-admin-push    gl-install       gl-setup-authkeys  gl-VREF-DUPKEYS
 119     ..               gl-auth-command  gl-mirror-push   gl-system-install  gl-VREF-EMAIL_CHECK
 120     gitolite_env.pm  gl-compile-conf  gl-mirror-shell  gl-time            gl-VREF-FILETYPE
 121     gitolite.pm      gl-conf-convert  gl-query-rc      gl-tool            gl-VREF-MERGE_CHECK
 122     gitolite_rc.pm   gl-dryrun        gl-setup         gl-VREF-COUNT      sshkeys-lint
 123     $ rm -rf bin;mkdir bin
 124
 125     $ grep GL_PACKAGE .gitolite.rc
 126     $GL_PACKAGE_CONF = "/home/git/share/gitolite/conf";
 127     $GL_PACKAGE_HOOKS = "/home/git/share/gitolite/hooks";
 128     $ rm -rf share
 129
 130     $GL_PACKAGE_HOOKS = "/home/git/share/gitolite/hooks";
 131     $ rm -rf share
 132
 133     $ mv .gitolite.rc old.grc
 134
 135 (still on step 1, this is substep 3) notice we are cloning **on the server**,
 136 using a **full path** to the repo.
 137
 138     $ git clone repositories/gitolite-admin.git old.ga
 139     Cloning into 'old.ga'...
 140     done.
 141     $ rm -rf repositories/gitolite-admin.git/
 142
 143 Since I'm not interested in preserving the logs and don't have any custom
 144 hooks:
 145
 146     $ rm -rf .gitolite
 147
 148 ## step 2
 149
 150 I have no variables that *must* be preset, since the report by
 151 `check-g2-compat` is clear.
 152
 153 ## step 3
 154
 155 Here we install the new gitolite.  Remember we already got the new software
 156 (in order to run 'check-g2-compat').
 157
 158 Just check that bin is empty, then run 'install -ln' from the gitolite source
 159 tree:
 160
 161     $ ls -al bin
 162     total 8
 163     drwxrwxr-x 2 git git 4096 Apr 24 10:57 .
 164     drwx------ 8 git git 4096 Apr 24 10:59 ..
 165     $ gitolite/install -ln
 166     $ ls -al bin
 167     total 8
 168     drwxrwxr-x 2 git git 4096 Apr 24 11:01 .
 169     drwx------ 8 git git 4096 Apr 24 10:59 ..
 170     lrwxrwxrwx 1 git git   30 Apr 24 11:01 gitolite -> /home/git/gitolite/src/gitolite
 171
 172 OK that went well.  Now setup gitolite.  You don't need a key here; just use a
 173 random name:
 174
 175     $ gitolite setup -a admin
 176     Initialized empty Git repository in /home/git/repositories/gitolite-admin.git/
 177
 178 ## step 4
 179
 180 Now go to your old clone, and push it:
 181
 182     $ cd old.ga
 183     $ gitolite push -f
 184         ...usual git progress output deleted...
 185     remote: FATAL: git config foo.bar not allowed
 186     remote: check GIT_CONFIG_KEYS in the rc file
 187     To /home/git/repositories/gitolite-admin.git
 188      + 7eb8163...1474770 master -> master (forced update)
 189
 190 Aaha!  I forgot to set `GIT_CONFIG_KEYS` (new name for `GL_GITCONFIG_KEYS`) in
 191 the new rc file so fix that:
 192
 193     $ vim ~/.gitolite.rc
 194     (edit and set it to `.*` for now)
 195
 196 and push again:
 197
 198     $ gitolite push -f
 199     Everything up-to-date
 200
 201 Damn.  We have to make a dummy commit to allow the push to do something.
 202
 203 But wait!  We forgot fix the [NAME/][g2i-name] rules, so may as well fix
 204 those, add, and push:
 205
 206     $ vim conf/gitolite.conf
 207     # change all NAME/ to VREF/NAME/
 208     # append a '- VREF/NAME/ = @all' at the end
 209     # save
 210     git add conf
 211
 212     $ git commit -m name-rules
 213         ... some output for add...
 214
 215     $ gitolite push -f
 216     Counting objects: 1, done.
 217     Writing objects: 100% (1/1), 181 bytes, done.
 218     Total 1 (delta 0), reused 0 (delta 0)
 219     Unpacking objects: 100% (1/1), done.
 220     To /home/git/repositories/gitolite-admin.git
 221        1474770..4c2b41d  master -> master
 222
 223 ## step 5
 224
 225 The only thing left is to fix up the gl-creater files:
 226
 227     $ cd $HOME/repositories
 228     $ find . -type d -name "*.git" -prune | while read r
 229     > do
 230     >     mv $r/gl-creater $r/gl-creator
 231     > done 2>/dev/null
 232
 233 And we're done!
 234
 235 # checking things out
 236
 237 Let's see what repos u3 has:
 238
 239     # as user 'u3'
 240     ssh git@server info
 241     hello u3, this is git@server running gitolite3 v3.0-11-g090b0f5 on git 1.7.7.6
 242
 243          C      baz/..*
 244      R W        baz/u3
 245      R W        baz/uthree
 246      R W        gitolite-admin
 247      R W        testing
 248
 249 That's a combination of 'info' and 'expand', by the way.  There is no expand
 250 command any more.
 251
 252 How about adding a new repo and checking if the config entries made it?
 253
 254     # as user u4
 255     $ git ls-remote git@server:baz/ufour
 256     Initialized empty Git repository in /home/git/repositories/baz/ufour.git/
 257     $ grep -A1 foo `find repositories -name "config" `
 258     repositories/baz/u3.git/config:[foo]
 259     repositories/baz/u3.git/config- bar = baz
 260     --
 261     repositories/baz/u4.git/config:[foo]
 262     repositories/baz/u4.git/config- bar = baz
 263     --
 264     repositories/baz/ufour.git/config:[foo]
 265     repositories/baz/ufour.git/config-      bar = baz
 266     --
 267     repositories/baz/uthree.git/config:[foo]
 268     repositories/baz/uthree.git/config-     bar = baz
 269
 270 And there it is, in the second block of lines...
 271
 272 And now we're really done.
 273