gitolite/doc/0-UPGRADE.mkd

# upgrading gitolite atomically

Upgrading is done **manually, on the server** (except the last step, which is
on your admin repo clone), even if you installed it using the easy install
script on the client.  First, it's not as difficult as an install so you don't
really need a script.  Second, you may have customised the "rc" file
(`~/.gitolite.rc` on the server) and I'm reluctant to mess with that in an
automated way.

### general upgrade notes

If you follow the steps below, you can make the upgrade "atomic", so you don't
have to do it at a "quiet" time or something.

1.  copy a tar file containing the new version to the server, untar it to some
    temp directory and `cd` to it

2.  *prepare* the new version of `~/.gitolite.rc`.  It **must** have **all**
    the variables defined in `conf/example.gitolite.rc` (the "new" rc file),
    because the new versions of the programs will be depending on seeing these
    variables.

    However, it must also retain any customisations you made to the **old**
    variables.

    So this is what you do:

      * make a copy of `conf/example.gitolite.rc` as `~/glrc.new`
      * if your current `~/.gitolite.rc` had any customisations (where you
        changed the defaults in some way), edit `~/glrc.new` and make those
        same changes there

3.  upgrade the rc file first

        cp ~/glrc.new ~/.gitolite.rc

4.  upgrade the software

        src/install.pl

5.  compile the config once again, in case the *internal* format of the
    compiled config file (`$GL_CONF_COMPILED`) has changed.

    To do this, you have to do a "git push" on the client side.  That might
    require a dummy change (maybe add a blank line somewhere) because
    otherwise the push will not happen.

And you're done.

### upgrade notes for specific versions

If any extra steps beyond the generic ones above are needed, they will be
listed here, newest first.

#### upgrading from 410c9ba

Between 410c9ba and this version, gitolite managed to make "push to admin" the
default for new installs, but in a much more painless way.  If you're
upgrading, you're not forced to use "push to admin", but I'd suggest you:

  * make sure you have password-less (pubkey) login to a command line on your
    server
  * save your `~/.gitolite.rc`, `keydir/*.pub` and your `conf/gitolite.conf`
    files from the server, bring them to your workstation
  * then run `src/00-easy-install.sh` on the workstation, as if it were a
    fresh install
      * when the editor pops up to edit the rc file, delete all the lines in
        it and copy them from the saved `~/.gitolite.rc`
      * at the end of the script, after the gitolite-admin repo has been
        cloned successfully, copy the saved `conf/gitolite.conf` and
        `keydir/*.pub` to the clone, then add, commit, and push

Gitolite also learnt to delegate parts of the config to other users.  See
`doc/5-delegation.mkd` for details.

#### upgrading from 8217ef9

Between 8217ef9 and this version, gitolite learnt to handle gitweb/daemon
access.  As a result, the rc file acquired a new variable, `$PROJECTS_LIST`,
which you have to set to whatever your gitweb installation requires.

#### upgrading from 86faae4

Between 86faae4 and this version, gitolite had a *major* change in the
*internal* format of the compiled config file.  Please do not omit step 5 in
the generic instructions above.

#### upgrading from 5758f69

Between 5758f69 and this version, gitolite learnt to allow "groupnames" for
repos as well.  The `conf/example.conf` has been recommented to explain the
syntax but it's really a no-brainer: what you could previously do only for
usernames, you can now do for reponames also.

#### upgrading from abb4580

Two new features (personal branches, and customisable logfile names/locations)
have been added between abb4580 and this version.

  * if you want to enable the personal branches feature, choose one of the
    alternative values given for `$PERSONAL` or change it to something you
    like; by default it is empty, which disables the feature

  * if you want the log files named or grouped differently, choose one of the
    alternative values for `$GL_LOGT`.  **Note** that if you choose to put
    them in some other directory than the default, you **must** create that
    directory (`mkdir`) yourself; gitolite will not do that for you