installing gitolite

NOTE: if you're migrating from g2, there are some settings that MUST be dealt with before running gitolite setup; please start [here][migr]. RTFM is mandatory for migrations.


This is the first step in using gitolite, and happens on the server. It is followed by [setup][], then [clone][].


[[TOC]]


notes and naming conventions

Gitolite uses a single "real" (i.e., unix) user to provide secure access to git repos to any number of "virtual" users, without giving them a shell.

The real user used is called the hosting user. Typically this user is git, and that is what we will use throughout the documentation. However RPMs and DEBs create a user called gitolite for this, so adjust instructions and examples accordingly.

Unless otherwise stated, everything in this page is to be done by logging in as this "hosting user".

Notes:

#req requirements

your skills

server

Also see the [WARNINGS][] page for more on what gitolite expects on the server side.

client

getting the software

git clone git://github.com/sitaramc/gitolite

the actual install

Note: This section describes installing an ssh-based setup. For smart http setup click [here][http].

Gitolite has only one server side "command" now, much like git itself. This command is gitolite. You don't need to place it anywhere special; worst case you run it with the full path.

"Installation" consists of the following options:

  1. Keep the sources anywhere and use the full path to run the gitolite command.
  2. Keep the sources anywhere and symlink just the gitolite program to some directory on your $PATH.
  3. Copy the sources somewhere and use that path to run the gitolite command.

Option 2 is the best for general use.

There is a program called 'install' that helps you do these easily. Assuming your cloned the repo like this:

git clone git://github.com/sitaramc/gitolite

you can run the 'install' command in 3 different ways:

# option 1
gitolite/install

# option 2
gitolite/install -ln
# defaults to $HOME/bin (which is assumed to exist)
#   ** or **
# or use a specific directory (please supply full path):
gitolite/install -ln /usr/local/bin

# option 3
# (again, please supply a full path)
gitolite/install -to /usr/local/gitolite/bin

Creating a symlink doesn't need a separate program but 'install' also runs git describe to create a VERSION file, which, trust me, is important!

Next step: run [setup][setup].

upgrading

#package packaging gitolite

Gitolite has broad similarities to git in terms of packaging requirements.

With that said, here's one way to package gitolite:

#migr migrating

This section is about migrating from older gitolite to "g3". If you're migrating from gitosis, see [here][gsmigr].

First things first: g2 will be supported for a good long time for critical bugs, although enhancements and new features won't happen.

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

pre-migration checks

  1. Check the [dev-status][] page to make sure all the features you want have been implemented in g3.

  2. Read the [g2 migration][g2migr] page to see what changes affect you and your users, and how much time it might take you to migrate. (The closer 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.

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

  1. Carefully wipe out the old gitolite:

  2. Read about [presetting][rc-preset] the rc file; if you're using any variables listed as requiring preset, follow those instructions to create your new rc file.

  3. Install gitolite g3; see [quick install and setup][qi] or [install][] 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 -f][bypass] to overwrite the "default" admin repo created by the install.

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