docs/migr.mkd

   1 # migrating from gitolite v2
   2
   3 ----
   4
   5 Gitolite v3 came out in April 2012.  Until now, my policy was that I would not
   6 support it except for critical issues, but I think by now (I am writing this
   7 in Feb 2017), it's time to cut it completely.
   8
   9 As such, migration is also not supported.  Please perform a clean install of
  10 the latest gitolite and bring your existing repos into this new installation.
  11 Details below.
  12
  13 The old, detailed, migration document is still available in the [archive
  14 directory][arch] of the gitolite-doc repo, if you really need it, but you're
  15 on your own.  After five years, it makes little sense to maintain all that in
  16 the active document hierarchy.
  17
  18 Despite all that, this document *does* list some of the more important issues,
  19 mainly those that cause a significant change in behaviour.
  20
  21 [arch]: https://github.com/sitaramc/gitolite-doc/tree/master/archive
  22
  23 ## step 1: backups
  24
  25 *   take a backup of all `~/repositories` from the v2 server
  26 *   take an extra backup, in the form of a normal `git clone`, of the
  27     `gitolite-admin` repository
  28 *   take a backup of `~/.gitolite.rc` and keep it handy
  29 *   (*optional but suggested*) take a backup of `~/.gitolite` and `~/.ssh`
  30
  31 ## step 2: install gitolite
  32
  33 !!! danger "Important:"
  34
  35     If you are reusing the same [hosting user][hu] on the same server, for the
  36     new setup, you will need to clean out the old one as much as you can so
  37     its artefacts don't interfere with the new installation.  This means all
  38     the files and directories you backed up above, including the optional
  39     ones.
  40
  41 To install, use one or more of the links in the "install" section in the
  42 navigation bar at the top.
  43
  44 !!! note "Important:"
  45
  46     Do **NOT** change the `gitolite.conf` from the minimal one that a fresh
  47     install creates at this stage.
  48
  49 Smoke test the installation by cloning the `testing` repo and pushing some
  50 minor change to it.
  51
  52 [hu]: concepts#the-hosting-user
  53
  54 ## step 3: add existing repos
  55
  56 Once the install is done, follow the instructions [here][existing] to bring in
  57 existing repos.
  58
  59 At the point where it talks about adding repos to the gitolite.conf file, you
  60 can copy relevant bits from your old gitolite-admin repo.
  61
  62 [existing]: basic-admin#appendix-1-bringing-existing-repos-into-gitolite
  63
  64 ## step 4: identify any remaining changes needed
  65
  66 If you're using any of the following features in your old (v2) setup, please
  67 make the appropriate changes as indicated.
  68
  69 ### NAME rules
  70
  71 `NAME/` rules must be changed to `VREF/NAME/`.  Also, fallthru on all VREFs is
  72 "success" now, so any `NAME/` rules you have **MUST** change the rule list in
  73 some way to maintain the same restrictions.  The simplest is to add the
  74 following line to the end of each repo's rule list:
  75
  76     -   VREF/NAME/       =   @all
  77
  78 ### `subconf` command
  79
  80 (This is also affected by the previous issue, 'NAME rules'; please read that
  81 as well).
  82
  83 If you're using delegation in your admin conf setup, please add the following
  84 lines to the end of the gitolite-admin rules in your conf/gitolite.conf file:
  85
  86     repo gitolite-admin
  87         -   VREF/NAME/       =   @all
  88
  89     subconf "fragments/*.conf"
  90
  91 The first part compensates for fallthru now being a success when processing
  92 [VREF](vref) rules (NAME rules are just one specific VREF).  Although,
  93 **ideally**, you should change your rule list so that you no longer require
  94 that line.
  95
  96 The second part explicitly says when and where to include the subconf files.
  97 (Before subconf was invented, this used to happen implicitly at the end of the
  98 main conf file, and was hardcoded to that specific glob.)
  99
 100 ### mirroring
 101
 102 <!-- duplicated in mirroring.mkd with minor differences -->
 103
 104 There are **several** important differences in mirroring; if you're using
 105 mirroring **please start from a clean slate on all copies**, using the v3
 106 documentation on [mirroring](mirroring).
 107
 108 If you're not willing to do that, you may be able to use the older, more
 109 detailed, documentation [here][arch] to manage the migration.  However, I
 110 cannot support that (mainly due to lack of time).
 111
 112 ### rc file settings
 113
 114 Many rc file settings have been dropped.  You should be able to get by without
 115 most of them, but some of them cause a significant change to behaviour:
 116
 117 *   `GL_ALL_INCLUDES_SPECIAL`: @all always includes gitweb and daemon now.
 118     Use deny-rules if you want to say `R = @all` but not have the repo(s) be
 119     visible to gitweb or daemon.
 120
 121 *   `GL_NO_DAEMON_NO_GITWEB`: the default will clobber your projects.list file
 122     and git-daemon-export-ok files.
 123
 124     Comment out the 'daemon' and 'gitweb' lines in the ENABLE list in the rc
 125     file.  Gitweb and daemon can now be separately disabled, instead of both
 126     being tied to the same setting.
 127
 128 *   `GL_NO_SETUP_AUTHKEYS`:  default will clobber your authkeys file.
 129
 130     Comment out all the line(s) that call ssh-authkeys in the rc file.
 131
 132 *   `ADMIN_POST_UPDATE_CHAINS_TO` and `UPDATE_CHAINS_TO`:
 133
 134     For the former, add your script to the `POST_COMPILE` [trigger](triggers)
 135     chain.  For the latter, use a [vref](vref).  Don't forget to add a rule that
 136     references the new VREF!
 137
 138 ### wild repos
 139
 140 *   `gl-creater` files: these files need to be renamed to `gl-creator` (the
 141     correct spelling at last, hooray!).  Suggested command sequence:
 142
 143     ```sh
 144     cd $HOME/repositories
 145     find . -type d -name "*.git" -prune | while read r
 146     do
 147         mv $r/gl-creater $r/gl-creator
 148     done 2>/dev/null
 149     ```
 150
 151 *   `gl-perms` files: setting perms of R and RW will no longer work; you have
 152     to say READERS and WRITERS now.  Suggested command:
 153
 154     ```sh
 155     find \`gitolite query-rc GL_REPO_BASE\` -name gl-perms |
 156         xargs perl -pi -e 's/\bR\b/READERS/;s/\bRW\b/WRITERS/'
 157     ```
 158