gitolite/doc/2-admin.mkd

# administering and running gitolite

*Note*: some of the paths in this document use variable names.  Just refer to
`~/.gitolite.rc` for the correct values for *your* installation.

In this document:

  * <a href="#please_read_this_first">please read this first</a>
  * <a href="#adding_users_and_repos">adding users and repos</a>
  * <a href="#other_features">other features</a>
      * <a href="#moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
      * <a href="#specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
      * <a href="#custom_hooks">custom hooks</a>
      * <a href="#hook_chaining">hook chaining</a>
      * <a href="#environment_variables_available_to_hooks">environment variables available to hooks</a>
      * <a href="#custom_git_config">custom git config</a>

----

<a name="please_read_this_first"></a>

### please read this first

  * ***do NOT add new repos manually***, unless you know how to add the
    required hook as well.  Without the hook, branch-level access control will
    not work for that repo, which sorta defeats the idea of using gitolite :-)

  * most normal (day-to-day) gitolite admin work is done by cloning the
    gitolite-admin repo from the server to your workstation, making changes to
    the clone, and pushing those changes back.  The installation steps in
    [doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed.

Once you've cloned it, you're ready to add users and repos.

<a name="adding_users_and_repos"></a>

### adding users and repos

  * ask each user who will get access to send you a public key.  See other
    sources (for example [here][genpub]) for how to do this

  * rename each public key according to the user's name, with a `.pub`
    extension, like `sitaram.pub` or `john-smith.pub`.  You can also use
    periods and underscores

  * copy all these `*.pub` files to `keydir` in your gitolite-admin repo
    clone.  You can also organise them into various subdirectories of `keydir`
    if you wish, since the entire tree is searched.

  * edit the config file (`conf/gitolite.conf` in your admin repo clone).  See
    `conf/example.conf` in the gitolite source for details on what goes in
    that file, syntax, etc.  Just add new repos as needed, and add new users
    and give them permissions as required.  The users names should be exactly
    the same as their keyfile names, but without the `.pub` extension

  * when done, commit your changes and push.  Any new repos you specified will
    automatically be created (empty, but clonable) and users' access will be
    updated as needed.

<a name="other_features"></a>

### other features

<a name="moving_pre_existing_repos_into_gitolite"></a>

#### moving pre-existing repos into gitolite

One simple way to add a pre-existing repo to gitolite is to let gitolite
create it as a brand new repo as in the previous section, then do the
following:

    cd your-copy-of-the-repo
    # make sure all the branches are correct and no extra stuff, "temp"
    # branches, etc., are present
    git push --all git@server:reponame
    git push --tags git@server:reponame

(You could also use "git push --mirror" instead of separately doing branches
and tags, but that will carry across *your* remote refs also, and typically
you may not want that.  Anyway please do a `git ls-remote git@server:repo` to
make sure all the stuff you want went through, and is named correctly).

All this is actually very simple and easily done.  However, if you have many
existing repos to add, this can be time-consuming and error-prone.  Here's how
to take a bunch of existing repos and add them to gitolite:

  * make sure they're *bare* repos ;-)

  * log on to the server and copy the repos to `$REPO_BASE` (which defaults to
    `~/repositories`), making sure that the directory names end in ".git".

  * back on your workstation, add each repo (without the `.git` suffix) to
    `conf/gitolite.conf` in your gitolite-admin repo clone.  Then add, commit,
    push.

<a name="specifying_gitweb_and_daemon_access"></a>

#### specifying gitweb and daemon access

This is a feature that I personally do not use (corporate environments don't
like unauthenticated access of any kind to any repo!), but someone wanted it,
so here goes.

To make a repo or repo group accessible via "git daemon", just give read
permission to the special user "daemon".  See the [faq, tips, etc][ss]
document for easy ways to specify access for multiple repositories.

[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd

There's a special user called "gitweb" also, which works the same way.
However, setting a description for the project also enables gitweb permissions
so you may as well use that method and kill two birds with one stone, like so:

    gitolite = "fast, secure, access control for git in a corporate environment"

You can also specify an owner for gitweb to show, if you like:

    gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"

Note that gitolite does **not** install or configure gitweb/daemon -- that is
a one-time setup you must do separately.  All this does is:

  * for daemon, create the file `git-daemon-export-ok` in the repository
  * for gitweb, add the repo (plus owner name, if given) to the list of
    projects to be served by gitweb (see the config file variable
    `$PROJECTS_LIST`, which should have the same value you specified for
    `$projects_list` when setting up gitweb)
  * put the description, if given, in `$repo/description`

The "compile" script will keep these files consistent with the config settings
-- this includes removing such settings/files if you remove "read" permissions
for the special usernames or remove the description line.

<a name="custom_hooks"></a>

#### custom hooks

You can supply your own, custom, hook scripts if you wish.  Just put a
**tested** hook script in `hooks/common` of your gitolite clone (as
distributed, there are only two files there).  For each file in that
directory, a symlink pointing to it will be placed in the `hooks/`
subdirectory of every *new* repo created.

If you added any new hooks and wish to propagate them to *existing* repos as
well, just run gl-easy-install (or gl-setup, if you installed directly on the
server) once.

**VERY IMPORTANT SECURITY NOTE:  the `update` hook in `hooks/common` is what
implements all the branch-level permissions in gitolite.  If you fiddle with
the hooks directory, please make sure you do not mess with this file
accidentally, or all your fancy per-branch permissions will stop working.**

<a name="hook_chaining"></a>

#### hook chaining

Gitolite basically takes over the update hook for all repos, but some setups
really need the update hook functionality for their own purposes too.  In
order to allow this, Gitolite now exec's a hook called `update.secondary` when
it's own "update" hook is done and everything is ready to go.

You can create this `update.secondary` hook manually on selected repos on the
server, or use the mechanism in the previous section to make gitolite put it
on *all* your repos.

Similarly, gitolite also takes over the post-update hook for the special
"gitolite-admin" repo.  This hook will also chain to a `post-update.secondary`
if such a hook exists.  People wishing to do exotic things on the server side
when the admin repo is pushed should see doc/shell-games.notes for how to
exploit this :-)

Finally, these names (`update.secondary` and `post-update.secondary`) are
merely the defaults.  You can change them to anything you want; look in
conf/example.gitolite.rc for details.

<a name="environment_variables_available_to_hooks"></a>

#### environment variables available to hooks

The following environment variables are set, and may be useful for any custom
processing you wish to do in your hook code:

  * `GL_USER` -- the user doing the push
  * `GL_REPO` -- the reponame
  * `GL_REPO_BASE_ABS` -- the absolute base path where all the repos are kept

The following variables are also set, but are generally less useful:

  * `GL_BINDIR` -- where all the binaries live
  * `GL_ADMINDIR` -- common directory for many gitolite things

<a name="custom_git_config"></a>

#### custom git config

The custom hooks feature is a blunt instrument -- all repos get the hook you
specified and will run it.  In order to make it a little more fine-grained,
you could set your hooks to only work if a certain "gitconfig" variable was
set.  Which means we now need a way to specify "git config" settings on a per
repository basis.

Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this
very easily.  For security reasons, this can only be done from the master
config file (i.e., if you're using delegation, the delegated admins cannot
specify git config settings).

Please see `conf/example.conf` for syntax.  Note that this only supports the
basic forms of the "git config" command:

    git config              section.key value   # value may be an empty string
    git config --unset-all  section.key

It does not (currently) support other options like `--add`, the `value_regex`,
etc.

[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key