http://gitolite.com/gitolite/master-toc.html

INSTALLATION AND SETUP
ADDING USERS AND REPOS
HELP FOR YOUR USERS
BASIC SYNTAX
ACCESS RULES
GROUPS
COMMANDS
THE 'rc' FILE
GIT-CONFIG
GIT-DAEMON
GITWEB

MIGRATING FROM v2

CONTACT AND SUPPORT
LICENSE

Server requirements:

  * any unix system
  * sh
  * git 1.6.6 
  * perl 5.8.8 
  * openssh 5.0 
  * a dedicated userid to host the repos (in this document, we assume it
    is 'git'), with shell access ONLY by 'su - git' from some other userid
    on the same server.

Steps to install:

  * login as 'git' as described above

  * make sure ~/.ssh/authorized_keys is empty or non-existent

  * make sure your ssh public key from your workstation is available at
    $HOME/YourName.pub

  * run the following commands:

        git clone git://github.com/sitaramc/gitolite
        mkdir -p $HOME/bin
        gitolite/install -to $HOME/bin
        gitolite setup -pk YourName.pub

    If the last command doesn't run perhaps 'bin' in not in your 'PATH'.
    You can either add it, or just run:

        $HOME/bin/gitolite setup -pk YourName.pub

Do NOT add new repos or users manually on the server.  Gitolite users,
repos, and access rules are maintained by making changes to a special repo
called 'gitolite-admin' and pushing those changes to the server.

----

To administer your gitolite installation, start by doing this on your
workstation (if you have not already done so):

    git clone git@host:gitolite-admin

**NOTE**: if you are asked for a password, something has gone wrong.

Now if you 'cd gitolite-admin', you will see two subdirectories in it:
'conf' and 'keydir'.

To add new users alice, bob, and carol, obtain their public keys and add
them to 'keydir' as alice.pub, bob.pub, and carol.pub respectively.

To add a new repo 'foo' and give different levels of access to these
users, edit the file 'conf/gitolite.conf' and add lines like this:

    repo foo
        RW          =   alice
        RW          =   bob
        R           =   carol

See the 'ACCESS RULES' section later for more details.

Once you have made these changes, do something like this:

    git add conf
    git add keydir
    git commit -m 'added foo, gave access to alice, bob, carol'
    git push

When the push completes, gitolite will add the new users to
~/.ssh/authorized_keys on the server, as well as create a new, empty, repo
called 'foo'.

Once a user has sent you their public key and you have added them as
specified above and given them access, you have to tell them what URL to
access their repos at.  This is usually 'git clone git@host:reponame'; see
man git-clone for other forms.

**NOTE**: again, if they are asked for a password, something is wrong.

If they need to know what repos they have access to, they just have to run
'ssh git@host info'; see 'COMMANDS' section later for more on this.

The basic syntax of the conf file is very simple.

  * Everything is space separated; there are no commas, semicolons, etc.,
    in the syntax.

  * Comments are in the usual perl/shell style.

  * User and repo names are as simple as possible; they must start with an
    alphanumeric, but after that they can also contain '.', '_', or '-'.

    Usernames can optionally be followed by an '@' and a domainname
    containing at least one '.'; this allows you to use an email address
    as someone's username.

    Reponames can contain '/' characters; this allows you to put your
    repos in a tree-structure for convenience.

  * There are no continuation lines.

This section is mostly 'by example'.

Gitolite's access rules are very powerful.  The simplest use was already
shown above.  Here is a slightly more detailed example:

    repo foo
        RW                      =   alice
        -   master              =   bob
        -   refs/tags/v[0-9]    =   bob
        RW                      =   bob
        RW  refs/tags/v[0-9]    =   carol
        R                       =   dave

For clones and fetches, as long as the user is listed with an R, RW
or RW  in at least one rule, he is allowed to read the repo.

For pushes, rules are processed in sequence until a rule is found
where the user, the permission (see note 1), and the refex (note 2)
*all* match.  At that point, if the permission on the matched rule
was '-', the push is denied, otherwise it is allowed.  If no rule
matches, the push is denied.

Note 1: permission matching:

  * a permission of RW matches only a fast-forward push or create
  * a permission of RW  matches any type of push
  * a permission of '-' matches any type of push

Note 2: refex matching:
(refex = optional regex to match the ref being pushed)

  * an empty refex is treated as 'refs/.*'
  * a refex that does not start with 'refs/' is prefixed with 'refs/heads/'
  * finally, a '^' is prefixed
  * the ref being pushed is matched against this resulting refex

With all that background, here's what the example rules say:

  * alice can do anything to any branch or tag -- create, push,
    delete, rewind/overwrite etc.

  * bob can create or fast-forward push any branch whose name does
    not start with 'master' and create any tag whose name does not
    start with 'v' digit.

  * carol can create tags whose names start with 'v' digit.

  * dave can clone/fetch.

Gitolite allows you to group users or repos for convenience.  Here's an
example that creates two groups of users:

    @staff      =   alice bob carol
    @interns    =   ashok

    repo secret
        RW      =   @staff

    repo foss
        RW      =   @staff
        RW      =   @interns

Group lists accumulate.  The following two lines have the same effect as
the earlier definition of @staff above:

    @staff      =   alice bob
    @staff      =   carol

You can also use group names in other group names:

    @all-devs   =   @staff @interns

Finally, @all is a special group name that is often convenient to use if
you really mean 'all repos' or 'all users'.

Users can run certain commands remotely, using ssh.  For example:

    ssh git@host help

prints a list of available commands.

The most commonly used command is 'info'.  All commands respond to a
single argument of '-h' with suitable information.

If you have shell on the server, you have a lot more commands available to
you; try running 'gitolite help'.

Some of the instructions below may require you to edit the rc file
(~/.gitolite.rc on the server).

The rc file is perl code, but you do NOT need to know perl to edit it.
Just mind the commas, use single quotes unless you know what you're doing,
and make sure the brackets and braces stay matched up.

Gitolite lets you set git-config values for individual repos without
having to log on to the server and run 'git config' commands:

    repo foo
        config hooks.mailinglist = [email protected]
        config hooks.emailprefix = '[foo] '
        config foo.bar = ''
        config foo.baz =

**WARNING**

    The last two syntaxes shown above are the *only* way to *delete*
    a config variable once you have added it.  Merely removing it from
    the conf file will *not* delete it from the repo.git/config file.

**SECURITY NOTE**

    Some git-config keys allow arbitrary code to be run on the server.

    If all of your gitolite admins already have shell access to the server
    account hosting it, you can edit the rc file (~/.gitolite.rc) on the
    server, and change the GIT_CONFIG_KEYS line to look like this:

        GIT_CONFIG_KEYS     =>  '.*',

    Otherwise, give it a space-separated list of regular expressions that
    define what git-config keys are allowed.  For example, this one allows
    only variables whose names start with 'gitweb' or with 'gc' to be
    defined:

        GIT_CONFIG_KEYS     =>  'gitweb\..* gc\..*',

Gitolite creates the 'git-daemon-export-ok' file for any repo that is
readable by a special user called 'daemon', like so:

    repo foo
        R   =   daemon

Any repo that is readable by a special user called 'gitweb' will be added
to the projects.list file.

    repo foo
        R   =   gitweb

Or you can set one or more of the following config variables instead:

    repo foo
        config gitweb.owner         =   some person's name
        config gitweb.description   =   some description
        config gitweb.category      =   some category

**NOTE**

    You will probably need to change the UMASK in the rc file from the
    default (0077) to 0027 and add whatever user your gitweb is running as
    to the 'git' group.  After that, you need to run a one-time 'chmod -R'
    on the already created files and directories.

This section describes how to migrate a basic install of v2 to v3.

However, if you have used any of the following features:

  * any non-default settings in the rc file
  * NAME/ rules
  * subconf and delegation
  * mirroring
  * wild repos (user-created repos)
  * any custom hooks of your own

you should go through the full set of migration instructions at
http://gitolite.com/gitolite/migr.html

The steps to follow to migrate a simple v2 setup to v3 are as follows:

0.  take a backup :-)

1.  remove old gitolite

    1.1 Remove (or rename)

      * the directories named in the rc variables GL_PACKAGE_CONF and
        GL_PACKAGE_HOOKS (look in ~/.gitolite.rc)

      * ~/.gitolite.rc

      * the gitolite v2 code, whose location you can find in the
        "command=" parameter in any of the gitolite keys in
        ~/.ssh/authorized_keys

      * ~/.gitolite (preserve ~/.gitolite/logs if you wish)

    1.2 Edit ~/.ssh/authorized_keys and delete all lines pertaining to
        gitolite (they will have a "command=" option pointing to
        gl-auth-command)

    1.3 Clone ~/repositories/gitolite-admin.git to some safe location on
        the same server.

        NOTE: please clone using the file system directly, not via ssh.

    1.4 Delete ~/repositories/gitolite-admin.git (the repo you just
        cloned).

        NOTE: DO NOT delete any other repo in ~/repositories.  Leave them
        all as they are.

2.  install gitolite as normal.  It doesn't matter what pubkey you use in
    the "gitolite setup" step; in fact you may even choose to just run
    "gitolite setup -a admin".  The admin repo created in this step will
    get wiped out in the next step anyway.

3.  go to the clone you made in step 1.3 and run 'gitolite push -f'.

    NOTE: that is 'gitolite push -f', not 'git push -f' :-)

Mailing list for support and general discussion:
    [email protected]
    subscribe address: gitolite [email protected]

Mailing list for announcements and notices:
    subscribe address: gitolite-announce [email protected]

IRC: #git and #gitolite on freenode.  Note that I live in India (UTC 0530
time zone).

Author: [email protected], but please DO NOT use this for general support
questions.  Subscribe to the list and ask there instead.

The gitolite *code* is released under GPL v2.  See COPYING for details.

This documentation, which is part of the source code repository, is
provided under a Creative Commons Attribution-ShareAlike 3.0 Unported
License -- see http://creativecommons.org/licenses/by-sa/3.0/