gitolite/doc/install.mkd

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.

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.

Notes:

• Any unix user can be a hosting user.
• Which also means you can have several hosting users on the same machine.
• The URLs used will be of the form git@host:reponame (or its longer equivalent starting with ssh://). The .git at the end is optional. I recommend you leave it out, so your reponames are consistent with what the conf file uses.

#req requirements

your skills

• If you're installing gitolite, you're a "system admin", like it or not. Ssh is therefore a necessary skill. Please take the time to learn at least enough to get passwordless access working.

• You also need to be somewhat familiar with git itself. You cannot administer a whole bunch of git repositories if you don't know the basics of git.

• Some familiarity with Unix and shells is probably required.

• Regular expressions are a big part of gitolite in many places but familiarity is not necessary to do basic access control.

server

• any Unix system with a posix compatible "sh".
• git version 1.6.6 or later
• perl 5.8.8 or later
• openssh (almost any version). Optional if you're using [smart http][http]
• a dedicated Unix userid to be the hosting user, usually "git" but it can be any user, even your own normal one. (If you're using an RPM/DEB the install probably created one called "gitolite").

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

client

• openssh client
• git 1.6.6 or later. Almost any git client will work, as long as it knows how to use ssh keys and send the right one along.

getting the software

git clone -b g3 git://github.com/sitaramc/gitolite

The -b g3' is needed until g3 becomes "master". Current estimates put this around June 2012, when the old gitolite (upto v2.x) will be retired and supported only for security issues.

the actual install

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 -b g3 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, or use a specific directory:
gitolite/install -ln /usr/local/bin

# option 3
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

• Update your clone of the gitolite source.
• Repeat the install command you used earlier (make sure you use the same arguments as before).
• Run gitolite setup.

packaging gitolite

Here are the requirements for gitolite:

• The programs gitolite and gitolite-shell, and the directories commands, lib, syntactic-sugar, triggers, and VREF must all be in the same directory.

  It doesn't matter what this directory is. As an example, Fedora keeps git's 150 executables in /usr/libexec/git-core, so /usr/libexec/gitolite may be a good choice; it's upto you.

  The rest of this section will assume you chose /usr/libexec/gitolite as the location. Adjust as needed.

• The program /usr/libexec/gitolite/gitolite must then be symlinked to some directory in the PATH. Do not copy it; it must be a symlink.

• The Gitolite subdirectory in /usr/libexec/gitolite/lib can stay there, OR, if your distro policies don't allow that, can be put in any directory in perl's @INC path (such as /usr/share/perl5/vendor_perl).

• Finally, a file called /usr/libexec/gitolite/VERSION must contain a suitable version string.

#migr migrating

If you're migrating from gitosis, [this][gsmigr] is what you want to start with.

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

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

migration

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. Carefully wipe out the old gitolite

   • the code

     • delete or move away all the old gitolite scripts. Check the path to the gl-auth-command in ~/.ssh/authorized_keys if you forgot where you put them.

     • delete or move away the two directories named in the two variables GL_PACKAGE_CONF and GL_PACKAGE_HOOKS in ~/.gitolite.rc

   • the rc file

     • rename ~/.gitolite.rc to something else

   • the admin repo

     • clone ~/repositories/gitolite-admin.git to someplace safe
     • then delete ~/repositories/gitolite-admin.git

     (make sure you do not delete any other repos!)

   • the admin directory

     • if you need to preserve logs, move the ~/.gitolite/logs` directory somewhere else

     • if you added any custom hooks and wish to preserve them, move the ~/.gitolite/hooks` directory somewhere else

     • delete ~/.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][].

4. Make sure your gitolite-admin clone has the correct pubkey for the administrator in its keydir directory, then git push -f to the server 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.