265 lines
9.2 KiB
Markdown
265 lines
9.2 KiB
Markdown
# installing gitolite
|
|
|
|
<font color="red">**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.</font>
|
|
|
|
----
|
|
|
|
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:
|
|
|
|
* 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 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
|
|
|
|
* 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`.
|
|
|
|
## #package packaging gitolite
|
|
|
|
Gitolite has broad similarities to git in terms of packaging requirements.
|
|
|
|
* Git has 150 executables to marshal and put somewhere. Gitolite has the
|
|
directories `commands`, `lib`, `syntactic-sugar`, `triggers`, and `VREF`.
|
|
|
|
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, and that this location contains the 5 directories named
|
|
above*.
|
|
|
|
* Git has the `GIT_EXEC_PATH` env var to point to this directory. Gitolite
|
|
has `GL_BINDIR`. However, in git, the "make" process embeds a suitable
|
|
default into the binary, making the env var optional.
|
|
|
|
With that said, here's one way to package gitolite:
|
|
|
|
* Put the two executables (gitolite and gitolite-shell) somewhere in PATH.
|
|
Then change the 2 assignments to `$ENV{GL_BINDIR}`, one in 'gitolite', one
|
|
in 'gitolite-shell', to "/usr/libexec/gitolite".
|
|
|
|
This is equivalent to "make" embedding the exec-path into the executable.
|
|
|
|
**OR**
|
|
|
|
Put the two executables `gitolite` and `gitolite-shell` also into
|
|
/usr/libexec/gitolite (i.e., as siblings to the 5 directories mentioned
|
|
above). Then *symlink* `/usr/libexec/gitolite/gitolite` to some directory
|
|
in the PATH. Do not *copy* it; it must be a symlink.
|
|
|
|
Gitolite will find the exec-path by following the symlink.
|
|
|
|
* The `Gitolite` subdirectory in `/usr/libexec/gitolite/lib` can stay right
|
|
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
|
|
|
|
<font color="gray">This section is about migrating from older gitolite to
|
|
"g3". If you're migrating from gitosis, see [here][gsmigr].</font>
|
|
|
|
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:
|
|
|
|
* 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][]. 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.
|