deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

MASSIVE set of changes to documents!

Browse source 
I got tired of being told "TL;DR".  Now the online versions of most
documents fit on a page or two, or at least most of them do.  The rest
has been split out (and you can see the links to the split out sections
right where the text is in the raw Markdown).

This is much more pleasant to read, and I've improved the linking so
it's much less effort for me to keep the links correct.
This commit is contained in:
Sitaram Chamarty 2011-11-01 10:33:20 +05:30
parent 3f87430c5a
commit 6e29365316
45 changed files with 1194 additions and 2706 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

226
README.mkd
View file

@ -1,221 +1,9 @@
# Hosting git repositories
# Gitolite README
<a name="start"></a>
If you're really impatient, and you're familiar with Unix and ssh, follow the
[quick install](http://sitaramc.github.com/gitolite/index.html#qi)
instructions.
Gitolite allows you to setup git hosting on a central server, with
fine-grained access control and many (many!) more powerful features.
----
In this document:
* <a href="#_quick_install">quick install</a>
* <a href="#_what">what</a>
* <a href="#_documentation">documentation</a>
* <a href="#_why">why</a>
* <a href="#_main_features">main features</a>
* <a href="#_security">security</a>
* <a href="#_contact_and_license">contact and license</a>
----
<a name="_quick_install"></a>
### quick install
If you're comfortable with Unix and ssh, the following steps should work.
<font color="gray">(However, gitolite has lots and lots of useful features;
don't miss out on them by skipping the excellent
[documentation][docs]!)</font>
* create a user called `git`. Login to this user.
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
* now run these commands:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
gl-setup ~/YourName.pub
You're done.
A word of caution: do **NOT** add repos or users directly on the server! You
MUST manage the server by cloning the special 'gitolite-admin' repo on your
workstation (`git clone git@server:gitolite-admin`), making changes, and
pushing them. See [here][aur] for how to add users and repos.
[aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
<a name="_what"></a>
### what
Gitolite is an access control layer on top of git. Here's an "executive
summary":
* use a single unix user ("real" user) on the server
* provide access to many gitolite users
* they are not "real" users
* they do not get shell access
* control access to many git repositories
* read access controlled at the repo level
* write access controlled at the branch/tag/file/directory level,
including who can rewind, create, and delete branches/tags
* can be installed without root access, assuming git and perl are already
installed
* authentication is most commonly done using sshd, but you can also use
httpd if you prefer (this may require root access).
* several other neat features described below and elsewhere in the
[doc/][docs] directory.
<a name="_documentation"></a>
#### documentation
Gitolite comes with a **huge** amount of documentation. Almost all of it is
for the *administrator* of a gitolite server. If you're a *user*, you only
need [this][user].
Otherwise, the suggested reading order is this:
* the README (this document) for a quick intro
* the [INSTALL][install] document
* the most common installation issues are caused by ssh. Here's how
[gitolite uses ssh][doc9gas]. And here's an [ssh trouble
shooting][doc6sts] document
* the [ADMIN][admin] document
* (if you're migrating from gitosis, read [this][migr])
There is also a **[master TOC of all gitolite documentation][docs]**; use your
browser's search function to look for likely sounding words or just browse
around -- you never know what you'll find!
[Here][who]'s some information on some of the projects and
people using gitolite (and who, in turn, have helped shape its features).
<a name="_why"></a>
### why
Gitolite is separate from git, and needs to be installed and configured. So...
why do we bother?
Gitolite is useful in any server that is going to host multiple git
repositories, each with many developers, where some sort of access control is
required.
In theory, this can be done with plain old Unix permissions: each user is a
member of one or more groups, each group "owns" one or more repositories, and
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
allow/disallow users access to repos.
But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a
killer, especially in tightly controlled environments
* adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with
* *viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually
* auditing historical permissions or permission changes is pretty much
impossible without extraneous tools
* errors or omissions in setting the permissions exactly can cause problems
of either kind: false accepts or false rejects
* without going into ACLs it is not possible to give some people read-only
access while some others have read-write access to a repo (unless you make
it world-readable). Group access just doesn't have enough granularity
* it is absolutely impossible to restrict pushing by branch name or tag
name.
Gitolite does away with all this:
* it uses ssh magic to remove the need to give actual unix userids to
developers
* it uses a simple but powerful config file format to specify access rights
* access control changes are affected by modifying this file, adding or
removing user's public keys, and "compiling" the configuration
* this also makes auditing trivial -- all the data is in one place, and
changes to the configuration are also logged, so you can audit them.
* finally, the config file allows distinguishing between read-only and
read-write access, not only at the repository level, but at the branch
level within repositories.
<a name="_main_features"></a>
### main features
The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single
reason I started *thinking* about writing gitolite.
It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
fast forward push") is potentially dangerous, but sometimes needed. So is
deleting a branch (which is really just an extreme form of rewind). I needed
something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
Here're **some more features**. All of them, and more, are documented in
detail somewhere in gitolite's [doc/][docs] subdirectory.
* simple, yet powerful, config file syntax, including specifying
gitweb/daemon access. You'll need this power if you manage lots of
users+repos+combinations of access
* apart from branch-name based restrictions, you can also restrict by
file/dir name changed (i.e., output of `git diff --name-only`)
* if your requirements are still too complex, you can split up the config
file and delegate authority over parts of it
* easy to specify gitweb owner, description and gitweb/daemon access
* easy to sync gitweb (http) authorisation with gitolite's access config
* comprehensive logging [aka: management does not think "blame" is just a
synonym for "annotate" :-)]
* "personal namespace" prefix for each dev
* migration guide and simple converter for gitosis conf file
* "exclude" (or "deny") rights at the branch/tag level
* specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking
<a name="_security"></a>
### security
Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one.
For the first person to find a security hole in it, defined as allowing a
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
that the config file says he shouldn't, and caused by a bug in *code* that is
in the "master" branch, (not in the other branches, or the configuration file
or in Unix, perl, shell, etc.)... well I can't afford 1000 USD rewards like
djb, so you'll have to settle for 5000 INR (Indian Rupees) as a "token" prize
:-)
However, there are a few optional features (which must be explicitly enabled
in the RC file) where I just haven't had the time to reason about security
thoroughly enough. Please read the comments in `conf/example.gitolite.rc` for
details, looking for the word "security".
----
<a name="_contact_and_license"></a>
### contact and license
Gitolite is released under GPL v2. See COPYING for details.
* author: sitaramc@gmail.com, sitaram@atc.tcs.com
* mailing list: gitolite@googlegroups.com
* list subscribe address : gitolite+subscribe@googlegroups.com
[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
[admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
[migr]: http://sitaramc.github.com/gitolite/doc/migrate.html
[doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
[doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
[who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
[docs]: http://sitaramc.github.com/gitolite
[user]: http://sitaramc.github.com/gitolite/doc/user-manual.html
But if you want to do anything meaningful with gitolite you have to spend some
time cuddling up to the docs. **The complete online documentation starts
[here](http://sitaramc.github.com/gitolite)**.

13
contrib/adc/README.mkd → contrib/adc/README-adc.mkd
View file

@ -1,4 +1,4 @@
## brief descriptions of the shipped ADCs (admin-defined commands)
# F=shipped_ADCs brief descriptions of the shipped ADCs (admin-defined commands)
(...with pointers to further information where needed)
@ -8,19 +8,14 @@
or other admin chores); details [here][able]. This ADC is meant only for
admins.
[able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily
**delete-branch**: allow someone to delete a branch that they themselves
created. (i.e., when the user had RWC, but not RWCD, permissions). Details on
this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd].
[dbsha]: https://github.com/sitaramc/gitolite/commit/89b68bf5ca99508caaa768c60ce910d7e0a29ccf
[rwcd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_creating_and_deleting_branches
**fork**: Think of it as a server-side clone; details [here][fork].
[fork]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_fork
**get-rights-and-owner.in-perl**: Most of the ADCs are in shell, so this is a
sample of how to write an ADC in perl.
@ -36,14 +31,10 @@ itself. This ADC displays site-local help, if the site admin enabled it.
**hub**: allow "pull requests" a la github; details [here][hub].
[hub]: http://sitaramc.github.com/gitolite/contrib/adc/hub.html
**rm**, **lock**, and **unlock**:<br>
**trash**, **list-trash**, and **restore**:
> two families of repo deletion commands; details [here][rddoc]
[rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
> two families of repo deletion commands; details [here][wild_repodel]
**sudo**: allow admin to run ADCs on behalf of a user. Useful in support
situations I guess. Details in source.

40
contrib/adc/hub.mkd
View file

@ -1,18 +1,6 @@
## the 'hub' ADC
# F=hub the 'hub' ADC
In this document:
* <a href="#_a_home_grown_hub_for_git_repos">a home grown 'hub' for git repos</a>
* <a href="#_general_syntax">general syntax</a>
* <a href="#_Bob_s_commands">Bob's commands</a>
* <a href="#_Alice_s_just_looking_commands">Alice's "just looking" commands</a>
* <a href="#_Alice_s_action_commands">Alice's "action" commands</a>
* <a href="#_what_next_">what next?</a>
* <a href="#_note_to_the_admin_configuration_variables">note to the admin: configuration variables</a>
<a name="_a_home_grown_hub_for_git_repos"></a>
### a home grown 'hub' for git repos
## a home grown 'hub' for git repos
This ADC (admin-defined command) helps collaboration among repos. The name is
in honor of github, which is the primary host for gitolite itself.
@ -51,17 +39,13 @@ do a normal `git fetch [origin]` to get it to her workstation. This has the
added advantage that other people, who may be watching her repo but not Bob's,
now get to see what Bob sent her and send comments etc.
<a name="_general_syntax"></a>
### general syntax
## general syntax
The general syntax is
ssh git@server hub <hub-command> <args>
<a name="_Bob_s_commands"></a>
#### Bob's commands
### Bob's commands
The following commands do not cause a fetch, and should be quite fast:
@ -92,9 +76,7 @@ The following commands do not cause a fetch, and should be quite fast:
ssh git@server hub request-status child [parent] request-number
<a name="_Alice_s_just_looking_commands"></a>
#### Alice's "just looking" commands
### Alice's "just looking" commands
* Alice lists requests waiting for her to check and possibly pull into
parent. For each waiting pull request, she will see a serial number, the
@ -140,9 +122,7 @@ The following commands do not cause a fetch, and should be quite fast:
to ADCs, you probably can't do things like `pu^` or `master~3`, and have
to use SHAs instead.
<a name="_Alice_s_action_commands"></a>
#### Alice's "action" commands
### Alice's "action" commands
* Alice doesn't like what she sees and decides to reject it. This command
expects some text on STDIN as the rejection message:
@ -179,9 +159,7 @@ The following commands do not cause a fetch, and should be quite fast:
Notice the sequence of Alice's action commands: it's either 'reject', or a
'fetch' then 'accept'.
<a name="_what_next_"></a>
### what next?
## what next?
At this point, you're done with the `hub` ADC. However, all this is on the
bare `parent.git` on the server, and nothing has hit Alice's workstation yet!
@ -195,9 +173,7 @@ Finally, note that Alice does not actually need to use the `fetch` subcommand.
She can do the traditional thing and fetch Bob's repo/branch directly to her
*workstation*.
<a name="_note_to_the_admin_configuration_variables"></a>
### note to the admin: configuration variables
## note to the admin: configuration variables
There are 2 configuration variables. `BASE_FETCH_URL` should be set to a
simple "read" URL (so it doesn't even have to be ssh) that almost anyone using

9
contrib/adc/repo-deletion.mkd
View file

@ -1,11 +1,8 @@
## deleting repos safely
# F=wild_repodel deleting repos safely
**NOTE**: this page is about deleting [user-created repos][wcr]. It is
**NOTE**: this page is about deleting [user-created repos][wild]. It is
**not** about deleting "normal" repos (the kind that are specified in the
gitolite.conf file itself) -- to delete those read [here][dnr].
[wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
[dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo
gitolite.conf file itself) -- to delete those read [here][repodel].
(see [this thread][thr] on the gitolite mailing list)

85
contrib/adc/sskm.mkd
View file

@ -1,38 +1,16 @@
## changing keys -- self service key management
# F=sskm changing keys -- self service key management
Follow this guide to add keys to or remove keys from your account. Note that you cannot use this method to add your *first* key to the account; you must still email your initial key to your admin.
The key management is done using an ADC (admin-defined command) called `sskm`.
In this document:
* <a href="#_Important_">Important!</a>
* <a href="#_Key_fingerprints">Key fingerprints</a>
* <a href="#_Active_keys">Active keys</a>
* <a href="#_Selecting_which_key_to_use">Selecting which key to use</a>
* <a href="#_Public_vs_private_keys">Public vs. private keys</a>
* <a href="#_Listing_your_existing_keys">Listing your existing keys</a>
* <a href="#_Adding_or_Replacing_a_key">Adding or Replacing a key</a>
* <a href="#_Step_1_Adding_the_Key">Step 1: Adding the Key</a>
* <a href="#_Step_2_Confirming_the_addition">Step 2: Confirming the addition</a>
* <a href="#_Optional_Undoing_a_mistaken_add_before_confirmation_">Optional: Undoing a mistaken add (before confirmation)</a>
* <a href="#_Removing_a_key">Removing a key</a>
* <a href="#_Step_1_Mark_the_key_for_deletion">Step 1: Mark the key for deletion</a>
* <a href="#_Step_2_Confirming_the_deletion">Step 2: Confirming the deletion</a>
* <a href="#_Optional_Undoing_a_mistaken_delete_before_confirmation_">Optional: Undoing a mistaken delete (before confirmation)</a>
* <a href="#_important_notes_for_the_admin">important notes for the admin</a>
----
<a name="_Important_"></a>
### Important!
## Important!
There are a few things that you should know before using the key management system. Please do not ignore this section!
<a name="_Key_fingerprints"></a>
#### Key fingerprints
### Key fingerprints
Keys are identified in some of these subcommands by their fingerprints. To see the fingerprint for a public key on your computer, use the following syntax:
@ -43,18 +21,13 @@ You'll get output like:
jeff@baklava ~ $ ssh-keygen -l -f .ssh/jeffskey.pub
2048 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 .ssh/jeffskey.pub (RSA)
<a name="_Active_keys"></a>
#### Active keys
### Active keys
Any keys that you can use to interact with the system are active keys. (Inactive keys are keys that are, for instance, scheduled to be added or removed.) Keys are identified with their `keyid`; see the section below on listing keys.
If you have no current active keys, you will be locked out of the system (in which case email your admin for help). Therefore, be sure that you are never removing your only active key!
<a name="_Selecting_which_key_to_use"></a>
#### Selecting which key to use
### Selecting which key to use
Although you can identify yourself to the Gitolite system with any of your active keys on the server, at times it is necessary to specifically pick which key you are identifying with. To pick the key to use, pass the `-i` flag into `ssh`:
@ -75,15 +48,11 @@ disable the agent, using one of these commands:
* If using `keychain`, run `keychain --clear` to remove identities
* Unset the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` variables in the current shell
<a name="_Public_vs_private_keys"></a>
#### Public vs. private keys
### Public vs. private keys
In this guide, all keys are using their full suffix. In other words, if you see a `.pub` at the end of a key, it's the public key; if you don't, it's the private key. For instance, when using the `-i` flag with `ssh`, you are specifying private keys to use. When you are submitting a key for addition to the system, you are using the public key.
<a name="_Listing_your_existing_keys"></a>
### Listing your existing keys
## Listing your existing keys
To see a list of your existing keys, use the `list` argument to `sskm`:
@ -103,13 +72,9 @@ use any keyid you wish when adding keys (like `@home`, `@laptop`, ...); the
only rules are that it must start with the `@` character and after that
contain only digits, letters, or underscores.
<a name="_Adding_or_Replacing_a_key"></a>
## Adding or Replacing a key
### Adding or Replacing a key
<a name="_Step_1_Adding_the_Key"></a>
#### Step 1: Adding the Key
### Step 1: Adding the Key
Adding and replacing a key is the same process. What matters is the `keyid`. When adding a new key, use a new `keyid`; when replacing a key, pass in the `keyid` of the key you want to replace, as found by using the `list` subcommand. Pretty simple!
@ -132,9 +97,7 @@ If you now run the `list` command you'll see that it's scheduled for addition:
== keys marked for addition/replacement ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Step_2_Confirming_the_addition"></a>
#### Step 2: Confirming the addition
### Step 2: Confirming the addition
Gitolite uses Git internally to store the keys. Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-add` subcommand to do this, *but*: to verify that you truly have ownership of the corresponding private key, you *must* use the key you are adding itself to do the confirmation! (Inconvenient like most security, but very necessary from a security perspective.) This is where using the `-i` flag of `ssh` comes in handy:
@ -152,9 +115,7 @@ Listing keys again shows that all four keys are now active:
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Optional_Undoing_a_mistaken_add_before_confirmation_"></a>
#### Optional: Undoing a mistaken add (before confirmation)
### Optional: Undoing a mistaken add (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly add the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to remove into the `undo-add` subcommand:
@ -171,13 +132,9 @@ Listing the keys shows that that new key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
<a name="_Removing_a_key"></a>
## Removing a key
### Removing a key
<a name="_Step_1_Mark_the_key_for_deletion"></a>
#### Step 1: Mark the key for deletion
### Step 1: Mark the key for deletion
Deleting a key works very similarly to adding a key, with `del` substituted for `add`.
@ -211,9 +168,7 @@ Listing the keys now shows that it is marked for deletion:
== keys marked for deletion ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Step_2_Confirming_the_deletion"></a>
#### Step 2: Confirming the deletion
### Step 2: Confirming the deletion
Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-del` subcommand to do this, *but*: unlike the `confirm-add` subcommand, you *must* use a *different* key than the key you are deleting to do the confirmation! This prevents you from accidentally locking yourself out of the system by removing all active keys:
@ -230,9 +185,7 @@ Listing keys again shows that the fourth key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
<a name="_Optional_Undoing_a_mistaken_delete_before_confirmation_"></a>
#### Optional: Undoing a mistaken delete (before confirmation)
### Optional: Undoing a mistaken delete (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly delete the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to keep into the `undo-del` subcommand. Note that this operation *must* be performed using the private key that corresponds to the key you are trying to keep! (Security reasons, similar to the reason that you must confirm an addition this way; it prevents anyone from undoing a deletion, and therefore keeping in the system, a key that they cannot prove (by having the corresponding private key) should stay in the system):
@ -260,9 +213,7 @@ Listing the keys shows that that new key is now marked active again:
----
<a name="_important_notes_for_the_admin"></a>
### important notes for the admin
## important notes for the admin
These are the things that can break if you enable this ADC for your users:
@ -279,10 +230,8 @@ These are the things that can break if you enable this ADC for your users:
So, if you have the same *filename* in different subdirectories of
`keydir`, you can't use this tool.
* keys placed in specific folders (perhaps to do [this][optak], or for
* keys placed in specific folders (perhaps to do [this][authkeyopt], or for
whatever other reasons), will probably not stay in those folders if this
ADC is used. Even a key delete, followed by undoing the delete, will
cause the key to effectively move to the root of the key store (i.e., the
`keydir` directory in the gitolite-admin repo).
[optak]: http://sitaramc.github.com/gitolite/doc/big-config.html#_optimising_the_authkeys_file

2
contrib/gerrit.mkd
View file

@ -1,4 +1,4 @@
## comparing gerrit and gitolite
# F=gerrit comparing gerrit and gitolite
Gerrit and gitolite have too many high level differences. Size is most
visible of course: 56000 lines of Java versus 1300 lines of perl+shell,

2
contrib/gitolite-tools.mkd
View file

@ -1,4 +1,4 @@
## gitolite-tools
# F=_gitolite_tools gitolite-tools
gitolite-tools is a collection of external git commands to work with
gitolite server and repositories:

7
contrib/ldap/README.mkd → contrib/ldap/README-ldap.mkd
View file

@ -1,20 +1,17 @@
## ldap helper programs
# F=ldap_helpers ldap helper programs
These programs were contributed by the Nokia MeeGo folks.
The first 2 are perl and shell verisions of programs meant to be used as
`$GL_GET_MEMBERSHIPS_PGM` (see [this][ldap] for more).
* ldap-query-example.pl
* ldap-query-example.sh
The third program is meant to be installed as an adc (admin-defined command,
see [here][adc]), and helps users change their LDAP passwords.
see [here][ADCs]), and helps users change their LDAP passwords.
* passwd
Enjoy!
[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_
[adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html

84
contrib/mirroring-complex-example.mkd
View file

@ -1,33 +1,9 @@
## semi-autonomous mirroring setup example
[deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
[sc]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command
# F=mirr_complex_example semi-autonomous mirroring setup example
This document describes one way to do this. Gitolite is powerful so you can
probably find other ways to suit you.
In this document:
* <a href="#_overview_of_problem">overview of problem</a>
* <a href="#_overview_of_setup">overview of setup</a>
* <a href="#_gitolite_feature_recap">gitolite feature recap</a>
* <a href="#_pre_requisites">pre-requisites</a>
* <a href="#_quick_setup">quick setup</a>
* <a href="#_step_by_step">step by step</a>
* <a href="#_1_gitolite_conf_">(1) `gitolite.conf`</a>
* <a href="#_2_master_sam_conf_">(2) `master/sam.conf`</a>
* <a href="#_3_host_admins_only_master_sam_p1_conf_">(3) host admins only -- `master/sam/p1.conf`</a>
* <a href="#_4_mirrors_sam_p1_conf_">(4) `mirrors/sam/p1.conf`</a>
* <a href="#_5_slave_frodo_sam_conf_">(5) `slave/frodo/sam.conf`</a>
* <a href="#_6_manual_sync">(6) manual sync</a>
* <a href="#_next_steps">next steps</a>
* <a href="#_appendix_A_delegation_helper_files">appendix A: delegation helper files</a>
----
<a name="_overview_of_problem"></a>
### overview of problem
## overview of problem
The example is from real life, with the following characteristics:
@ -55,9 +31,7 @@ The following can only be done by the master admins:
* mirroring setup -- who's the master and who're the slaves for any repo
* allowing redirected pushes from slaves
<a name="_overview_of_setup"></a>
### overview of setup
## overview of setup
We will use p1 as the product, with sam as the master and frodo as a slave.
Assume equivalent text/code for other product/master/slave combos.
@ -67,22 +41,18 @@ name; either a product name or, for local repos, a hostname. In our example,
these directory names would be p1 or sam on the host sam, and frodo on the
host frodo.
<a name="_gitolite_feature_recap"></a>
### gitolite feature recap
#### gitolite feature recap
We use [delegation][deldoc], to ensure that admins for sam can only write
We use [delegation][deleg], to ensure that admins for sam can only write
files whose names start with `master/sam/`. The actual files they will write
are `master/sam/p1.conf` etc., one for each product that is mastered on their
server.
We use [subconf][sc]. When you say `subconf "path/to/foo.conf`, then within
We use [subconf][]. When you say `subconf "path/to/foo.conf`, then within
that file (and anything included from it), access can only be defined for
repos that regex-match one of the elements of `@foo`.
<a name="_pre_requisites"></a>
### pre-requisites
## pre-requisites
First, install mirroring on all servers according to the main mirroring
document. Set it up so that the gitolite-admin repo is mastered at one server
@ -91,9 +61,7 @@ and everyone else slaves it.
Also, after (or during) the normal mirroring install, edit `~/.gitolite.rc` on
all servers and set `$GL_WILDREPOS` to 1 (from its default of 0).
<a name="_quick_setup"></a>
### quick setup
## quick setup
* edit your `gitolite.conf` file as given in step 1 below
* ignore all the comments, even the ones that tell you to do something :-)
@ -126,9 +94,7 @@ A typical sequence with that script is:
You can then treat the detailed steps described below as extra information or
"background reading" ;-)
<a name="_step_by_step"></a>
### step by step
## F=_mirrexsteps step by step
If the script is not cutting it for you and want to vary the technique for
some reason, or you simply want to gain a better understanding of what is
@ -139,9 +105,7 @@ script.
only place where you have to explicitly state this is in the delegation code
in the appendix. The rest of the time, "conf/" is assumed.
<a name="_1_gitolite_conf_"></a>
#### (1) `gitolite.conf`
### (1) `gitolite.conf`
The main config file has these items in it. **Please add them in this
order**.
@ -209,9 +173,7 @@ Here's what it looks like:
You'll get some warnings about missing include files; ignore them.
<a name="_2_master_sam_conf_"></a>
#### (2) `master/sam.conf`
### (2) `master/sam.conf`
For each host sam, one file called `master/sam.conf` is needed. This file
contains just one line:
@ -223,9 +185,7 @@ contains just one line:
"master/sam.conf"`. The only purpose of this is to setup the subconf
restriction on the combined contents of `master/sam/*.conf`.</font>
<a name="_3_host_admins_only_master_sam_p1_conf_"></a>
#### (3) host admins only -- `master/sam/p1.conf`
### (3) host admins only -- `master/sam/p1.conf`
(recap: the host admins for sam can only write files in `master/sam`).
@ -240,9 +200,7 @@ product.conf files.
By default, everything is local to their server. (Mirroring can only be setup
by the master admins).
<a name="_4_mirrors_sam_p1_conf_"></a>
#### (4) `mirrors/sam/p1.conf`
### (4) `mirrors/sam/p1.conf`
For each product p1 mastered on host sam, a file called `mirrors/sam/p1.conf`
will be created, containing mirror config lines for all repos of product p1.
@ -254,9 +212,7 @@ In this case, it could be
If this file does not exist, p1 is local to sam and not mirrored.
<a name="_5_slave_frodo_sam_conf_"></a>
#### (5) `slave/frodo/sam.conf`
### (5) `slave/frodo/sam.conf`
For each product that slave frodo gets from master sam, this file has the
following lines
@ -278,18 +234,14 @@ restriction of "sam"*. This is important to prevent sam's admins from writing
rules for repos they don't own and having them processed on other
servers!</font>
<a name="_6_manual_sync"></a>
#### (6) manual sync
### (6) manual sync
The new repo(s) you just created would not have been synced up to frodo. You
can either make an empty commit and push, or log on to sam and run
gl-mirror-shell request-push p1/reponame
<a name="_next_steps"></a>
### next steps
## next steps
Once you've done the initial setup, here's what ongoing additions will
require.
@ -302,9 +254,7 @@ require.
hostname in the slaves list for the admin repo (this is in the main
gitolite.conf file)
<a name="_appendix_A_delegation_helper_files"></a>
### appendix A: delegation helper files
## F=_mirrappA appendix A: delegation helper files
These two files were briefly mentioned in the delegation setup.

2
doc/monkeysphere.mkd → contrib/monkeysphere.mkd
View file

@ -1,4 +1,4 @@
## (contributed doc: integrating gitolite with monkeysphere)
# F=monkeysphere (contributed doc: integrating gitolite with monkeysphere)
This document attempts to describe one way to integrate
[Monkeysphere](http://web.monkeysphere.info/) authentication

75
contrib/putty.mkd
View file

@ -1,21 +1,4 @@
## putty and msysgit
In this document:
* <a href="#_msysgit_setup">msysgit setup</a>
* <a href="#_Going_back_to_OpenSSH">Going back to OpenSSH</a>
* <a href="#_Putty_keys">Putty keys</a>
* <a href="#_Creating_a_new_key">Creating a new key</a>
* <a href="#_Importing_an_existing_key">Importing an existing key</a>
* <a href="#_Loading_an_existing_key">Loading an existing key</a>
* <a href="#_Public_key">Public key</a>
* <a href="#_Putty_ageant">Putty ageant</a>
* <a href="#_Sessionless_or_raw_hostname_usage">Sessionless or raw hostname usage</a>
* <a href="#_Putty_sessions">Putty sessions</a>
* <a href="#_Host_key_authentication">Host key authentication</a>
* <a href="#_Debugging_multiple_putty_ageant_keys">Debugging multiple putty ageant keys</a>
* <a href="#_Setperms_and_other_commands">Setperms and other commands</a>
* <a href="#_About_this_document">About this document</a>
# F=contrib_putty putty and msysgit
This document is intended for those who wish to use Putty/Plink with msysgit.
@ -27,9 +10,7 @@ If you need more help with putty or component programs I suggest looking at [the
<a name="msysgit_setup"/>
<a name="_msysgit_setup"></a>
### msysgit setup
## msysgit setup
Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT\_SSH" to point at plink.exe, wherever you have that sitting.
@ -51,17 +32,13 @@ If instead you get a "command not found" type error you likely have a typo in yo
<a name="Going_back_to_OpenSSH"/>
<a name="_Going_back_to_OpenSSH"></a>
### Going back to OpenSSH
## Going back to OpenSSH
If you wish to go back to OpenSSH all you need to do is delete the GIT\_SSH environment variable. This will vary by your version of windows and thus is not covered here.
<a name="Putty_keys"/>
<a name="_Putty_keys"></a>
### Putty keys
## Putty keys
If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
@ -69,9 +46,7 @@ Either way, you will want to use puttygen. Note that you can go the other way if
<a name="Creating_a_new_key"/>
<a name="_Creating_a_new_key"></a>
#### Creating a new key
### Creating a new key
To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
@ -79,9 +54,7 @@ It is recommended to give the key a meaningful comment.
<a name="Importing_an_existing_key"/>
<a name="_Importing_an_existing_key"></a>
#### Importing an existing key
### Importing an existing key
If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
@ -89,41 +62,31 @@ If the key does not have a meaningful comment I would suggest adding one at this
<a name="Loading_an_existing_key"/>
<a name="_Loading_an_existing_key"></a>
#### Loading an existing key
### Loading an existing key
If you need to load an existing key to edit or view it you can do so from the File menu.
<a name="Public_key"/>
<a name="_Public_key"></a>
#### Public key
### Public key
To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH `authorized_keys` file" there. Copy the text into your preferred text editor and save.
<a name="Putty_ageant"/>
<a name="_Putty_ageant"></a>
#### Putty ageant
### Putty ageant
Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
<a name="Sessionless_or_raw_hostname_usage"/>
<a name="_Sessionless_or_raw_hostname_usage"></a>
### Sessionless or raw hostname usage
## Sessionless or raw hostname usage
When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
<a name="Putty_sessions"/>
<a name="_Putty_sessions"></a>
### Putty sessions
## Putty sessions
In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's `ssh_config` file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
@ -135,9 +98,7 @@ You can use:
<a name="Host_key_authentication"/>
<a name="_Host_key_authentication"></a>
### Host key authentication
## Host key authentication
Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
@ -204,9 +165,7 @@ In either case hit y and the key will be stored.
<a name="Debugging_multiple_putty_ageant_keys"/>
<a name="_Debugging_multiple_putty_ageant_keys"></a>
### Debugging multiple putty ageant keys
## Debugging multiple putty ageant keys
In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
@ -225,9 +184,7 @@ The first says which (numerical) key the ageant is trying. The second tells you
<a name="Setperms_and_other_commands"/>
<a name="_Setperms_and_other_commands"></a>
### Setperms and other commands
## Setperms and other commands
When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
@ -241,8 +198,6 @@ Otherwise everything should be identical.
<a name="About_this_document"/>
<a name="_About_this_document"></a>
### About this document
## About this document
This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.

31
contrib/real-users/password-access.mkd
View file

@ -1,10 +1,8 @@
# password access to gitolite
# F=password_access password access to gitolite
## (a.k.a: turning real users into gitolite users)
(a.k.a: turning real users into gitolite users)
<a name="_problems"></a>
### problems
## problems
*Problem 1*: Here's one type of problem some admins have:
@ -33,9 +31,7 @@ pesky password problem, and do not wish them to actually have shell access or
be able to do anything else on the server, don't worry -- that's easy to
handle too.</font>
<a name="_solution"></a>
### solution
## solution
Briefly, the Unix userid is made to act like a "gitolite proxy".
@ -73,17 +69,13 @@ This second connection *does* require ssh keys, but since they're all on the
server, it's scriptable and automatable so the user doesn't have to deal with
these pesky ssh keys.
<a name="_some_hints_notes_and_caveats"></a>
### some hints, notes and caveats
## some hints, notes and caveats
* This doesn't mean all your users have to be like this. You can have
normal users also. In fact, you can have users who give you a pub key
from their workstation the normal way, as well as use this method.
<a name="_what_the_2_scripts_actually_do"></a>
### what the 2 scripts actually do
## what the 2 scripts actually do
* `gl-shell` will become the new login shell for these users. This shell
will forward git clone/fetch/push requests to the gitolite server.
@ -99,12 +91,11 @@ these pesky ssh keys.
example) `alice@localhost.pub` in keydir of the admin repo, which is then
pushed.
Notice the use of [this trick][oumk] to allow Alice to allow users to have
other (gitolite normal) keys as well, such as perhaps from a laptop.
Notice the use of [this trick][oldmultikeys] to allow Alice to allow users
to have other (gitolite normal) keys as well, such as perhaps from a
laptop.
<a name="_setting_it_up"></a>
### setting it up
## setting up password access
Here's how to set this up. First, the **one-time** tasks:
@ -131,5 +122,3 @@ Now, for each user 'alice' that has her own real (unix) userid, and also needs
to access gitolite *via* her own id, run the command `gl-shell-setup alice`.
And that's really all there is to it.
[oumk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_one_user_many_keys

3
contrib/vim/README.mkd → contrib/vim/README-vim.mkd
View file

@ -1,11 +1,10 @@
## Vim Syntax Highlight
# F=_vimsyntax Vim Syntax Highlight
[Vim][] Syntax highlight for `gitolite.conf` can be found from:
- [vim.org script page][vim.org] (Releases)
- [GitHub][] (Sources)
[Vim]: http://www.vim.org/
[vim.org]: http://www.vim.org/scripts/script.php?script_id=2900
[GitHub]: http://github.com/tmatilai/gitolite.vim

12
doc/1000-words.mkd
View file

@ -1,4 +1,4 @@
# gitolite in pictures
# F=pictures gitolite in pictures
Well, they say a picture speaks a thousand words, so here're a few!
@ -9,9 +9,7 @@ had to use Unicode 2010 for it. I expect that I will have to resort to
similar tricks for colon, equals, and many others like it if and when I need
those in text within a ditaa diagram.
<a name="_installation_and_setup"></a>
### installation and setup
## installation and setup
Here's a picture showing the "non-root" install. We assume Alice is the
gitolite admin, and "git" is the hosting user on the server.
@ -56,9 +54,7 @@ Note also that you only need ONE real user on the server. In our example it
is git. In particular, you do NOT create Unix userids for your gitolite
users.
<a name="_adding_users_to_gitolite"></a>
### adding users to gitolite
## adding users to gitolite
Once you've done the install, here's how you add users.
@ -103,7 +99,7 @@ You do NOT need to add Carol or Bob as *real* (Unix) users. You do NOT add
their keys directly anywhere on the server; you do it by cloning, adding keys,
and pushing.
### adding repos to gitolite
## adding repos to gitolite
Adding a repo is even easier. It's so easy that you don't really need a
picture. OK maybe a small one:

95
doc/admin-defined-commands.mkd
View file

@ -1,29 +1,6 @@
## admin defined commands
# F=ADCs admin defined commands
----
In this document:
* <a href="#_background">background</a>
* <a href="#_details">details</a>
* <a href="#_installing_ADCs">installing ADCs</a>
* <a href="#_user_invocation">user invocation</a>
* <a href="#_checking_authorisation">checking authorisation</a>
* <a href="#_checking_arguments">checking arguments</a>
* <a href="#_passing_unchecked_arguments">passing unchecked arguments</a>
* <a href="#_fake_repos_and_access_control_for_non_git_programs">"fake" repos and access control for non-git programs</a>
* <a href="#_anatomy_of_a_command">anatomy of a command</a>
* <a href="#_example_uses_and_sample_commands_in_contrib_adc_">example uses and sample commands in `contrib/adc`</a>
* <a href="#_fork">fork</a>
* <a href="#_deleting_trashing_repos">deleting/trashing repos</a>
* <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
* <a href="#_how_this_feature_came_about">how this feature came about</a>
----
<a name="_background"></a>
### background
## ADC background
The admin-defined commands (ADCs) feature allows controlled access to
specific, "safe", programs or scripts, without giving users full shell access.
@ -36,17 +13,11 @@ but an extra pair of eyes never hurt, so please review before use.
<font color="gray">Although this is a generic way to allow pretty much any
command to be run, most of the examples and sample ADCs pertain to allowing
users to manage their "own" repos. If that's your use case, please read
[doc/wildcard-repositories.mkd][wild] before you continue here.</font>
the [wildcard repositories][wild] doc before you continue here.</font>
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
## ADC details
<a name="_details"></a>
### details
<a name="_installing_ADCs"></a>
#### installing ADCs
### installing ADCs
ADCs can only be installed by someone with shell access to the server; merely
having push rights to the admin repo is not enough.
@ -63,18 +34,14 @@ This is by design. So be careful what you name your scripts.
However, it is perfectly ok, and may even be necessary in some cases, to name
them after system executables (like 'rsync').
<a name="_user_invocation"></a>
#### user invocation
### user invocation
If you have a command called "foo" in that directory, then a user can invoke
it by saying:
ssh git@server foo argument list
<a name="_checking_authorisation"></a>
#### checking authorisation
### checking authorisation inside an ADC
Once an ADC is installed, *all* users can run it. But sometimes you want only
some people to be able to do so.
@ -87,17 +54,13 @@ repo, which is an easy way of making sure an ADC is only run by admins.
See the section on "the anatomy of a command" later for this and many more
details.
<a name="_checking_arguments"></a>
#### checking arguments
### checking arguments
Gitolite will call an ADC only if the arguments passed to it match a very
strict pattern (see `$ADC_CMD_ARGS_PATT` in `src/gitolite_rc.pm`). This
reduces the risk of various kinds of shell-meta related compromises.
<a name="_passing_unchecked_arguments"></a>
#### passing unchecked arguments
### passing unchecked arguments
Some commands need arguments with a broader range of characters than
`$ADC_CMD_ARGS_PATT` will allow. As long as you are sure those commands are
@ -107,9 +70,7 @@ arguments**.
The "ua" stand for "unchecked arguments". Consider this your last warning ;-)
<a name="_fake_repos_and_access_control_for_non_git_programs"></a>
### "fake" repos and access control for non-git programs
## "fake" repos and access control for non-git programs
A "fake" repo is a repo that exists in the config file but is specially named
(starts with "EXTCMD/") so that gitolite will not create an actual repo on
@ -126,9 +87,7 @@ server has sufficient information to decide. Protocols where the command line
is just one word and everything else happens in the conversation later cannot
be helped by this mechanism.</font>
<a name="_anatomy_of_a_command"></a>
### anatomy of a command
## anatomy of a command
You can do whatever you want in an ADC! It's upto you to check the
permissions of *each* repo that the user is manipulating using your ADC --
@ -176,13 +135,9 @@ convenient. See any of the other samples for how to use it.
If you prefer perl, there is a nicely commented example in
`contrib/adc/get-rights-and-owner.in-perl`.
<a name="_example_uses_and_sample_commands_in_contrib_adc_"></a>
## example uses and sample commands in `contrib/adc`
### example uses and sample commands in `contrib/adc`
<a name="_fork"></a>
#### fork
### #fork the 'fork' ADC
A user would use the fork command like this:
@ -206,19 +161,11 @@ the client side:
or some such incantation.
<a name="rmrepo"></a>
### deleting/trashing repos
<a name="_deleting_trashing_repos"></a>
See the [repo-deletion document][wild_repodel] for details about this.
#### deleting/trashing repos
See the [repo-deletion document][rdR] for details about this.
[rdR]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
<a name="_enable_disable_push_access_temporarily"></a>
#### enable/disable push access temporarily
### #able enable/disable push access temporarily
If you want to disable push access to gitolite temporarily (maybe for
maintenance), anyone with write access to the gitolite-admin repo can do this:
@ -233,15 +180,9 @@ You can also do this for one or more individual repos; in place of `@all`,
just use a space separated list of reponames (exactly as they would appear in
the config file). Wildcards are not supported; patches welcome ;-)
Note: please see [this][diswr] for more on this.
Note: please see [this][disable] for more on this.
[diswr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
----
<a name="_how_this_feature_came_about"></a>
### how this feature came about
## how the ADC feature came about
<font color="gray">

204
doc/2-admin.mkd → doc/admin.mkd
View file

@ -1,26 +1,6 @@
# administering and running gitolite
# F=admin administering and running gitolite
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="#_using_hooks">using hooks</a>
* <a href="#_custom_hooks">custom hooks</a>
* <a href="#_gl_post_init_hook">"gl-post-init" hook</a>
* <a href="#_gl_pre_git_hook">"gl-pre-git" hook</a>
* <a href="#_hook_chaining">hook chaining</a>
* <a href="#_environment_variables_available_to_hooks">environment variables available to hooks</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="#_moving_the_whole_thing_from_one_server_to_another">moving the whole thing from one server to another</a>
* <a href="#_specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
* <a href="#_custom_git_config">custom git config</a>
----
<a name="_please_read_this_first"></a>
### please read this first
## please read this first
Unless you know what you're doing, do not do **anything** manually on the
server (except when the documentation says you should, for example to add
@ -46,9 +26,7 @@ Either way, make sure you `cd` into this clone first.
Once you've cloned it, you're ready to add users and repos.
<a name="_adding_users_and_repos"></a>
### adding users and repos
## F=add adding users and repos
Do **NOT** add repos or users directly on the server! You MUST manage the
server by cloning the special 'gitolite-admin' repo on your workstation (`git
@ -67,23 +45,20 @@ section tells you how to add users and repos.
if you wish, since the entire tree is searched.
* edit the config file (`conf/gitolite.conf` in your admin repo clone). See
[doc/gitolite.conf.mkd][confmkd] 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
the [gitolite.conf][conf] documentation 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="_using_hooks"></a>
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
### using hooks
## F=hooks using hooks
<a name="_custom_hooks"></a>
#### custom hooks
### #customhooks custom hooks
You can supply your own, custom, hook scripts if you wish. Install gitolite
as usual, then:
@ -104,37 +79,7 @@ that you had previously installed.
* Do not under any conditions put anything in `hooks/gitolite-admin` --
nothing in gitolite requires you to do anything here. Leave it alone!
<a name="_gl_post_init_hook"></a>
#### "gl-post-init" hook
Sometimes it is necessary to do something whenever a new repo is created. If
you need this functionality, just supply a hook called "gl-post-init" with
whatever code you want in it.
<a name="_gl_pre_git_hook"></a>
#### "gl-pre-git" hook
Although git has lots of nice hooks you can tap into, they all run only on a
push. There's nothing that runs on a fetch or a clone, and there's no way to
run something *before* git-receive-pack or git-upload-pack, (as the case may
be) are invoked.
That's what the `gl-pre-git` hook is for. If an executable hook called
`gl-pre-git` is present, it will be invoked with the current directory set to
`repo.git`, and with a single argument which will be either `R` or `W`
depending on what the client is trying to do. The environment variables
`GL_USER` and `GL_REPO` are available. STDOUT will be forced to STDERR before
it is called, to avoid confusing the client.
If the code returns anything other than 0, gitolite will terminate the
operation (i.e., not run git at all), just like many git hooks do, so make
sure you end with `exit 0` or equivalent.
<a name="_hook_chaining"></a>
#### hook chaining
### #hookchaining hook chaining
Sometimes you need to use git hooks for your own purposes (site-local
validations, CI integration, email notifications, or the ever popular "live
@ -183,9 +128,7 @@ 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
### 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:
@ -199,13 +142,33 @@ 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="_other_features"></a>
### "gl-post-init" hook
### other features
Sometimes it is necessary to do something whenever a new repo is created. If
you need this functionality, just supply a hook called "gl-post-init" with
whatever code you want in it.
<a name="_moving_pre_existing_repos_into_gitolite"></a>
### "gl-pre-git" hook
#### moving pre-existing repos into gitolite
Although git has lots of nice hooks you can tap into, they all run only on a
push. There's nothing that runs on a fetch or a clone, and there's no way to
run something *before* git-receive-pack or git-upload-pack, (as the case may
be) are invoked.
That's what the `gl-pre-git` hook is for. If an executable hook called
`gl-pre-git` is present, it will be invoked with the current directory set to
`repo.git`, and with a single argument which will be either `R` or `W`
depending on what the client is trying to do. The environment variables
`GL_USER` and `GL_REPO` are available. STDOUT will be forced to STDERR before
it is called, to avoid confusing the client.
If the code returns anything other than 0, gitolite will terminate the
operation (i.e., not run git at all), just like many git hooks do, so make
sure you end with `exit 0` or equivalent.
## other features
### F=moverepos moving pre-existing repos into gitolite
It's best to split this into different use cases.
@ -254,10 +217,8 @@ Assuming you can group your repo names into various patterns, and can use
similar access control lines within each such group, you can use gitolite's
"wildcard repos" feature.
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
First read [doc/wildcard-repositories.mkd][wild], or at least skim through it,
to understand the basic concept. Then do this:
First read the [wildcard repositories][wild] document, or at least skim
through it, to understand the basic concept. Then do this:
* do step 1 just like step 1 in Case 2 above
@ -294,7 +255,7 @@ to understand the basic concept. Then do this:
* what's with the `gl-creater` file in case 3?
What [doc/wildcard-repositories.mkd][wild] does not explain is how
What the [wildcard repositories][wild] document does not explain is how
ownership is *recorded* in gitolite: the `gl-creater` file contains the
owner name. If you want to "pretend" these repos were created by some
user, you need to add that in. That user then gets whatever access you
@ -313,9 +274,7 @@ In the end, it all boils down to (a) making sure the `update` hook is correct
on all repos, wild or normal, and (b) making sure `gl-creater` contains the
owner name for wild repos. The rest of the setup is in the conf file.
<a name="_moving_the_whole_thing_from_one_server_to_another"></a>
#### moving the whole thing from one server to another
### F=moveserver moving the whole thing from one server to another
[**NOTE**: I would appreciate help testing these instructions]
@ -391,83 +350,12 @@ if things are not clear -- you can help me fine tune this document :-)
And that should be that!
<a name="gwd"></a>
<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.
Gitolite has two pre-defined, "special", usernames: `daemon` and `gitweb`.
To make a repo or repo group accessible via "git daemon", just give read
permission to the special user "daemon". Similarly, give read permission to
`gitweb` to allow the gitweb CGI to show the repo. Something like this:
repo foo bar baz
R = gitweb daemon
This gives you a quick way to offer multiple repos up for gitweb and/or daemon
access.
However, **setting a description** for the project also enables gitweb
permissions so you can do it that way if you want. Of course in this case you
have to deal with each repo separately. Add lines like this to gitolite.conf:
foo = "some description"
bar = "some other description"
baz = "yet another description"
You can also **specify an owner** for gitweb to show, if you like; for example
I might use:
gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git"
These lines are standalone, so you can add them anywhere in the conf file.
Note that gitolite does **not** install or configure gitweb/git-daemon -- that
is a one-time setup you must do separately. All gitolite 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.
Please **note** that giving permissions to these special users via `@all`
(that is, using either `repo @all` or `R = @all`), will not work unless you
set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`. Also, **NOTE**
that giving them read access to `repo @all` means the `gitolite-admin` repo is
also accessible. **It is upto you to decide if that is OK in your
environment**.
<a name="_custom_git_config"></a>
#### custom git config
### 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.
specified and will run it. You can of course install hooks manually on the
server, but sometimes that's cumbersome.
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 `doc/gitolite.conf.mkd` for syntax and limitations. Also note that
this feature is disabled by default. Read the comments on a variable called
`GL_GITCONFIG_KEYS` in the rc file documentation, then set it to some
appropriate value, to enable this feature.
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
[confmkd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
Instead, you could set your hooks to only work if a certain "gitconfig"
variable was set. See [this][rsgc] for a way to specify "git config"
settings on a per repository basis.

31
doc/authentication-vs-authorisation.mkd → doc/auth.mkd
View file

@ -1,13 +1,9 @@
# authentication versus authorisation
# F=auth authentication versus authorisation
This document will explain why an "ssh issue" is almost never a "gitolite
issue", and, indirectly, why I dont get too excited about the former.
Note: for actual ssh troubleshooting see [this][glsts].
[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
----
Note: for actual ssh troubleshooting see [this][sts].
Here is a fundamental point: <font color="red">**Gitolite does not do
authentication. It only does authorisation**.</font>
@ -22,7 +18,7 @@ So first, let's loosely define these words:
> **Authorisation** is the process of asking what you want to do and
> deciding if you're allowed to do it or not.
Now, if you managed to read [doc/gitolite-and-ssh.mkd][gas], you know that
Now, if you managed to read about [gitolite and ssh][gl_ssh], you know that
gitolite is meant to be invoked as:
/full/path/to/gl-auth-command some-authenticated-gitolite-username
@ -32,26 +28,18 @@ be, and usually *isn't*, an actual *unix* username).
As you can see, authentication happens before gitolite is called.
[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
<a name="_but_but_you_have_all_that_ssh_stuff_in_there_"></a>
### but... but... you have all that ssh stuff in there!
## but... but... you have all that ssh stuff in there!
The default mode of using gitolite does use ssh keys, but all it's doing is
helping you **setup** ssh-based authentication **as a convenience to you**.
You don't have to use it, though. And many people don't. The examples I know
are [smart http][sh], and ldap-backed sshd. In both cases, gitolite has no
are [smart http][http], and ldap-backed sshd. In both cases, gitolite has no
role to play in creating users, setting up their passwords/keys, etc. There's
even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with
the authkeys file in such installations.
[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html
<a name="_so_you_re_basically_saying_you_won_t_support_X_"></a>
### so you're basically saying you won't support "X"
## so you're basically saying you won't support "X"
(where "X" is some ssh related behaviour change or feature)
@ -64,9 +52,7 @@ Even if you locked yourself (the admin) out, the docs tell you how to recover
from such errors. You do need some password based method to get a shell
command line on the server, of course.
<a name="_appendix_how_to_use_other_authentication_systems_with_gitolite"></a>
### appendix: how to use other authentication systems with gitolite
## appendix: how to use other authentication systems with gitolite
The bottom line in terms of how to invoke gitolite has been described above,
and as long as you manage to do that gitolite won't even know how the
@ -75,7 +61,7 @@ authentication scheme you want.
It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the
full command (typically starting with git-receive-pack or git-upload-pack)
that the client sent. Also, when using [smart http][sh], things are somewhat
that the client sent. Also, when using [smart http][http], things are somewhat
different: gitolite uses certain environment variables that it expects httpd
to have set up. Even the user name comes from the `REMOTE_USER` environment
variable instead of as a command line argument in this case.
@ -101,4 +87,3 @@ which can be useful.
Finally, gitolite allows you to store *group* information externally too. See
[here][ldap] for more on this.
[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_

555
doc/big-config.mkd
View file

@ -1,27 +1,22 @@
## what is a "big-config"
# F=bc what is a "big-config"
In this document:
This document is just background info; you don't actually need to read the
whole thing if you don't care. All you need to do is set `BIG_CONFIG` to 1 in
the rc file and you're done. If you have no use for gitweb and daemon, you
can save even more time by setting `GL_NO_DAEMON_NO_GITWEB`.
* <a href="#_when_why_do_we_need_it_">when/why do we need it?</a>
* <a href="#_how_do_we_use_it_">how do we use it?</a>
* <a href="#_access_rules_for_groups">access rules for groups</a>
* <a href="#_access_rules_for_individual_repos_split_config_">access rules for individual repos (split config)</a>
* <a href="#_other_optimisations">other optimisations</a>
* <a href="#_disabling_various_defaults">disabling various defaults</a>
* <a href="#_optimising_the_authkeys_file">optimising the authkeys file</a>
* <a href="#_what_are_the_downsides_">what are the downsides?</a>
* <a href="#_storing_usergroup_information_outside_gitolite_like_in_LDAP_">storing usergroup information outside gitolite (like in LDAP)</a>
* <a href="#_why">why</a>
* <a href="#_how">how</a>
* <a href="#_implementation_notes">implementation notes</a>
Finally, if you're *really* an expert (or your initials are "JK"), you can
even set `GL_NO_CREATE_REPOS` and `GL_NO_SETUP_AUTHKEYS`. However, be warned
that if you're not sufficiently clueful, those last 2 variables could have a
[security impact][rcsecurity].
<a name="_when_why_do_we_need_it_"></a>
### when/why do we need it?
## when/why do we need it?
A "big config" is anything that has a few thousand users and a few thousand
repos, resulting in a very large 'compiled' config file.
### the problem
To understand the problem, consider what happens if you have something like
this in your gitolite conf file:
@ -40,7 +35,259 @@ Without the 'big config' setting, gitolite internally translates this to:
and then generates the actual config rules once for each user-repo-ref
combination (there are 8 combinations above); the compiled config file looks
somewhat like this:
somewhat like [this][_bigno].
Of course, the output is the same whether you used groups (like `@wbr` and
`@devs` in the example above) or listed the repos directly on the 'repo'
lines.
Anyway, you can imagine what that does when you have 10,000 users and 10,000
repos. Let's just say it's not pretty :)
## how do we use it?
Just set
$GL_BIG_CONFIG = 1;
in the `~/.gitolite.rc` file on the server (see next section for more
variables). When you do that, and push this configuration, one of two things
happens.
### access rules for groups
If you used group names in the 'repo' lines (as in `repo @wbr`), then the
compiled config looks like [this][_bigyes].
That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.
### access rules for individual repos (split config)
If, on the other hand, you had the repos listed individually, (as in `repo
lynx firefox`), then the main config file would now look like this:
%repos = ();
%split_conf = (
'firefox' => 1,
'lynx' => 1
);
And each individual repo's configuration would go its own directory. For
instance, `~/repositories/lynx.git/gl-conf` would look like this:
%one_repo = (
'lynx' => {
'R' => {
'alice' => 1,
'bob' => 1
},
'W' => {
'alice' => 1,
'bob' => 1
},
'alice' => [
[
0,
'refs/heads/next',
'RW+'
],
[
4,
'refs/heads/master',
'RW'
]
],
'bob' => [
[
1,
'refs/heads/next',
'RW+'
],
[
5,
'refs/heads/master',
'RW'
]
]
}
);
That does not reduce the overall size of the repo config (because you did not
group the repos), but the main repo config is now even smaller!
## what are the downsides?
There are some downsides.
The following apply if individual ("split") conf files are written, which in
turn only happens if you used repo names instead of group names on the `repo`
lines:
* the compile (gitolite-admin push) is now slower, because it potentially
has to write a few thousand small files instead of one large one. Since
the compile should be relatively infrequent compared to developer access,
this is ok -- the main config file is parsed much faster now, so every hit
to the server will benefit.
* we can no longer distinguish 'repo not found on disk' from 'you dont have
access'. They both now look like 'you dont have access'.
## other optimisations
### disabling various defaults
The default RC file contains the following lines (we've already discussed the
first one):
$GL_BIG_CONFIG = 0;
$GL_NO_DAEMON_NO_GITWEB = 0;
$GL_NO_CREATE_REPOS = 0;
$GL_NO_SETUP_AUTHKEYS = 0;
`GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
if you *do* have a large number of repositories, and do *not* use gitolite's
support for gitweb or git-daemon access (see "[this][gwd]" for details). This will save a
lot of time when you push the gitolite-admin repo with changes. This variable
also controls whether "git config" lines (such as `config hooks.emailprefix =
"[gitolite]"`) will be processed or not.
You should be a lot more careful with `GL_NO_CREATE_REPOS` and
`GL_NO_SETUP_AUTHKEYS`. These are meant for installations where some backend
system already exists that does all the actual repo creation, (including
setting up the proper hooks -- very important for access control), and all the
authentication setup (ssh auth keys), respectively.
Summary: Please **leave those two variables alone** unless you're initials are
"JK" ;-)
### #authkeyopt optimising the authkeys file
Sshd does a linear scan of the `~/.ssh/authorized_keys` file when an incoming
connection shows up. This means that keys found near the top get served
faster than keys near the bottom. On my laptop, it takes about 2500 keys
before I notice the delay; on a typical server it could be double that, so
don't worry about all this unless your user-count is in that range.
One way to deal with 5000+ keys is to use customised, database-backed ssh
daemons, but many people are uncomfortable with taking non-standard versions
of such a critical piece of the security infrastructure. In addition, most
distributions do not make it painless to use them.
So what do you do?
The following trick uses the Pareto principle (a.k.a the "80-20 rule")
to get an immediate boost in response for the most frequent or prolific
developers. It can allow you to ignore the problem until the next big
increase in your user counts!
Here's how:
* create subdirectories of keydir/ called 0, 1, (maybe 2, 3, etc., also),
and 9.
* in 0/, put in the pubkeys of the most frequent users
* in 1/, add the next most important set of users, and so on for 2, 3, etc.
* finally, put all the rest in 9/
Make sure "9" contains at least 70-90% of the total number of pubkeys,
otherwise this doesn't really help.
You can easily determine who your top users are by runnning something like
this (note the clever date command that always gets you last months log file!)
cat .gitolite/logs/gitolite-`date +%Y-%m -d -30days`.log |
cut -f2 | sort | uniq -c | sort -n -r
## F=ldap storing usergroup information outside gitolite (like in LDAP)
[Please NOTE: this is all about *user* groups, not *repo* groups]
[WARNING: the earlier method of doing this has been discontinued; please see
the commit message for details]
Gitolite now allows usergroup information to be stored outside its own config
file. We'll see "why" first, then the "how".
### #_ldapwhy why
Large sites often have LDAP servers that already contain user and group
information, including group membership details. Such sites may prefer that
gitolite just pick up that info instead of having to redundantly put it in
gitolite's config file.
Consider this example config for one repo:
repo foo
RW+ = @lead_devs
RW = @devs
R = @interns
Normally, you would also need to specify:
@lead_devs = dilbert alice
@devs = wally
@interns = ashok
However, if the corporate LDAP server already tags these people correctly, and
if there is some way of getting that information out **at run time**, that
would be cool.
### #_ldaphow how
All you need is a script that, given a username, queries your LDAP or similar
server, and returns a space-separated list of all the groups she is a member
of. If an invalid user name is sent in, or the user is valid but is not part
of any groups, it should print nothing.
This script will probably be specific to your site. (See contrib/ldap for some
example scripts that were contributed by the Nokia MeeGo team.)
Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
path of this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
## implementation notes
To understand how big-config works (at least when you're using grouped repos),
we'll first look at how it works without this setting. Think back to the
example at the top, and assume 'alice' is accessing the 'lynx' repo. The
various rights are governed by the following hash elements:
# for the first level checks
$repos{'lynx'}{'R'}{'alice'} = 1
$repos{'lynx'}{'W'}{'alice'} = 1
# for the second level checks
$repos{'lynx'}{'alice'}{'refs/heads/master'} = 'RW';
$repos{'lynx'}{'alice'}{'refs/heads/next'} = 'RW+';
Those elements are explicitly specified in the compiled hash, as you can see
(you don't need to know perl too much to read a hash; just make some educated
guesses if needed!)
Now look at the compiled hash produced when `GL_BIG_CONFIG` is set. In place
of both 'firefox' and 'lynx' you have '@wbr', and similarly '@devs' for both
'alice' and 'bob'. In addition, there is a group hash at the bottom that
lists each group and its members.
When 'alice' tries to access the 'lynx' repo, gitolite collects all the group
names that these names belong to, so '@devs' is added to the list of 'user'
names that 'alice' inherits permissions from, and '@wbr' is added to the list
of 'repo' names that 'lynx' inherits from. This means that the final access
inherits all permissions pertaining to the following combinations:
alice, lynx
alice, @wbr
@devs, lynx
@devs, @wbr
(Actually there are 3 more... try and guess what they may be!)
Anyway, all ACL rules for these combinations are clubbed together to make the
composite set of rules that 'alice' accessing 'lynx' is subject to.
## config listings
### F=_bigno compiled config with big-config disabled
%repos = (
'firefox' => {
@ -115,31 +362,7 @@ somewhat like this:
Phew!
Of course, the output is the same whether you used groups (like `@wbr` and
`@devs` in the example above) or listed the repos directly on the 'repo'
lines.
Anyway, you can imagine what that does when you have 10,000 users and 10,000
repos. Let's just say it's not pretty :)
<a name="_how_do_we_use_it_"></a>
### how do we use it?
Just set
$GL_BIG_CONFIG = 1;
in the `~/.gitolite.rc` file on the server (see next section for more
variables). When you do that, and push this configuration, one of two things
happens.
<a name="_access_rules_for_groups"></a>
#### access rules for groups
If you used group names in the 'repo' lines (as in `repo @wbr`), then the
compiled config looks like this:
### F=_bigyes compiled config with big-config enabled
%repos = (
'@wbr' => {
@ -173,249 +396,3 @@ compiled config looks like this:
'lynx' => 'master'
}
);
That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.
<a name="_access_rules_for_individual_repos_split_config_"></a>
#### access rules for individual repos (split config)
If, on the other hand, you had the repos listed individually, (as in `repo
lynx firefox`), then the main config file would now look like this:
%repos = ();
%split_conf = (
'firefox' => 1,
'lynx' => 1
);
And each individual repo's configuration would go its own directory. For
instance, `~/repositories/lynx.git/gl-conf` would look like this:
%one_repo = (
'lynx' => {
'R' => {
'alice' => 1,
'bob' => 1
},
'W' => {
'alice' => 1,
'bob' => 1
},
'alice' => [
[
0,
'refs/heads/next',
'RW+'
],
[
4,
'refs/heads/master',
'RW'
]
],
'bob' => [
[
1,
'refs/heads/next',
'RW+'
],
[
5,
'refs/heads/master',
'RW'
]
]
}
);
That does not reduce the overall size of the repo config (because you did not
group the repos), but the main repo config is now even smaller!
<a name="_other_optimisations"></a>
### other optimisations
<a name="_disabling_various_defaults"></a>
#### disabling various defaults
The default RC file contains the following lines (we've already discussed the
first one):
$GL_BIG_CONFIG = 0;
$GL_NO_DAEMON_NO_GITWEB = 0;
$GL_NO_CREATE_REPOS = 0;
$GL_NO_SETUP_AUTHKEYS = 0;
`GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
if you *do* have a large number of repositories, and do *not* use gitolite's
support for gitweb or git-daemon access (see "[this][gwd]" for details). This will save a
lot of time when you push the gitolite-admin repo with changes. This variable
also controls whether "git config" lines (such as `config hooks.emailprefix =
"[gitolite]"`) will be processed or not.
You should be a lot more careful with `GL_NO_CREATE_REPOS` and
`GL_NO_SETUP_AUTHKEYS`. These are meant for installations where some backend
system already exists that does all the actual repo creation, (including
setting up the proper hooks -- very important for access control), and all the
authentication setup (ssh auth keys), respectively.
Summary: Please **leave those two variables alone** unless you're initials are
"JK" ;-)
<a name="_optimising_the_authkeys_file"></a>
#### optimising the authkeys file
Sshd does a linear scan of the `~/.ssh/authorized_keys` file when an incoming
connection shows up. This means that keys found near the top get served
faster than keys near the bottom. On my laptop, it takes about 2500 keys
before I notice the delay; on a typical server it could be double that, so
don't worry about all this unless your user-count is in that range.
One way to deal with 5000+ keys is to use customised, database-backed ssh
daemons, but many people are uncomfortable with taking non-standard versions
of such a critical piece of the security infrastructure. In addition, most
distributions do not make it painless to use them.
So what do you do?
The following trick uses the Pareto principle (a.k.a the "80-20 rule")
to get an immediate boost in response for the most frequent or prolific
developers. It can allow you to ignore the problem until the next big
increase in your user counts!
Here's how:
* create subdirectories of keydir/ called 0, 1, (maybe 2, 3, etc., also),
and 9.
* in 0/, put in the pubkeys of the most frequent users
* in 1/, add the next most important set of users, and so on for 2, 3, etc.
* finally, put all the rest in 9/
Make sure "9" contains at least 70-90% of the total number of pubkeys,
otherwise this doesn't really help.
You can easily determine who your top users are by runnning something like
this (note the clever date command that always gets you last months log file!)
cat .gitolite/logs/gitolite-`date +%Y-%m -d -30days`.log |
cut -f2 | sort | uniq -c | sort -n -r
<a name="_what_are_the_downsides_"></a>
### what are the downsides?
There are some downsides.
The following apply if individual ("split") conf files are written, which in
turn only happens if you used repo names instead of group names on the `repo`
lines:
* the compile (gitolite-admin push) is now slower, because it potentially
has to write a few thousand small files instead of one large one. Since
the compile should be relatively infrequent compared to developer access,
this is ok -- the main config file is parsed much faster now, so every hit
to the server will benefit.
* we can no longer distinguish 'repo not found on disk' from 'you dont have
access'. They both now look like 'you dont have access'.
<a name="_storing_usergroup_information_outside_gitolite_like_in_LDAP_"></a>
### storing usergroup information outside gitolite (like in LDAP)
[Please NOTE: this is all about *user* groups, not *repo* groups]
[WARNING: the earlier method of doing this has been discontinued; please see
the commit message for details]
Gitolite now allows usergroup information to be stored outside its own config
file. We'll see "why" first, then the "how".
<a name="_why"></a>
#### why
Large sites often have LDAP servers that already contain user and group
information, including group membership details. Such sites may prefer that
gitolite just pick up that info instead of having to redundantly put it in
gitolite's config file.
Consider this example config for one repo:
repo foo
RW+ = @lead_devs
RW = @devs
R = @interns
Normally, you would also need to specify:
@lead_devs = dilbert alice
@devs = wally
@interns = ashok
However, if the corporate LDAP server already tags these people correctly, and
if there is some way of getting that information out **at run time**, that
would be cool.
<a name="_how"></a>
#### how
All you need is a script that, given a username, queries your LDAP or similar
server, and returns a space-separated list of all the groups she is a member
of. If an invalid user name is sent in, or the user is valid but is not part
of any groups, it should print nothing.
This script will probably be specific to your site. (See contrib/ldap for some
example scripts that were contributed by the Nokia MeeGo team.)
Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
path of this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
<a name="_implementation_notes"></a>
### implementation notes
To understand how big-config works (at least when you're using grouped repos),
we'll first look at how it works without this setting. Think back to the
example at the top, and assume 'alice' is accessing the 'lynx' repo. The
various rights are governed by the following hash elements:
# for the first level checks
$repos{'lynx'}{'R'}{'alice'} = 1
$repos{'lynx'}{'W'}{'alice'} = 1
# for the second level checks
$repos{'lynx'}{'alice'}{'refs/heads/master'} = 'RW';
$repos{'lynx'}{'alice'}{'refs/heads/next'} = 'RW+';
Those elements are explicitly specified in the compiled hash, as you can see
(you don't need to know perl too much to read a hash; just make some educated
guesses if needed!)
Now look at the compiled hash produced when `GL_BIG_CONFIG` is set. In place
of both 'firefox' and 'lynx' you have '@wbr', and similarly '@devs' for both
'alice' and 'bob'. In addition, there is a group hash at the bottom that
lists each group and its members.
When 'alice' tries to access the 'lynx' repo, gitolite collects all the group
names that these names belong to, so '@devs' is added to the list of 'user'
names that 'alice' inherits permissions from, and '@wbr' is added to the list
of 'repo' names that 'lynx' inherits from. This means that the final access
inherits all permissions pertaining to the following combinations:
alice, lynx
alice, @wbr
@devs, lynx
@devs, @wbr
(Actually there are 3 more... try and guess what they may be!)
Anyway, all ACL rules for these combinations are clubbed together to make the
composite set of rules that 'alice' accessing 'lynx' is subject to.

40
doc/delegation.mkd
View file

@ -1,20 +1,8 @@
## delegating access control responsibilities
In this document:
* <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
* <a href="#_how_to_use_delegation">how to use delegation</a>
* <a href="#_the_subconf_command">the subconf command</a>
* <a href="#_backward_compatibility">backward compatibility</a>
* <a href="#_security_notes">security notes</a>
* <a href="#_group_names">group names</a>
* <a href="#_delegating_pubkeys">delegating pubkeys</a>
# F=deleg delegating access control responsibilities
----
<a name="_lots_of_repos_lots_of_users"></a>
### lots of repos, lots of users
## lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos,
exploiting commonalities wherever possible. It lets you specify bits and
@ -39,9 +27,7 @@ for a set of repos to be specified in a **subconf** file and allow someone (a
**sub-admin**) to make changes within that file. (Note: sub-admins cannot
create or remove users).
<a name="_how_to_use_delegation"></a>
### how to use delegation
## how to use delegation
First, you group your repos however you want. In the example below, I'm
considering firefox and lynx (projects at the root of the gitolite server) as
@ -89,9 +75,7 @@ commit and push.
And that's really all there is to it.
<a name="_the_subconf_command"></a>
#### the subconf command
### #subconf the subconf command
This command is much like the "include" command, but in addition it checks
that a subconf does not contain ACL rules for repos that are outside its
@ -112,9 +96,7 @@ In more precise terms:
(Additional notes: it can also contain lines for an actual repo called
`webbrowsers`, or, in big-config mode, for a group called `@webbrowsers`).
<a name="_backward_compatibility"></a>
#### backward compatibility
### backward compatibility
For backward compatibility, if no `subconf` commands have been seen at the end
of processing the main config file, gitolite pretends you appended
@ -123,13 +105,9 @@ of processing the main config file, gitolite pretends you appended
to the end of the file.
<a name="_security_notes"></a>
## security notes
### security notes
<a name="_group_names"></a>
#### group names
### group names
You can use "@group"s defined in the main config file but do not attempt to
redefine or extend them in your own subconf file. If you must extend a group
@ -141,9 +119,7 @@ redefine or extend them in your own subconf file. If you must extend a group
Group names you define in your subconf will not clash even if the exact same
name is used in another subconf file, so you need not worry about that.
<a name="_delegating_pubkeys"></a>
#### delegating pubkeys
### delegating pubkeys
Short answer: not gonna happen.

54
doc/developer-notes.mkd
View file

@ -1,22 +1,6 @@
## developer/patch maintainer notes
# F=dev_notes developer/patch maintainer notes
In this document:
* <a href="#_general_stuff">general stuff</a>
* <a href="#_the_rc_file">the rc file</a>
* <a href="#_modules">modules</a>
* <a href="#_that_bindir_thing">that 'bindir' thing</a>
* <a href="#_from_perl">from perl</a>
* <a href="#_from_shell">from shell</a>
* <a href="#_OUTLIER_">OUTLIER!</a>
* <a href="#_special_types_of_setups">special types of setups</a>
* <a href="#_Fedora">Fedora</a>
----
<a name="_general_stuff"></a>
### general stuff
## general stuff
* all scripts and libraries must be in the same directory. However, RPM/DEB
packagers can put the libraries where they want, as long as they can be
@ -36,31 +20,23 @@ In this document:
much all of them are run via gl-auth-command or from something that was
forked from it so the variables *will* exist during normal operation.
<a name="_the_rc_file"></a>
### the rc file
## the rc file
The 'rc' file has one major change from v1: any new values in the rc file need
to be added to the @EXPORT list in `src/gitolite_rc.pm`.
<a name="_modules"></a>
### modules
## modules
There are 3 "modules" (`gitolite_rc`, `gitolite_env`, and `gitolite` itself).
Their purposes should be fairly obvious.
<a name="_that_bindir_thing"></a>
### that 'bindir' thing
## that 'bindir' thing
The importance of `GL_BINDIR` is that the command= argument in
`~/.ssh/authorized_keys` must be a full path, ideally, and the compile script
gets this from `GL_BINDIR`.
<a name="_from_perl"></a>
#### from perl
### from perl
* for frequently run perl programs, I prefer my method
@ -73,9 +49,7 @@ gets this from `GL_BINDIR`.
* gl-setup-authkeys (external shim to compile keys separately from PTA)
<a name="_from_shell"></a>
#### from shell
### from shell
* a perl program called gl-query-rc finds its own BINDIR (using my perl
method, not FindBin). This is suitable for calling from shell scripts
@ -85,22 +59,16 @@ gets this from `GL_BINDIR`.
* gl-tool
* gl-mirror-push
<a name="_OUTLIER_"></a>
#### OUTLIER!
### OUTLIER!
* gl-admin-push is an outlier. For some silly reason I have the notion that
even if it runs from /tmp it should get the right values, so it is the
only one that interrogates `~/.ssh/authorized_keys` to get the actual
BINDIR in use!
<a name="_special_types_of_setups"></a>
## special types of setups
### special types of setups
<a name="_Fedora"></a>
#### Fedora
### Fedora
Fedora has a very special setup, as follows:
@ -138,8 +106,6 @@ fails, and you now have new code trying to work with old format data.
The solution is to explicitly run a compile, from a properly privileged
userid, as soon as you do an RPM upgrade.
----
# **Why v2?**
I went onto `#perl` to ask some question about setpriority() and got yelled at

35
doc/gitolite-and-ssh.mkd
View file

@ -1,14 +1,12 @@
# how gitolite uses ssh
# F=gl_ssh how gitolite uses ssh
Although other forms of authentications exist (see
[doc/authentication-vs-authorisation.mkd][ws]), ssh is the one that most git
Although other forms of authentications exist (see the document on
[authentication versus authorisation][auth]), ssh is the one that most git
users use.
***Therefore, gitolite is (usually) heavily dependent on ssh***.
[ws]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
Most people didn't realise this, and even if they did they didn't know ssh
Most people didn't realise this, and even if they did they don't know ssh
well enough to help themselves. If you don't understand how ssh public key
authentication works, or how the `~/.ssh/authorized_keys` file can be used to
restrict users, etc., you will have endless amounts of trouble getting
@ -17,18 +15,7 @@ gitolite to work, because you'll be attacking the wrong problem.
So please please please understand this before tearing your hair out and
blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
In this document:
* <a href="#_ssh_basics">ssh basics</a>
* <a href="#_how_does_gitolite_use_all_this_ssh_magic_">how does gitolite use all this ssh magic?</a>
* <a href="#_restricting_shell_access_distinguishing_one_user_from_another">restricting shell access/distinguishing one user from another</a>
* <a href="#_restricting_branch_level_actions">restricting branch level actions</a>
----
<a name="_ssh_basics"></a>
### ssh basics
## ssh basics
Let's start with some basics, focusing *only* on the pieces relevant to
`gitolite`. If this is not detailed enough, please use google and learn more
@ -98,9 +85,7 @@ from somewhere, or maybe buy the OReilly ssh book.
**This is the backbone of what makes gitolite work; please make sure you
understand this**.
<a name="_how_does_gitolite_use_all_this_ssh_magic_"></a>
### how does gitolite use all this ssh magic?
## how does gitolite use all this ssh magic?
These are two different questions you ought to be having by now:
@ -108,9 +93,7 @@ These are two different questions you ought to be having by now:
logging in as the same remote user "git"
* how does it restrict what I can do within a repository
<a name="_restricting_shell_access_distinguishing_one_user_from_another"></a>
#### restricting shell access/distinguishing one user from another
### restricting shell access/distinguishing one user from another
The answer to the first question is the `command=` we talked about before. If
you look in the `authorized_keys` file, you'll see entries like this (I chopped
@ -141,9 +124,7 @@ at its config file, and either allows or rejects the request.
But this cannot differentiate between different branches within a repo; that
has to be done separately.
<a name="_restricting_branch_level_actions"></a>
#### restricting branch level actions
### restricting branch level actions
[If you look inside the git source tree, there's a file among the "howto"s in
there called `update-hook-example.txt`, which was the inspiration for this

78
doc/gitolite-gitweb-http-backend.mkd
View file

@ -1,30 +1,10 @@
## how to set up gitolite+gitweb+ssh+http-backend
# F=ggshb how to set up gitolite+gitweb+ssh+http-backend
In this document:
* <a href="#_NAME">NAME</a>
* <a href="#_DESCRIPTION">DESCRIPTION</a>
* <a href="#_EXAMPLE_ENVIRONMENT">EXAMPLE ENVIRONMENT</a>
* <a href="#_GITOLITE_SETUP">GITOLITE SETUP</a>
* <a href="#_gitolite_rc">gitolite.rc</a>
* <a href="#_gitolite_conf">gitolite.conf</a>
* <a href="#_APACHE_SETUP">APACHE SETUP</a>
* <a href="#_suexec">suexec</a>
* <a href="#_Gitweb">Gitweb</a>
* <a href="#_Virtual_Host">Virtual Host</a>
* <a href="#_VALIDATION">VALIDATION</a>
* <a href="#_ADDITIONAL_RESOURCES">ADDITIONAL RESOURCES</a>
* <a href="#_AUTHOR">AUTHOR</a>
<a name="_NAME"></a>
### NAME
## NAME
gitolite-gitweb-http-backend
<a name="_DESCRIPTION"></a>
### DESCRIPTION
## DESCRIPTION
You've been tasked with rolling out gitolite and git-web in your
corporate environment and your requirements are as follows:
@ -37,9 +17,7 @@ corporate environment and your requirements are as follows:
Note that these instructions are geared toward OpenSuSE 11.4. Feel
free to modify the examples below to your environment.
<a name="_EXAMPLE_ENVIRONMENT"></a>
### EXAMPLE ENVIRONMENT
## EXAMPLE ENVIRONMENT
The following assumptions are made for the purposes of example:
@ -59,19 +37,13 @@ The following assumptions are made for the purposes of example:
* engineering
* operations
<a name="_GITOLITE_SETUP"></a>
### GITOLITE SETUP
## GITOLITE SETUP
Install gitolite via your package management tools. Under OpenSuSE, this will
install repositories in `/srv/git`. Follow the instructions found [here][1in]
for initial set up.
install repositories in `/srv/git`. Follow the instructions found
[here][install] for initial set up.
[1in]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
<a name="_gitolite_rc"></a>
#### gitolite.rc
### gitolite.rc
You will need to tell gitolite.rc about some additional keys that will
be needed for each repository. Make sure the following config option
@ -83,9 +55,7 @@ These options tell gitolite to allow the user to set these values in
`gitolite.conf`, which in turn will be propagated to each
repositories git config.
<a name="_gitolite_conf"></a>
#### gitolite.conf
### gitolite.conf
For the purposes of example, we assume that we have two groups accessing each repository: engineering and operations. So, our `gitolite.conf` file will look something like this:
@ -131,17 +101,11 @@ For the purposes of example, we assume that we have two groups accessing each re
Save, commit, and push your changes to the gitolite-admin repo as
described [here][conf].
[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
<a name="_APACHE_SETUP"></a>
### APACHE SETUP
## APACHE SETUP
Under OpenSuSE 11.4, Apache runs as user `wwwrun` group `www` (see `/etc/apache2/uid.conf`). But wait! How can Apache running as `wwwrun` commit to git repositories, which are owned by `git`?
<a name="_suexec"></a>
#### suexec
### suexec
Enter SuExec. This is an apache module that allows apache to run
under the auspicious of a different user. For this to work, we need
@ -195,9 +159,7 @@ Finally, make sure Apache loads the suexec module. Under OpenSuSE,
this would mean adding "suexec" to `APACHE_MODULES` in
`/etc/sysconfig/apache2`.
<a name="_Gitweb"></a>
#### Gitweb
### Gitweb
As gitweb will now be run under the `git` user, all files must be
under `/srv/www` as well.
@ -209,9 +171,7 @@ under `/srv/www` as well.
Do not forget to point `$projectroot` in `/etc/gitweb.conf` to
`/srv/git/projects`!
<a name="_Virtual_Host"></a>
#### Virtual Host
### Virtual Host
Configure your virtual host as follows:
@ -273,9 +233,7 @@ Configure your virtual host as follows:
</VirtualHost>
<a name="_VALIDATION"></a>
### VALIDATION
## VALIDATION
Once apache has been restarted, verify your configuration:
@ -285,9 +243,7 @@ Once apache has been restarted, verify your configuration:
- Commit over ssh git@git.example.com
- Commit over http
<a name="_ADDITIONAL_RESOURCES"></a>
### ADDITIONAL RESOURCES
## ADDITIONAL RESOURCES
- [http://httpd.apache.org/docs/2.2/suexec.html](http://httpd.apache.org/docs/2.2/suexec.html) Apache suexec
documentation
@ -296,8 +252,6 @@ git-http-backend(1) documentation
- [https://git.wiki.kernel.org/index.php/Gitweb](https://git.wiki.kernel.org/index.php/Gitweb) git-web documentaiton
- [http://sitaramc.github.com/gitolite/doc/http-backend.html](http://sitaramc.github.com/gitolite/doc/http-backend.html) gitolite http backend documentation
<a name="_AUTHOR"></a>
### AUTHOR
## AUTHOR
Christopher M. Fuhrman << cfuhrman at panix dot com >>

39
doc/gitolite.conf-by-example.mkd
View file

@ -1,4 +1,4 @@
# gitolite.conf -- by example
# F=conf_examples gitolite.conf -- by example
I hate people who make statements like "I dont have time to learn". People
with that sort of attitude shouldn't use gitolite at all, and I refuse to
@ -23,15 +23,7 @@ asking me.
that "rewind" actually means any of 3 different things so I'll say it only
once. It's upto you to have read that part also.
[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
----
[[TOC]]
----
### general notes
## general notes
Git branch/tag name **recap**: branches look like refs/heads/something, tags
look like refs/tags/something. When there is no ambiguity, we leave out the
@ -48,7 +40,7 @@ not going to discuss things like what characters are allowed in a username or
reponame, how to write a comment line, how to write continuation lines (you
can't), include files, and all such *lexical* issues.
### extremely brief regex overview
## F=regexov extremely brief regex overview
Regexes are powerful. Gitolite uses that power as much as it can. If you
can't handle that power, hire someone who can and become a manager.
@ -82,7 +74,7 @@ The previous token need not be a single character; you can use parens to make
it longer. `(foo)+` matches one or more "foo", (like "foo", "foofoo",
"foofoofoo", etc.)
### basic access control
## F=exbac basic access control
repo gitolite-admin
RW+ = sitaram
@ -160,9 +152,9 @@ Ashok is allowed to push version tags. He can push any tag whose name starts
with a "v", then a digit, like "v1", "v1.0", "v2.0rc1", etc., but not "v-1",
"ver1".
### advanced access control
## F=exaac advanced access control
#### "deny" rules
### "deny" rules
**Warning**: When using deny rules, the order of your rules matters, where
earlier it did not.
@ -190,18 +182,7 @@ earlier.
before the third one, and it has a `-` as the permission, so the push
fails
#### personal branches
Personal branches exist **in a namespace** of their own. The syntax is
RW personal/USER/ = @staff
where the "personal" can be anything you like (but cannot be empty), and the
"/USER/" part is **necessary**. A user "alice" can then push any branches
inside `personal/alice/`. Which means she can push `personal/alice/foo` and
`personal/alice/bar`, but NOT `personal/alice`.
#### splitting up rules into rulesets
### #ruleaccum2 rule accumulation
Rules accumulate. Even when separated by rules for other repos. They
accumulate intuitively. For example:
@ -225,12 +206,10 @@ has the **effective** ruleset, for repo foo, of
RW dev/USER/ = @staff
RW+ tmp/ = @staff
Just remember that if you use [deny rules][dr] anywhere then the *order of the
Just remember that if you use [deny rules][deny] anywhere then the *order of the
rules matters*!
[dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
#### gitweb and daemon
### gitweb and daemon
Gitolite does NOT do anything for gitweb and daemon access **except**

301
doc/gitolite.conf.mkd
View file

@ -1,29 +1,4 @@
# the access control file `gitolite.conf`
In this document:
* <a href="#_syntax">syntax</a>
* <a href="#_continuation_lines">continuation lines</a>
* <a href="#_include_files">include files</a>
* <a href="#_basic_access_control">basic access control</a>
* <a href="#_how_rules_are_matched">how rules are matched</a>
* <a href="#_branches_tags_and_specifying_refex_es">branches, tags, and specifying "refex"es</a>
* <a href="#_groups">groups</a>
* <a href="#_the_special_all_group">the special `@all` group</a>
* <a href="#_advanced_access_control">advanced access control</a>
* <a href="#_creating_and_deleting_branches">creating and deleting branches</a>
* <a href="#_deny_rules">"deny" rules</a>
* <a href="#_warnings_and_required_reading">warnings and required reading</a>
* <a href="#_deny_rules_for_refs_in_a_repo">"deny" rules for refs in a repo</a>
* <a href="#_deny_rules_for_the_entire_repo">"deny" rules for the entire repo</a>
* <a href="#_summary_permissions">summary: permissions</a>
* <a href="#_virtual_ref_types">virtual "ref"-types</a>
* <a href="#_other_tips">other tips</a>
* <a href="#_personal_branches">personal branches</a>
* <a href="#_splitting_up_rules_into_rulesets">splitting up rules into rulesets</a>
* <a href="#_gitweb_and_daemon">gitweb and daemon</a>
* <a href="#_repo_specific_git_config_commands">repo specific `git config` commands</a>
* <a href="#_repo_owner_description_line_for_gitweb">repo owner/description line for gitweb</a>
# F=conf the access control file `gitolite.conf`
Gitolite has an advanced access control language that is designed to be
powerful but easy to use. Other objectives were that it should be even easier
@ -35,9 +10,7 @@ something as different as possible from the brain-dead, nausea-inducing
This document describes the syntax and semantics of the access control rules
and other configuration directives in the `gitolite.conf` file.
<a name="_syntax"></a>
### syntax
## #syntax syntax
In general, everything is **space separated**; there are no commas,
semicolons, etc., in the syntax.
@ -52,18 +25,14 @@ 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)
<a name="_continuation_lines"></a>
#### continuation lines
### continuation lines
There are no continuation lines -- gitolite does not process C-style
backslash-escaped newlines as anything special. However, the section on
"groups" will tell you how you can break up large lists of names in a group
definition into multiple lines.
<a name="_include_files"></a>
#### include files
### include files
Gitolite allows you to break up the configuration into multiple files and
include them in the main file for convenience.
@ -86,11 +55,7 @@ Files that have been already processed once are skipped, with a warning.
<font color="gray">Advanced users: `subconf`, a command that is very closely
related to `include`, is documented [here][subconf].</font>
[subconf]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command
<a name="_basic_access_control"></a>
### basic access control
## F=bac basic access control
Here's a very basic set of rules:
@ -137,18 +102,14 @@ by Linus and currently maintained by Junio.
</font>
<a name="_how_rules_are_matched"></a>
#### how rules are matched
### how rules are matched
It's important to understand that there're two levels at which access control
happens. Please see [this][l2] for details, especially about the first level
happens. Please see [this][2levels] for details, especially about the first level
check. Much of the complexity applies only to the second level check, so that
is all we will be discussing here. This check is done by the update hook, and
determines whether the push succeeds or fails.
[l2]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_two_levels_of_access_rights_checking
For basic permissions like this, matching is simple. Gitolite already knows:
* the user
@ -160,9 +121,7 @@ Gitolite goes down the list of rules matching the user, repo, and the ref.
The first matching rule that has the permission you're looking for (`W` or
`+`), results in success. A fallthrough results in failure.
<a name="_branches_tags_and_specifying_refex_es"></a>
#### branches, tags, and specifying "refex"es
### branches, tags, and specifying "refex"es
One of the original goals of gitolite was to allow access control at the
branch/tag (aka "ref") level. The git source code contains a sample update
@ -219,9 +178,7 @@ looks like "refs/heads/foo", while a tag ref looks like "refs/tags/bar")
"v1.0", "v2.0rc1", all match the criterion specified by `v[0-9]` because
this is a prefix match only.
<a name="_groups"></a>
#### groups
### groups
Gitolite allows you to define **groups** of repos. users, or even refexes. A
group is semantically (but *not* syntactically) like a `#define` in C. Here
@ -262,97 +219,37 @@ parsed in a single-pass, so later *additions* to a group name cannot affect
earlier *uses* of it. If you moved line 2 to the end, "@alldevs" would only
have 6 names in it.
<a name="_the_special_all_group"></a>
##### the special `@all` group
#### the special `@all` group
There's a special group called `@all` that includes all authenticated users
when used as a username; you've seen examples of it earlier.
[Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in
[doc/gitolite.rc.mkd][rcdoc].]
Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in the
documentation for [`~/.gitolite.rc`][rc].
When used as a reponame, it includes all repos.
<a name="_advanced_access_control"></a>
### advanced access control
## F=aac advanced access control
The previous section is sufficient for most common needs, but gitolite can go
a lot further than that.
<a name="_creating_and_deleting_branches"></a>
### #deny "deny" rules
#### creating and deleting branches
Since the beginning of gitolite, `RW` gave the ability, not only to update,
but to *create* a branch (that matched the refex). Similarly, `RW+` meant
being able to not only rewind, but also delete a ref. Conceptually, a rewind
is almost the same as a delete+push (the only difference I can see is if you
had core.logAllRefUpdates set, which is *not* a default setting).
However, there seem to be cases where it is useful to distinguish these cases.
Arguments can be made on all sides if you're dealing with new users, so
gitolite supports that.
We'll look at the delete/rewind case in detail first:
* if the rules for a repo do not contain a `D` anywhere, then `RW+` will
allow both rewind and delete operations. Apart from being more convenient
if you don't need this separation, this also ensures backward
compatibility for setups created before this separation feature was added
to gitolite).
* if, however, *any* of the rules for a repo contains a `D` (example: `RWD`,
`RW+D`, etc) then `RW+` by itself will permit only a rewind, not a delete
The same thing applies to create/push, where if you have permissions like
`RWC` or `RW+C` anywhere in that repo, a simple `RW` or `RW+` can no longer
*create* a new ref.
You can combine the `C` and `D` also. Thus, the set of permissions you now
know about are, in regex syntax: `R|RW+?C?D?`. See a later section for the
full set of permissions possible.
Some usage hints:
* if you find that `RW+` no longer allows creation/deletion but you can't
see a `C`/`D` permission in the rules, remember that gitolite allows a
repo config to be specified in multiple places for convenience, included
delegated or included files. Be sure to search everywhere :)
* a quick way to make this the default for *all* your repos is:
repo @all
RWCD dummy-branch = foo
where foo can be either the administrator, or if you can ignore the
warning message when you push, a non-existant user.
<a name="_deny_rules"></a>
#### "deny" rules
<a name="_warnings_and_required_reading"></a>
##### warnings and required reading
#### warnings and required reading
Gitolite performs access checks at 2 levels. The first check is performed for
both read *and* write operations, while the second one happens only for write
operations.
**Required reading**: [this section][two_l] of the documentation.
[two_l]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_two_levels_of_access_rights_checking
**Required reading**: [this section][2levels] of the documentation.
**Warning**: When using deny rules, the order of your rules matters, where
earlier it did not. If you're just starting to add a deny rule to an existing
ruleset, it's a good idea to review the entire ruleset once, to make sure
you're doing it right.
<a name="_deny_rules_for_refs_in_a_repo"></a>
##### "deny" rules for refs in a repo
#### "deny" rules for refs in a repo
You can use "deny" rules for the second check, to prevent people pushing
branches or tags that they should not be allowed to.
@ -403,9 +300,7 @@ And here's how it works:
before the third one, and it has a `-` as the permission, so the push
fails
<a name="_deny_rules_for_the_entire_repo"></a>
##### "deny" rules for the entire repo
#### "deny" rules for the entire repo
The previous section described deny rules for the second check, which is a
fairly common need. However, gitolite does not process deny rules for the
@ -441,9 +336,53 @@ Here are some notes on how/why this works:
gitolite just ignores the refexes, and simply looks at the permission (R,
RW, "-", etc) and the user list.
<a name="_summary_permissions"></a>
### #rwcd creating and deleting branches
### summary: permissions
Since the beginning of gitolite, `RW` gave the ability, not only to update,
but to *create* a branch (that matched the refex). Similarly, `RW+` meant
being able to not only rewind, but also delete a ref. Conceptually, a rewind
is almost the same as a delete+push (the only difference I can see is if you
had core.logAllRefUpdates set, which is *not* a default setting).
However, there seem to be cases where it is useful to distinguish these cases.
Arguments can be made on all sides if you're dealing with new users, so
gitolite supports that.
We'll look at the delete/rewind case in detail first:
* if the rules for a repo do not contain a `D` anywhere, then `RW+` will
allow both rewind and delete operations. Apart from being more convenient
if you don't need this separation, this also ensures backward
compatibility for setups created before this separation feature was added
to gitolite).
* if, however, *any* of the rules for a repo contains a `D` (example: `RWD`,
`RW+D`, etc) then `RW+` by itself will permit only a rewind, not a delete
The same thing applies to create/push, where if you have permissions like
`RWC` or `RW+C` anywhere in that repo, a simple `RW` or `RW+` can no longer
*create* a new ref.
You can combine the `C` and `D` also. Thus, the set of permissions you now
know about are, in regex syntax: `R|RW+?C?D?`. See a later section for the
full set of permissions possible.
Some usage hints:
* if you find that `RW+` no longer allows creation/deletion but you can't
see a `C`/`D` permission in the rules, remember that gitolite allows a
repo config to be specified in multiple places for convenience, included
delegated or included files. Be sure to search everywhere :)
* a quick way to make this the default for *all* your repos is:
repo @all
RWCD dummy-branch = foo
where foo can be either the administrator, or if you can ignore the
warning message when you push, a non-existant user.
## summary: permissions
The full set of permissions, in regex syntax: `-|R|RW+?C?D?`. This expands to
one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
@ -453,36 +392,24 @@ one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
the standalone `C`, which is not really a "ref" level permission and can be
found in doc/wildcard-repositories.mkd.]
<a name="_virtual_ref_types"></a>
## F=_confother other tips
### virtual "ref"-types
This is a highly advanced topic; see [doc/virtualrefs-and-scoring.mkd][vs] for
details.
[vs]: http://sitaramc.github.com/gitolite/doc/virtualrefs-and-scoring.html
<a name="_other_tips"></a>
### other tips
<a name="_personal_branches"></a>
#### personal branches
### personal branches
Gitolite lets you define a "personal" or "scratch" namespace prefix for each
developer (for example, `refs/personal/<devname>/*`); see the "personal
branches" section in `doc/3-faq-tips-etc.mkd` for details.
developer. See [here][pers] for details.
<a name="_splitting_up_rules_into_rulesets"></a>
### #ruleaccum rule accumulation
#### splitting up rules into rulesets
(Also see [this][ruleaccum2] for a different example that may be more
intuitive for some people).
Gitolite lets you specify access rules for a repo in bits and pieces. This
can be very convenient sometimes. Let's say you have a mix of open source and
closed source projects, and "bosses" should have read access to all projects,
and everyone should have read access to open source projects. Assuming the
appropriate group definitions, this would work:
Gitolite lets you specify access rules for a repo in bits and pieces, and
accumulates them in the same sequence they were given. This is very
convenient. Let's say you have a mix of open source and closed source
projects, and "bosses" should have read access to all projects, and everyone
should have read access to open source projects. Assuming the appropriate
group definitions, this would work:
# all bosses have read access to all projects
repo @open @closed @topsecret
@ -503,35 +430,77 @@ And although this example used groups, you can use reponames as well, or mix
and match them. You can even distribute rulesets across multiple "include"
files if you wish.
Just remember that if you use [deny rules][dr] anywhere then the *order of the
Just remember that if you use [deny rules][deny] anywhere then the *order of the
rules matters*!
[dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
This feature also helps people who generate their gitolite.conf itself from
some *other* database -- it allows them much more flexibility in how they
generate rules.
<a name="_gitweb_and_daemon"></a>
### #gwd specifying gitweb and daemon access
#### gitweb and daemon
Gitolite allows you to specify access for git-daemon and gitweb. 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.
Gitolite allows you to specify access for git-daemon and gitweb. See
[this][gwd] for more on this.
Gitolite has two pre-defined, "special", usernames: `daemon` and `gitweb`.
[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
To make a repo or repo group accessible via "git daemon", just give read
permission to the special user "daemon". Similarly, give read permission to
`gitweb` to allow the gitweb CGI to show the repo. Something like this:
<a name="_repo_specific_git_config_commands"></a>
repo foo bar baz
R = gitweb daemon
#### repo specific `git config` commands
This gives you a quick way to offer multiple repos up for gitweb and/or daemon
access.
However, **setting a description** for the project also enables gitweb
permissions so you can do it that way if you want. Of course in this case you
have to deal with each repo separately. Add lines like this to gitolite.conf:
foo = "some description"
bar = "some other description"
baz = "yet another description"
You can also **specify an owner** for gitweb to show, if you like; for example
I might use:
gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git"
These lines are standalone, so you can add them anywhere in the conf file.
Note that gitolite does **not** install or configure gitweb/git-daemon -- that
is a one-time setup you must do separately. All gitolite 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.
Please **note** that giving permissions to these special users via `@all`
(that is, using either `repo @all` or `R = @all`), will not work unless you
set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`. Also, **NOTE**
that giving them read access to `repo @all` means the `gitolite-admin` repo is
also accessible. **It is upto you to decide if that is OK in your
environment**.
### #rsgc repo specific `git config` commands
(Thanks to teemu dot matilainen at iki dot fi)
> ----
> **Note**: this won't work unless the rc file has the right settings;
> please see `$GL_GITCONFIG_KEYS` in [doc/gitolite.rc.mkd][rcdoc] for
> details and security information.
> please see `$GL_GITCONFIG_KEYS` in the [rc file doc][rc] for details and
> security information.
> ----
@ -588,13 +557,3 @@ The "delete config variable" syntax can also be used, if you wish:
As you can see, the general idea is to place the most generic ones (`repo
@all`, or repo patterns like `repo foo.*`) first, and place more specific ones
later to override the generic settings.
[rcdoc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
<a name="_repo_owner_description_line_for_gitweb"></a>
#### repo owner/description line for gitweb
You can include owner/description information in the conf file, and gitolite
will put it in places where gitweb will pick it up. See [here][gwd] for more
on this.

93
doc/gitolite.rc.mkd
View file

@ -1,4 +1,4 @@
# configuring gitolite's advanced features -- the `.gitolite.rc` file
# F=rc configuring gitolite's advanced features -- the `.gitolite.rc` file
This is the documentation for the contents of the "rc" file
(`$HOME/.gitolite.rc`) on the server. Until now this documentation was
@ -8,37 +8,23 @@ and too difficult to grok for people new to gitolite.
The documentation follows approximately the same order as the sample variables
in the (now reorganised) example "rc" file.
In this document:
* <a href="#_variables_that_should_not_be_touched_at_all">variables that should not be touched at all</a>
* <a href="#_most_often_used_changed_variables">most often used/changed variables</a>
* <a href="#_variables_with_an_efficiency_performance_impact">variables with an efficiency/performance impact</a>
* <a href="#_variables_with_a_security_impact">variables with a security impact</a>
* <a href="#_less_used_changed_variables">less used/changed variables</a>
* <a href="#_rarely_changed_variables">rarely changed variables</a>
* <a href="#_constants_that_aren_t_">constants that aren't!</a>
[Note: in perl, there is no actual boolean. The undefined value, the number
'0', and the empty string, are all 'false'. Everything else is 'true'. It is
thus common to use just 0/1 for false/true].
<a name="_variables_that_should_not_be_touched_at_all"></a>
### variables that should not be touched at all
## variables that should not be touched at all
The first section does not need too much elaboration. Let's just say bad
things happen if you change them.
<a name="_most_often_used_changed_variables"></a>
### most often used/changed variables
## most often used/changed variables
* `$GL_WILDREPOS`, boolean, default 0
Setting this variable lets your users create repositories based on wild
cards, hand out R and RW permissions to other users to collaborate, etc.
See [doc/wildcard-repositories.mkd][wild] for lots of info on this.
See [this][wild] for lots of info on this.
* `$PROJECTS_LIST`, filename, default `~/projects.list`
@ -68,15 +54,13 @@ things happen if you change them.
This is because umask only affects permissions on newly created files, not
existing ones.
<a name="_variables_with_an_efficiency_performance_impact"></a>
### variables with an efficiency/performance impact
## variables with an efficiency/performance impact
* `$GL_BIG_CONFIG`, boolean, default 0
This is the most common setting for efficiency in handling large repo/user
groups. This is a very powerful setting; please read
[doc/big-config.mkd][bc] for all the details you might need.
groups. This is a very powerful setting; please read [this][bc] if you
need details.
There are 3 other settings related to big configs. They are changed only
in rare cases, however, so are described later.
@ -85,8 +69,7 @@ things happen if you change them.
If you have *lots* of repos, and you're *not* using gitweb or daemon, you
should probably set this on for efficiency. Despite the name, it also
blocks repo config settings. Please read [doc/big-config.mkd][bc] for
more details.
blocks repo config settings. Please read [this][bc] for more details.
**WARNING**: if your description files are maintained by some other means
than via the gitolite config file, make sure you set this variable to 1.
@ -99,11 +82,9 @@ things happen if you change them.
* `$BIG_INFO_CAP`, number, default 20
See [using patterns to limit output][limit] for details.
See [using patterns to limit output][limitoutput] for details.
<a name="_variables_with_a_security_impact"></a>
### variables with a security impact
## #rcsecurity variables with a security impact
**IMPORTANT NOTE**
@ -136,8 +117,8 @@ on feedback from my users to find or fix issues.
This setting allows the repo admin to define acceptable gitconfig keys.
Gitolite allows you to set git repo options using the "config" keyword;
see the section on "repo specific git config commands" in
[doc/gitolite.conf.mkd][gitconf] for details and syntax.
see the section on "repo specific git config commands" in the
[gitolite.conf][conf] documentation for details and syntax.
However, if you are in an installation where the repo admin does not (and
should not) have shell access to the server, then allowing him to set
@ -196,9 +177,8 @@ on feedback from my users to find or fix issues.
enable this, give the variable the absolute path to whatever file apache
(etc) expect to find the passwords in.
Look in [doc/3-faq-tips-etc.mkd][faq] ("easier to link gitweb
authorisation with gitolite" section) for more details on using this
feature.
Look in the docs for [linking gitweb authorisation with
gitolite][gitwebauth] for more details on using this feature.
* `$RSYNC_BASE`, string, default empty
@ -245,9 +225,9 @@ on feedback from my users to find or fix issues.
**WARNING**: Use this feature only if (a) you really know what you're
doing and (b) you really, **really**, know what you're doing! Please read
[doc/admin-defined-commands.mkd][adc] for details. This is an extremely
powerful and flexible feature, and naturally anything that flexible can be
a security risk!
the [admin defined commands][ADCs] document for details. This is an
extremely powerful and flexible feature, and naturally anything that
flexible can be a security risk!
* `$GL_GET_MEMBERSHIPS_PGM`, string, default undef
@ -257,17 +237,16 @@ on feedback from my users to find or fix issues.
Set the following variable to the name of a script that, given a username
as argument, will return a list of groups that she is a member of. See
[doc/big-config.mkd][bc] for more details.
the [big config][bc] doc for more details.
Example: `$GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"`
* `$GL_HTTP_ANON_USER`, string, default undef
Analogous to running mob branches over ssh (as described in
[doc/mob-branches.mkd][mob], this variable -- combined with appropriate
setup described in [doc/http-backend.mkd][smart] -- lets you pretend to
gitolite that unauthenticated HTTP users are actually authenticated as
this user.
Analogous to running mob branches over ssh (as described in the [mob
branches][mob]), this variable -- combined with appropriate setup
described in [doc/http-backend.mkd][http] -- lets you pretend to gitolite
that unauthenticated HTTP users are actually authenticated as this user.
* `$GL_REF_OR_FILENAME_PATT`, string
@ -284,9 +263,7 @@ on feedback from my users to find or fix issues.
it, if you really need to. If you do, at least avoid backquotes and the
dollar sign!
<a name="_less_used_changed_variables"></a>
### less used/changed variables
## less used/changed variables
* `$GL_ALL_INCLUDES_SPECIAL`, boolean, default undef
@ -302,10 +279,9 @@ on feedback from my users to find or fix issues.
This variable is a space-separated list of the allowed roles.
PLEASE, *PLEASE*, read the section in
[doc/wildcard-repositories.mkd][wild] for caveats and warnings. This is a
VERY powerful feature and if you're not careful you could mess up the ACLs
nicely.
Please read the **[warning][rolenamewarn]** in the [wild][] document
before using this feature. This is a VERY powerful feature and if you're
not careful you could mess up the ACLs nicely.
This is the internal default if you don't set it (like if you didn't
update your ~/.gitolite.rc with new variables when you upgraded gitolite):
@ -317,9 +293,7 @@ on feedback from my users to find or fix issues.
$GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS TESTERS";
<a name="_rarely_changed_variables"></a>
### rarely changed variables
## rarely changed variables
* `$GL_LOGT`, string, default `$GL_ADMINDIR/logs/gitolite-%y-%m.log`
@ -351,12 +325,10 @@ on feedback from my users to find or fix issues.
This is where all the repos go. If it's not an absolute path, it is
considered to be relative to $HOME. Moving all the repositories after the
install has completed is doable: just [disable writes][dwr] to gitolite,
install has completed is doable: just [disable writes][disable] to gitolite,
move `~/repositories/*`, change this variable, then re-enable writes.
<a name="_constants_that_aren_t_"></a>
### constants that aren't!
## constants that aren't!
The source file `src/gitolite_rc.pm` defines a few "constants", for example:
@ -371,13 +343,6 @@ defining a new value for any or all of them in your `~/.gitolite.rc` file.
If you use this to relax some of the patterns involved (for example, the value
of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing.
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
[bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
[faq]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html
[adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
[mirr]: http://sitaramc.github.com/gitolite/doc/mirroring.html
[mob]: http://sitaramc.github.com/gitolite/doc/mob-branches.html
[smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html
[dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
[limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output
[gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands

48
doc/hook-propagation.mkd
View file

@ -1,27 +1,13 @@
## hook propagation in gitolite
# F=hook_prop hook propagation in gitolite
Some users like to know how hooks propagate, and when, and why there appear to
be two places to put them, and so on. I'll try and set out the logic here.
**Note**: This is **not** the document to read if you just want to install a
new custom hook; treat it as more "theory" than "lab". ([Here][ch] is the
new custom hook; treat it as more "theory" than "lab". ([Here][customhooks] is the
"lab" version!)
[ch]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_custom_hooks
In this document:
* <a href="#_hooks_used_by_gitolite">hooks used by gitolite</a>
* <a href="#_where_do_I_the_admin_put_the_hooks_">**where** do I (the admin) put the hooks?</a>
* <a href="#_the_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
* <a href="#_the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
* <a href="#_why_two_places_">why two places?</a>
* <a href="#_special_case_the_non_root_method">special case: the "non-root" method</a>
* <a href="#_when_do_hooks_propagate_">**when** do hooks propagate?</a>
<a name="_hooks_used_by_gitolite"></a>
### hooks used by gitolite
## hooks used by gitolite
Gitolite uses only 2 hooks. **All** repos have an `update` hook, without
which there is no write-level access control (per-branch permissions). The
@ -35,9 +21,7 @@ In addition there is a "sentinel file" -- an empty file called
The final objective of all this is that each repo's `hooks/` directory should
get all the hooks that it is meant to get.
<a name="_where_do_I_the_admin_put_the_hooks_"></a>
### **where** do I (the admin) put the hooks?
## **where** do I (the admin) put the hooks?
In general, **all** hooks go into the `hooks/common` directory. Only the
special `post-update` hook meant for the admin repo goes into
@ -47,11 +31,9 @@ Now we'll discuss the locations of these `hooks/common` and
`hooks/gitolite-admin` directories. This depends on which install method you
used.
(Please refer to [doc/1-INSTALL.mkd][0inst] for what these "methods" are).
(Please refer to [doc/1-INSTALL.mkd][install] for what these "methods" are).
<a name="_the_GL_PACKAGE_HOOKS_directory"></a>
#### the `GL_PACKAGE_HOOKS` directory
### the `GL_PACKAGE_HOOKS` directory
You might recall that the "root", and "non-root" methods run a command called
`gl-system-install`, the third argument of which is some directory of your
@ -68,9 +50,7 @@ process does the equivalent of `gl-system-install`.
So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can
place your hooks.
<a name="_the_HOME_gitolite_directory"></a>
#### the `$HOME/.gitolite` directory
### the `$HOME/.gitolite` directory
You might also recall that, in these three methods, each **hosting user** has
to run `gl-setup`. This sets up, among other things, `$HOME/.gitolite`
@ -78,9 +58,7 @@ directory, which also contains a `hooks/` directory.
So now there are two places you can put your hooks, apparently.
<a name="_why_two_places_"></a>
#### why two places?
### why two places?
Just think of the "package" and "root" methods for now, even if you're using
the "non-root" method.
@ -104,18 +82,14 @@ get copied to `$HOME/.gitolite/hooks` when you "install". I need to fix and
thoroughly test this later; for now, just ignore the extra files you see in
there; they're harmless/redundant (TODO)]
<a name="_special_case_the_non_root_method"></a>
#### special case: the "non-root" method
### special case: the "non-root" method
This method was created later, just piggy-backing on everything that already
existed to cater to the "package" and "root" methods. In this method, the
`$GL_PACKAGE_HOOKS` is as accessible or under your control as
`$HOME/.gitolite`, so it doesn't matter where you put your hooks.
<a name="_when_do_hooks_propagate_"></a>
### **when** do hooks propagate?
## **when** do hooks propagate?
First: realise that gitolite *wants to make sure* that all the hooks in your
`hooks/common` directory get copied (symlinked, actually) to *every* repo that
@ -157,5 +131,3 @@ For people who do not want certain hooks to run for certain repos, one simple
solution that will work right now is to check the value of `$GL_REPO` at the
start of the hook, and `exit 0` based on what it contains/matches.
[0inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html

54
doc/http-backend.mkd
View file

@ -1,4 +1,4 @@
# how to setup gitolite to use smart http mode
# F=http how to setup gitolite to use smart http mode
**Note**: "smart http" refers to the feature that came with git 1.6.6, late
2009 or so. The base documentation for this is `man git-http-backend`. Do
@ -6,22 +6,7 @@
that is the same or even relevant -- that is from 2006 and is quite different
(and arguably obsolete).
In this document:
* <a href="#_WARNINGS_plus_stuff_I_need_help_with">WARNINGS, plus stuff I need help with</a>
* <a href="#_additional_requirements">additional requirements</a>
* <a href="#_detailed_instructions">detailed instructions</a>
* <a href="#_install_gitolite_under_apache_">install gitolite under "apache"</a>
* <a href="#_setup_apache">setup apache</a>
* <a href="#_usage">usage</a>
* <a href="#_allowing_anonymous_access">allowing anonymous access</a>
* <a href="#_ssh_http_access_and_the_GIT_HTTP_EXPORT_ALL_variable">ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable</a>
----
<a name="_WARNINGS_plus_stuff_I_need_help_with"></a>
### WARNINGS, plus stuff I need help with
## WARNINGS, plus stuff I need help with
* I have NOT converted the test suite to use this mode. Volunteers to
convert it to http access are welcome :-)
@ -47,32 +32,24 @@ In this document:
and given a proper $HOME and `~/.ssh/authorized_keys` and all that). If
anyone has the energy to try that please let me know how that went.
<a name="_additional_requirements"></a>
### additional requirements
## additional requirements
* requires `GIT_PROJECT_ROOT` (see "man git-http-backend" for what this is)
set explicitly (i.e., it is no longer optional). Please set it to some
place outside apache's `DOCUMENT_ROOT`.
<a name="_detailed_instructions"></a>
### detailed instructions
## detailed instructions
I assume you've installed apache 2.x and git on the server.
I assume your httpd runs under the "apache" userid; adjust instructions below
if it does not. Similarly for "/var/www" and other file names/locations.
I assume you have read the "[please read this first][1rtf]" section of the
I assume you have read the "[please read this first][insttrouble]" section of the
main install document to get an idea of the general concepts and terminology
(just ignore anything that is specific to ssh).
[1rtf]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_please_read_this_first
<a name="_install_gitolite_under_apache_"></a>
#### install gitolite under "apache"
### install gitolite under "apache"
Follow the "non-root" method, but since you can't even "su - apache", make the
following variations when doing this as root:
@ -116,9 +93,7 @@ following variations when doing this as root:
chown -R apache.apache $GITOLITE_HTTP_HOME
<a name="_setup_apache"></a>
#### setup apache
### setup apache
You will need to setup certain values in the httpd conf, as given in `man
git-http-backend`. You can put all them into, for instance,
@ -144,9 +119,7 @@ from those in the manpage cited above, plus we have one extra variable:
Now create/update the password file in `/path/to/some/passwdfile` using the
`htpasswd` command, and you're all done for the setup!
<a name="_usage"></a>
### usage
## usage
Git URLs look like `http://user:password@server/git/reponame.git`.
@ -171,9 +144,7 @@ following works and I'm leaving it at that:
With a few nice shell aliases, you won't even notice the horrible convolutions
here ;-)
<a name="_allowing_anonymous_access"></a>
### allowing anonymous access
## allowing anonymous access
Like [mob branches][mob] with ssh, you can allow completely
**un**-authenticated users to still have some rights specified in gitolite.
@ -192,9 +163,7 @@ Briefly, here's how:
URLs (in this example) will then look like `http://server/gitmob/reponame.git`
-- we lose the userid:passwd part and change 'git' to 'gitmob'.
<a name="_ssh_http_access_and_the_GIT_HTTP_EXPORT_ALL_variable"></a>
### ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable
## ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable
This document only talks about setting up access to a set of git repositories
purely via smart http. The `GIT_HTTP_EXPORT_ALL` variable must be set for
@ -222,6 +191,3 @@ repo.
----
Enjoy!
[mob]: http://sitaramc.github.com/gitolite/doc/mob-branches.html

205
doc/index.mkd Normal file
View file

@ -0,0 +1,205 @@
# F=index Hosting git repositories
Gitolite allows you to setup git hosting on a central server, with
fine-grained access control and many (many!) more powerful features.
## #qi quick install
If you're comfortable with Unix and ssh, the following steps should work.
* create a user called `git`. Login to this user.
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
* now run these commands:
git clone git://github.com/sitaramc/gitolite
gitolite/src/gl-system-install
gl-setup ~/YourName.pub
You're done.
**WARNING**: do **NOT** add repos or users directly on the server! You MUST
manage the server by cloning the special 'gitolite-admin' repo on your
workstation (`git clone git@server:gitolite-admin`), making changes, and
pushing them. Here's how to [add users and repos][add].
## #rtfm what should you read?
The complete online documentation for gitolite is
[here](http://sitaramc.github.com/gitolite). There's a lot of it, so here're
some reading suggestions.
If you're a **user** (i.e., not a gitolite admin), you only need [this][user].
Otherwise, the suggested reading order is this:
* **quick intro**: this document, or at least the "[what is
gitolite][gl_what]" section just below this one.
* **installation**: if the [quick install][qi] above did not work for you,
then read the [INSTALL][install] document. The "[trouble][insttrouble]"
section in it may be useful too.
* **basic** administration tasks: [adding users and repos][add].
When you have to use more features, look in the master table of contents
(there's a link to it at the top of *every* document), and use your browser's
search function to search for stuff.
### F=other_docs what do the other docs contain
The master TOC (see link above) is really the only *comprehensive* list of
what is there, but here's an attempt to give you an overview!
* understanding gitolite
* gitolite install and basic admin in [pictures][]
* gitolite.conf by [example][conf_examples]
* gitolite and [ssh][gl_ssh]
* normal admin tasks done on the server
* [admin][]: adding your own hooks, adding existing repos into gitolite, etc.
* [rc][]: setting gitolite behaviour options (warning: some of the
variables have a security impact if you're careless)
* normal admin tasks done by changing [gitolite.conf][conf]
* basic access control
* advanced access control
* extras: personal branches, gitweb/git-daemon access, git config settings
* advanced use (experts only; you can shoot yourself in the foot nicely!)
* [ADCs][]: allowing users to run specific shell commands (but not give them a shell)
* (also, [sample ADCs][shipped_ADCs] that come with gitolite)
* letting [users create][wild] their own repos and assign permissions
* [delegating][deleg] admin rights
* [mirroring][]
* special installation scenarios:
* using smart-[http][] instead of ssh
* [migrating][migr] from gitolite
Finally, [tips][] has a lot of useful information.
## #gl_what what is gitolite?
Gitolite is an access control layer on top of git. Here's an "executive
summary":
* use a single unix user ("real" user) on the server
* provide access to many gitolite users
* they are not "real" users
* they do not get shell access
* control access to many git repositories
* read access controlled at the repo level
* write access controlled at the branch/tag/file/directory level,
including who can rewind, create, and delete branches/tags
* can be installed without root access, assuming git and perl are already
installed
* authentication is most commonly done using sshd, but you can also use
httpd if you prefer (this may require root access).
* several other neat features, too many to list here
## F=_need why is gitolite needed?
Gitolite is separate from git, and needs to be installed and configured. So...
why do we bother?
Gitolite is useful in any server that is going to host multiple git
repositories, each with many developers, where some sort of access control is
required.
In theory, this can be done with plain old Unix permissions: each user is a
member of one or more groups, each group "owns" one or more repositories, and
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
allow/disallow users access to repos.
But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a
killer, especially in tightly controlled environments
* adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with
* *viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually
* auditing historical permissions or permission changes is pretty much
impossible without extraneous tools
* errors or omissions in setting the permissions exactly can cause problems
of either kind: false accepts or false rejects
* without going into ACLs it is not possible to give some people read-only
access while some others have read-write access to a repo (unless you make
it world-readable). Group access just doesn't have enough granularity
* it is absolutely impossible to restrict pushing by branch name or tag
name.
Gitolite does away with all this:
* it uses ssh magic to remove the need to give actual unix userids to
developers
* it uses a simple but powerful config file format to specify access rights
* access control changes are affected by modifying this file, adding or
removing user's public keys, and "compiling" the configuration
* this also makes auditing trivial -- all the data is in one place, and
changes to the configuration are also logged, so you can audit them.
* finally, the config file allows distinguishing between read-only and
read-write access, not only at the repository level, but at the branch
level within repositories.
## why did I write it?
The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single
reason I started *thinking* about writing gitolite.
It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
fast forward push") is potentially dangerous, but sometimes needed. So is
deleting a branch (which is really just an extreme form of rewind). I needed
something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
### F=_morefeatures some more features
Here're some more features.
* simple, yet powerful, config file syntax, including specifying
gitweb/daemon access. You'll need this power if you manage lots of
users+repos+combinations of access
* apart from branch-name based restrictions, you can also restrict by
file/dir name changed (i.e., output of `git diff --name-only`)
* if your requirements are still too complex, you can split up the config
file and delegate authority over parts of it
* easy to specify gitweb owner, description and gitweb/daemon access
* easy to sync gitweb (http) authorisation with gitolite's access config
* comprehensive logging [aka: management does not think "blame" is just a
synonym for "annotate" :-)]
* "personal namespace" prefix for each dev
* migration guide and simple converter for gitosis conf file
* "exclude" (or "deny") rights at the branch/tag level
* specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking
## security
Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one.
The first person to find a hole that allows a non-admin user to push a change
to a repository that he is not allowed to, will get a modest reward of 5000
INR. The hole should not require enabling any of the options listed as having
a [security impact][rcsecurity] in the rc file, nor obvious things like setting
the umask too loose, etc.
## contact and license
Gitolite is released under GPL v2. See COPYING for details.
* author: sitaramc@gmail.com, sitaram@atc.tcs.com
* mailing list: gitolite@googlegroups.com
* list subscribe address : gitolite+subscribe@googlegroups.com

313
doc/1-INSTALL.mkd → doc/install.mkd
View file

@ -1,38 +1,10 @@
# gitolite installation
# F=install gitolite installation
(Note: git servers are most commonly used with ssh URLs, and this document
describes installing gitolite to support such usage. If your users prefer
http URLs, read [this][http] to install gitolite to support "smart http").
In this document:
* <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
* <a href="#_side_note_upgrading">(side note) upgrading</a>
* <a href="#_package_method">package method</a>
* <a href="#_non_root_method">non-root method</a>
* <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a>
* <a href="#_root_method">root method</a>
* <a href="#_troubleshooting">troubleshooting</a>
* <a href="#_important_points_to_note">important points to note</a>
* <a href="#_naming_conventions_used">naming conventions used</a>
* <a href="#_requirements">requirements</a>
* <a href="#_client_workstation">client/workstation</a>
* <a href="#_server">server</a>
* <a href="#_technical_skills">technical skills</a>
* <a href="#_getting_the_gitolite_software">getting the gitolite software</a>
* <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
* <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
* <a href="#_uninstalling">uninstalling</a>
* <a href="#_cleaning_out_a_botched_install">cleaning out a botched install</a>
* <a href="#_uninstalling_gitolite_completely">uninstalling gitolite completely</a>
* <a href="#_appendix_a_the_from_client_method">appendix a: the from-client method</a>
* <a href="#_appendix_b_PATH_issues_for_gl_setup">appendix b: PATH issues for gl-setup</a>
----
<a name="_installing_and_upgrading_gitolite"></a>
### installing and upgrading gitolite
## installing and upgrading gitolite
This section tells you how to install/upgrade gitolite, without too much
background. Later sections have more details and troubleshooting info; please
@ -56,23 +28,7 @@ These install methods are described in detail below. (*Once you finish the
install, read the [admin document][admin] to administer your gitolite
installation*).
<a name="_side_note_upgrading"></a>
#### (side note) upgrading
Upgrading is easy; you just re-run some of the same commands used for install.
These commands are clearly noted in the install instructions below.
However, if you've added any new hooks, you must also run the next step (the
`gl-setup` command), although this time you don't need to supply a pubkey
filename as an argument.
[admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
[http]: http://sitaramc.github.com/gitolite/doc/http-backend.html
<a name="_package_method"></a>
#### package method
### F=rpmdeb package method
(Unlike in the rest of this document, we use "gitolite" as the "hosting user"
instead of "git" here, because that is the user that both the Fedora and
@ -97,9 +53,7 @@ On your *workstation*:
git clone gitolite@server:gitolite-admin
<a name="_non_root_method"></a>
#### non-root method
### F=nonroot non-root method
**IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method
you had better know the password to the hosting user on the server, or be able
@ -110,6 +64,8 @@ messing with the keys.
you're interested. (That tutorial is by someone else but it's nice enough for
me to link it here).
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
On your *workstation*:
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
@ -119,10 +75,9 @@ on the default PATH. If not, fiddle with the `.bashrc` or `.bash_profile` or
similar files and add it somehow. Then:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
gitolite/src/gl-system-install
# defaults to being the same as:
# src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
# gitolite/src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
@ -133,9 +88,7 @@ On your *workstation*:
git clone git@server:gitolite-admin
<a name="_upgrading_from_from_client_method_to_non_root_method"></a>
##### upgrading from from-client method to non-root method
#### F=upgrfromclient upgrading from from-client method to non-root method
Since the from-client method is now deprecated for reasons explained
elsewhere, some folks may want to do their next upgrade using the non-root
@ -165,9 +118,7 @@ There are many, many ways to skin this cat; here's one way:
Now save the file.
<a name="_root_method"></a>
#### root method
### F=root root method
On your *workstation*:
@ -176,10 +127,9 @@ On your *workstation*:
On your *server*, as *root*:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
gitolite/src/gl-system-install
# defaults to being the same as:
# src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
# gitolite/src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
@ -197,34 +147,54 @@ On your *workstation*:
git clone git@server:gitolite-admin
----
### #upgrade upgrading
<a name="_troubleshooting"></a>
Upgrading is easy; you just re-run some of the same commands used for install.
These commands are clearly noted in the install instructions below.
### troubleshooting
However, if you've added any new hooks, you must also run the next step (the
`gl-setup` command), although this time you don't need to supply a pubkey
filename as an argument.
* The most common thing that goes wrong in an install is something to do
with ssh.
## #insttrouble if you run into trouble...
Here are three facts of ssh:
If you run into trouble, please read the following sections. They have
background information that may help you, or additional steps you can take to
troubleshoot or fix the problem.
* ssh is a pain
* most people don't know ssh well enough
* even people who think they do, don't
### common install problems
Please read how [gitolite uses ssh][glgas] and the [ssh
troubleshooting][glsts] documents before asking for help.
The most common problem is usually ssh. Here are three facts of ssh:
* If you've tried multiple methods of install, you may have multiple copies
of the sources lying around. This could be a problem; see appendix b for
how to detect and deal with this.
* ssh is a pain
* most people don't know ssh well enough
* even people who think they do, don't
Please read how [gitolite uses ssh][gl_ssh] and the [ssh
troubleshooting][sts] documents before asking for help.
If you've tried multiple methods of install, you may have multiple copies of
the sources lying around. This could be a problem; see [appendix a][instpath]
for how to detect and deal with this.
If none of this works read the rest of this document, understand it as much as
you can, then ask for help.
<a name="_important_points_to_note"></a>
### #instnameconv naming conventions used
### important points to note
Throughout the documentation, we use "YourName" as the admin user, and his
workstation is called "client". The hosting user is "git", and the server is
called "server". **Please substitute your values as needed**.
**If you're using DEB or RPM**, the installer creates a user called
"gitolite", so substitute that for "git" anywhere in the docs where the
"hosting user" is mentioned as "git".
Also, we often say "the rc file". This means `~/.gitolite.rc` on the server.
And when we say the "access control rules", or "conf file", or "config file",
we mean `conf/gitolite.conf` on your gitolite-admin clone.
### F=instbg helpful background information
* gitolite runs as a single (real) user on a server, and is invoked via ssh.
Traditionally, this "hosting user" is "git", and thus all git URLs start
@ -234,8 +204,7 @@ you can, then ask for help.
* there is *usually* only one hosting user per server (machine), but
gitolite makes it trivial to have as many as you want. In fact, every
user on the server is a potential hosting user. Advanced users can
look [here][mgs]!)
user on the server is a potential hosting user.
* using this single user and sshd (or httpd) authentication, gitolite allows
you to create any number of "virtual" users. Virtual user names only mean
@ -251,7 +220,7 @@ you can, then ask for help.
administration of gitolite.
To make matters worse, ssh problems in gitolite don't always look like ssh
problems. See [doc/ssh-troubleshooting.mkd][glsts] for help.
problems. See the [ssh troubleshooting][sts] document for help.
* gitolite **does NOT** like it when people with shell access to the server
fiddle with files and directories it controls.
@ -267,27 +236,7 @@ emergency use. However, I will not be documenting it because (a) if you know
ssh you'll know how to extrapolate my instructions to do this and (b) if you
don't know ssh it'll be a nightmare to support you.
<a name="_naming_conventions_used"></a>
### naming conventions used
Throughout the documentation, we use "YourName" as the admin user, and his
workstation is called "client". The hosting user is "git", and the server is
called "server". **Please substitute your values as needed**.
**If you're using DEB or RPM**, the installer creates a user called
"gitolite", so substitute that for "git" anywhere in the docs where the
"hosting user" is mentioned as "git".
Also, we often say "the rc file". This means `~/.gitolite.rc` on the server.
And when we say the "access control rules", or "conf file", or "config file",
we mean `conf/gitolite.conf` on your gitolite-admin clone.
<a name="_requirements"></a>
### requirements
<a name="_client_workstation"></a>
### F=instrequire requirements
#### client/workstation
@ -296,8 +245,6 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
you're using putty, plink, puttygen, etc., for ssh; I recommend
msysgit for Windows and the openssh that comes with it
<a name="_server"></a>
#### server
* any Unix system with a posix compatible "sh".
@ -313,8 +260,6 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
user, even your own normal one. (If you're using an RPM/DEB the install
probably created one called "gitolite").
<a name="_technical_skills"></a>
#### technical skills
* if you're installing gitolite, you're a "system admin", like it or not.
@ -330,9 +275,7 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
* regular expressions are a big part of gitolite in many places but
familiarity is not necessary to do basic access control.
<a name="_getting_the_gitolite_software"></a>
### getting the gitolite software
### F=_getgl getting the gitolite software
You can get the latest version of gitolite from github or google code using
the 'git clone' command:
@ -341,8 +284,6 @@ the 'git clone' command:
# (OR)
git clone https://code.google.com/p/gitolite/
<a name="_getting_a_tar_file_from_a_clone"></a>
#### getting a tar file from a clone
If you are on an internal network and cannot clone the gitolite repo, you can
@ -360,55 +301,37 @@ Please use the make command as shown, not a plain "git archive", because the
Makefile adds a file called `.GITOLITE-VERSION` that will help you identify
which version you are using.
--------------------------------------------------------
## #_instappendices appendixes
<a name="_special_cases_multiple_gitolite_servers"></a>
The following sections have some miscellaneous information that does not
cleanly to fit anywhere else.
### special cases -- multiple gitolite servers
### #instpath appendix a: PATH issues for gl-setup
(**Advanced users only, please!**)
If you've tried multiple methods of install, you may have multiple copies of
the sources lying around, and when you ran `gl-setup` it picked up the wrong
one. This might also happen if the directory you supplied as the first
argument to `gitolite/src/gl-system-install` is not even in the `$PATH`.
There is no gitolite "daemon"; it gets invoked via sshd which calls
"gl-auth-command" via the "command=" option in the authkeys file (see
[gitolite and ssh][glgas] for more).
Run `su - git` then `which gl-setup` to see which it picked up. This is what
it should be for each method:
If you think about it, this means every real (unix) user on the system can
host her own gitolite server!
* RPM/DEB method: probably `/usr/bin`
* root method: the first argument to the `gitolite/src/gl-system-install` command (or
`/usr/local/bin` by default)
* non-root method: the first argument to the `gitolite/src/gl-system-install` command
(or `$HOME/bin` by default)
Of course, one doesn't normally do that in the interests of sanity, but let's
say you want to create one gitolite instance for each department on some
company-wide mega-server.
If this is not what you get, remove the partially installed or extraneous
sources, if any, and try again. Or fix your `$PATH`.
Using one of the first two methods of installation, it's trivial to create
multiple gitolite instances -- essentially any Unix user can then run
`gl-setup` with some pubkey filename as an argument and that user is now a
gitolite host.
One situation that is not easy to solve is if the system admin installed
gitolite using the RPM/DEB or root methods, and you want to install a later
version using the non-root method. Since `/usr/bin` and `/usr/local/bin` are
usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
Good luck.
You can even do this without giving shell access to the admins. Here's an
example with just two "departments", and their admins Alice and Bob:
* create userids `webbrowser_repos` and `webserver_repos`
* ask Alice and Bob for their pubkeys; copy them to the respective home
directories for convenience
* run `su - webbrowser_repos`, then `gl-setup alice.pub`
* (similarly with `webserver_repos` and `bob.pub`, and so on for others)
That's it. The URL for all web browser projects is now something like
`webbrowser_repos@server:reponame`, and similarly for the others.
Notice that you only have to do this once for each "department", and it's
really just one command after creating the userid. None of these admins need
to have a command line on the server, so don't give them the passwords if you
don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations.
<a name="_uninstalling"></a>
### uninstalling
<a name="_cleaning_out_a_botched_install"></a>
#### cleaning out a botched install
### #clean appendix b: cleaning out a botched install
When people have trouble installing gitolite, they often try to change a bunch
of things manually on the server. This usually makes things worse ;-) so
@ -428,65 +351,57 @@ here's how to clean the slate.
delete `/var/gitolite/conf` and `/var/gitolite/hooks` or
`$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks`
<a name="_uninstalling_gitolite_completely"></a>
### F=_uninstall appendix c: uninstalling gitolite completely
#### uninstalling gitolite completely
(There's some duplication between this and the previous section).
There's some duplication between this and the previous section, but
uninstalling gitolite is described in great detail in
[doc/uninstall.mkd][doc9unin]
Uninstalling gitolite is fairly easy, although it is manual. (We'll assume
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
not, adjust accordingly):
----
**server side tasks**
<a name="_appendix_a_the_from_client_method"></a>
* edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
gitolite end` markers and all the lines between them. This will prevent
any of your users from attempting a push while you are doing this.
### appendix a: the from-client method
If you are the only user, and/or *need* one or more of those keys to
continue to access this account (like if one of them is your laptop or
your home desktop etc.) then instead of deleting the line you can just
delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
This method was the only install mode at one time, but the newer ones are much
better, so it's gone now, to reduce confusion and support/documentation load.
* Now remove (or move aside or rename to something else if you're paranoid)
the following files and directories.
The only advantage of this method was that it forced you to solve the ssh
pubkey problem **before** attempting to install.
~/.gitolite
~/.gitolite.rc
~/repositories/gitolite-admin.git
But it turned out not to be worth the hassle of supporting an install scheme
that ends up with the admin user having [two keys][twokeys], though. And this
in turn forced the admin to use a different URL to access gitolite repos than
normal users, which seemed to confuse a heck of a lot of people who don't read
the prominently displayed messages and/or the documentation.
* You can remove all of `~/repositories` if you have not really started
using gitolite properly yet; that's your choice.
All in all, it wasn't one of my best ideas.
If you *do* need to preserve the other repos and continue to use them,
remove all the `update` hooks that git installs on each repository. The
easiest way is:
<a name="_appendix_b_PATH_issues_for_gl_setup"></a>
find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
### appendix b: PATH issues for gl-setup
but you can do it manually if you want to be careful.
If you've tried multiple methods of install, you may have multiple copies of
the sources lying around, and when you ran `gl-setup` it picked up the wrong
one. This might also happen if the directory you supplied as the first
argument to `src/gl-system-install` is not even in the `$PATH`.
**client side tasks**
Run `su - git` then `which gl-setup` to see which it picked up. This is what
it should be for each method:
* Any remote users that still have access must update their clone's remote
URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
actual path used, in order for the remote to still work. This is because
you'll now be accessing it through plain ssh, which means you have to give
it the full path.
* RPM/DEB method: probably `/usr/bin`
* root method: the first argument to the `src/gl-system-install` command (or
`/usr/local/bin` by default)
* non-root method: the first argument to the `src/gl-system-install` command
(or `$HOME/bin` by default)
* Finally, you as the gitolite admin *nay* have a host stanza for "gitolite"
in your *client*'s `~/.ssh/config`. Find and delete lines that look like
this:
If this is not what you get, remove the partially installed or extraneous
sources, if any, and try again. Or fix your `$PATH`.
One situation that is not easy to solve is if the system admin installed
gitolite using the RPM/DEB or root methods, and you want to install a later
version using the non-root method. Since `/usr/bin` and `/usr/local/bin` are
usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
Good luck.
[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
[doc9unin]: http://sitaramc.github.com/gitolite/doc/uninstall.html
[twokeys]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#twokeys
[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers
[glgas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
host gitolite
user git
hostname your.server
port 22
identityfile ~/.ssh/your-gitolite-admin-username

13
doc/migrate.mkd
View file

@ -1,4 +1,4 @@
# migrating from gitosis to gitolite
# F=migr migrating from gitosis to gitolite
HELP WANTED: these instructions have been revamped a bit recently
[2011-07-18], so if something doesn't work let me know.
@ -39,7 +39,7 @@ Here are the steps on the server:
chown -R git.git /home/git/repositories
* (as 'root' and/or 'git' on the server) Follow instructions to install
gitolite; see the [install document][inst]. Make sure that you **don't**
gitolite; see the [install document][install]. Make sure that you **don't**
change the default path for `$REPO_BASE` if you edit the config file!
This will give you a gitolite config that has the required entries for the
@ -80,7 +80,7 @@ instructions are to be read as "on gitolite admin's workstation".
* **IMPORTANT**: if you have any users with names like `user@foo`, where the
part after the `@` does *not* have a `.` in it (i.e., does not look like
an email address), you need to change them, because gitolite uses that
syntax for enabling multi keys.
syntax for [enabling multi keys][oldmultikeys].
You have two choices in how to fix this. You can change the gitolite
config so that all mention of `user@foo` is changed to just `user`.
@ -92,9 +92,10 @@ instructions are to be read as "on gitolite admin's workstation".
`user@foo.bar`, i.e., the part after the `@` had a `.` in it, because then
it looks like an email address.
[This][mk] will tell you more about these nuances.
[This][multikey] will tell you more about these nuances. If you can
understand it.
* **IMPORTANT: expand any multi-key files you may have**. [Here][mk]'s an
* **IMPORTANT: expand any multi-key files you may have**. [Here][multikey]'s an
explanation of what multi-keys are, how gitosis does them and how gitolite
does it differently.
@ -123,5 +124,3 @@ instructions are to be read as "on gitolite admin's workstation".
* Check all your changes to your gitolite-admin clone, commit, and push
[mk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#multikeys
[inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html

158
doc/mirroring.mkd
View file

@ -1,4 +1,4 @@
## mirroring gitolite servers
# F=mirroring mirroring gitolite servers
Mirroring a repo is simple in git; you just need code like this in a
`post-receive` hook in each repo:
@ -11,37 +11,7 @@ Mirroring a repo is simple in git; you just need code like this in a
For a lot of people, though, mirroring is more than just 'backup', and their
needs are complex enough that setup is hard.
----
In this document:
* <a href="#_why">why</a>
* <a href="#_RULE_NUMBER_ONE_">RULE NUMBER ONE!</a>
* <a href="#_IMPORTANT_cautions">IMPORTANT cautions</a>
* <a href="#_concepts_and_terminology">concepts and terminology</a>
* <a href="#_setup_and_usage">setup and usage</a>
* <a href="#_server_level_setup">server level setup</a>
* <a href="#_repository_level_setup">repository level setup</a>
* <a href="#_commands_to_re_sync_mirrors">commands to (re-)sync mirrors</a>
* <a href="#_details">details</a>
* <a href="#_the_conf_gitolite_conf_file">the `conf/gitolite.conf` file</a>
* <a href="#_redirecting_pushes">redirecting pushes</a>
* <a href="#_example_setups">example setups</a>
* <a href="#_non_autonomous">non-autonomous</a>
* <a href="#_non_autonomous_with_local_repos">non-autonomous with local repos</a>
* <a href="#_semi_autonomous">semi-autonomous</a>
* <a href="#_autonomous">autonomous</a>
* <a href="#_discussion">discussion</a>
* <a href="#_problems_with_the_old_mirroring_model">problems with the old mirroring model</a>
* <a href="#_the_new_mirroring_model">the new mirroring model</a>
* <a href="#_appendix_A_example_cronjob_based_mirroring">appendix A: example cronjob based mirroring</a>
* <a href="#_appendix_B_efficiency_versus_paranoia">appendix B: efficiency versus paranoia</a>
----
<a name="_why"></a>
### why
## #_mirrwhy why
Gitolite's mirroring used to be very rigid -- one master, any number of
slaves, but the slaves are identical copies of the master. No variations
@ -88,9 +58,7 @@ of setup you need. Here're some advantages:
As you can see, this is a bit more than a backup solution ;-)
<a name="_RULE_NUMBER_ONE_"></a>
### RULE NUMBER ONE!
## RULE NUMBER ONE!
**RULE OF GIT MIRRORING: users should push directly to only one server**! All
the other machines (the slaves) should be updated by the master server.
@ -105,9 +73,22 @@ recovers.
**Getting around rule number one**: see the section on "redirecting pushes"
later.
<a name="_IMPORTANT_cautions"></a>
## concepts and terminology
### IMPORTANT cautions
Servers can host 3 kinds of repos: master, slave, and local.
* A repo can be a **master** on one and only one server. A repo on its
"master" server is a **native** repo, on slaves it is "non-native".
* A **slave** repo cannot be pushed to by a user. It will only accept
pushes from a master server. (Exception: see the "redirecting pushes"
section later)
* A **local** repo is not involved in mirroring at all, in either direction.
## setting up mirroring
### F=mirrcautions IMPORTANT cautions
* For reasons given in the 'discussion' section later, the mirroring process
will never *create* a repo on the receiving side. It has to exist, and be
@ -151,28 +132,7 @@ later.
documentation on [git config commands][rsgc] if you wish to **delete** one
of those lines.
[rsgc]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
<a name="_concepts_and_terminology"></a>
### concepts and terminology
Servers can host 3 kinds of repos: master, slave, and local.
* A repo can be a **master** on one and only one server. A repo on its
"master" server is a **native** repo, on slaves it is "non-native".
* A **slave** repo cannot be pushed to by a user. It will only accept
pushes from a master server. (Exception: see the "redirecting pushes"
section later)
* A **local** repo is not involved in mirroring at all, in either direction.
<a name="_setup_and_usage"></a>
### setup and usage
<a name="_server_level_setup"></a>
### F=mirrsetup setup and usage
#### server level setup
@ -198,15 +158,15 @@ and 'gollum' as examples here.
trusting gollum?)
3. Now copy `hooks/common/post-receive.mirrorpush` from the gitolite source,
and install it as a custom hook called `post-receive`; see [here][ch] for
instructions.
and install it as a custom hook called `post-receive`; see
[here][customhooks] for instructions.
4. Edit `~/.gitolite.rc` on each machine and add/edit the following lines.
The `GL_HOSTNAME` variable **must** have the correct name for that host
(frodo, sam, or gollum), so that will definitely be different on each
server. The other line can be the same, or may have additional patterns
for other `git config` keys you have previously enabled. See [here][rsgc]
and the description for `GL_GITCONFIG_KEYS` in [this][vsi] for details.
and the description for `GL_GITCONFIG_KEYS` in [this][rcsecurity] for details.
$GL_HOSTNAME = 'frodo'; # will be different on each server!
$GL_GITCONFIG_KEYS = "gitolite.mirror.*";
@ -232,7 +192,7 @@ and 'gollum' as examples here.
gl-tool add-mirroring-peer gollum.pub
6. Create "host" aliases on each machine to refer to all other machines. See
[here][ha] for what/why/how.
[here][sshhostaliases] for what/why/how.
The host alias for a host (in other machines' `~/.ssh/config` files) MUST
be the same as the `GL_HOSTNAME` in the referred host's `~/.gitolite.rc`.
@ -255,8 +215,6 @@ should get you
Check this command from *everywhere to everywhere else*, and make sure you get
expected results. **Do NOT proceed otherwise.**
<a name="_repository_level_setup"></a>
#### repository level setup
Setting up mirroring at the repository level instead of at the "entire server"
@ -342,9 +300,7 @@ So here's how our example would go:
Also, send the same lines to gollum's administrator and ask him to add
them into his conf/gitolite.conf file, commit, and push.
<a name="_commands_to_re_sync_mirrors"></a>
#### commands to (re-)sync mirrors
### F=mirrsync commands to (re-)sync mirrors
You don't have to put all the slaves in `gitolite.mirror.slaves`. For
example, let's say you have some repos that are very active, and two of your
@ -450,13 +406,9 @@ are ways to do that:
want to know why their push errored out or didn't work last time or
whatever.
<a name="_details"></a>
## #ad/m-dtls details
### details
<a name="_the_conf_gitolite_conf_file"></a>
#### the `conf/gitolite.conf` file
### F=mirrconf the `conf/gitolite.conf` file
One goal I have is to minimise the code changes to "core" gitolite due to
this, so all repo-specific mirror settings are stored as `git config`
@ -491,9 +443,7 @@ config file right?). These are:
except they have to start with `gitolite.mirror.`. The section on
"commands to (re-)sync mirrors" has some examples.
<a name="_redirecting_pushes"></a>
### redirecting pushes
### F=mirrredirect redirecting pushes
**Please read carefully; there are security implications if you enable this
for mirrors NOT under your control**.
@ -550,15 +500,11 @@ There are some potential issues that you MUST consider before enabling this:
Ideally, I recommend that ad hoc repos not be mirrored at all. Keep
mirroring for "blessed" repos only.
<a name="_example_setups"></a>
## example setups
### example setups
Here are some samples of what is possible.
Here is a sample of what is possible.
<a name="_non_autonomous"></a>
#### non-autonomous
### F=mirrnonauto non-autonomous
In this setup, the slave server is under the same "management" as the master.
All repos, including gitolite-admin are mirrored, and *each slave is an exact
@ -585,9 +531,7 @@ redirected pushing if you wish:
repo @all
config gitolite.mirror.redirectOK = "true"
<a name="_non_autonomous_with_local_repos"></a>
#### non-autonomous with local repos
### F=mirrnonautolocal non-autonomous with local repos
As above, but you want to allow each slave server to have some repos be
"local" to the server (not be mirrored), for whatever reason. Different slaves
@ -613,9 +557,7 @@ That's it. When this config is pushed, each machine will have an effective
config that consists of the main file, with the correct HOSTNAME.conf included
(and all the others ignored) when the include statement is reached.
<a name="_semi_autonomous"></a>
#### semi-autonomous
### F=mirrsemiauto semi-autonomous
So far, the "central" admin still has control over the gitolite.conf file and
all repos created. Sometimes it's easier to give control over parts of the
@ -623,12 +565,10 @@ configuration to people at the mirror sites. To keep it simple, each admin
will be able to do whatever they want to directories within a subdirectory of
the same name as the hostname.
You can combine the "HOSTNAME" feature above with [delegation][deldoc]. Let's
You can combine the "HOSTNAME" feature above with [delegation][deleg]. Let's
say the admin for sam is a user called "gamgee", and the admin for gollum is
"smeagol".
[deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
Add this to your conf file:
@sam = sam/..*
@ -641,9 +581,7 @@ Now in the main config file, at the end (or wherever you wish), add one line:
subconf "HOSTNAME.conf"
<a name="_autonomous"></a>
#### autonomous
### F=mirrauto autonomous
In many ways this is the simplest setup.
@ -659,13 +597,9 @@ etc.)
Best for open source projects with heavy "fetch" load compared to "push".
<a name="_discussion"></a>
## F=mirrdisc discussion
### discussion
<a name="_problems_with_the_old_mirroring_model"></a>
#### problems with the old mirroring model
### problems with the old mirroring model
The old mirroring model had a single server as the master for *all*
repositories. Slaves were effectively only for load-balancing reads, or for
@ -689,9 +623,7 @@ as such:
* it implicitly assumed all the mirrors were under the same admin, and that
the gitolite-admin repo was itself mirrored too.
<a name="_the_new_mirroring_model"></a>
#### the new mirroring model
### the new mirroring model
In the new model, servers can be much more independent and autonomous than in
the old model. (Don't miss the side note in the 'repository level setup'
@ -736,11 +668,9 @@ repo).
in the side note somewhere up above, and just forget this feature exists
:-)
----
## appendices
<a name="_appendix_A_example_cronjob_based_mirroring"></a>
### appendix A: example cronjob based mirroring
### F=mirrcron appendix A: example cronjob based mirroring
Let's say you have some repos that are very active. You're pushing halfway
across the world every few seconds, but those slaves do not need to be that closely
@ -774,9 +704,7 @@ Then write a cron job that looks like this (untested).
sleep 10
done
<a name="_appendix_B_efficiency_versus_paranoia"></a>
### appendix B: efficiency versus paranoia
### F=mirrparanoia appendix B: efficiency versus paranoia
If you're paranoid enough to use mirrors, you should be paranoid enough to
use the `receive.fsckObjects` setting. However, informal tests indicate a
@ -790,9 +718,3 @@ gitolite.conf file:
Personally, I just set `git config --global receive.fsckObjects true`, since
those servers aren't doing anything else anyway, and are idle for long
stretches of time. It's upto you what you want to do here.
[ch]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_custom_hooks
[ha]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#_appendix_4_host_aliases
[rsgc]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
[vsi]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html#_variables_with_a_security_impact

2
doc/mob-branches.mkd
View file

@ -1,4 +1,4 @@
## mob branches in gitolite
# F=mob mob branches in gitolite
WARNING: This is hairy stuff. But what's life without a little danger?

62
doc/nagp.mkd
View file

@ -1,29 +1,10 @@
# ...not a gitolite problem!
# F=nagp ...not a gitolite problem!
Subtitle: Unix, ssh, git, and gitolite -- recognising the boundaries
**Warning**: Most of this is technical, but some of it is definitely
subjective opinion.
----
In this document:
* <a href="#_background">background</a>
* <a href="#_ssh">ssh</a>
* <a href="#_git">git</a>
* <a href="#_windows">windows</a>
* <a href="#_apple">apple</a>
* <a href="#_just_say_NO_">just say NO!</a>
* <a href="#_behind_my_back">behind my back</a>
* <a href="#_that_s_outrageous">that's outrageous</a>
----
<a name="_background"></a>
### background
More and more people are being tasked with creating a "server" environment for
git, (and thus being forcibly introduced to gitolite), before they've had a
chance to know git (or even Unix) well enough. As a result, I often get
@ -51,24 +32,16 @@ That might help with some of the problems described in this document.
[bare]: http://sitaramc.github.com/concepts/0-terminology.html#working_tree_repository_bare_repository
[sgs]: http://sitaramc.github.com/1-basic-usage/simple-git-session.html
<a name="_ssh"></a>
### ssh
## ssh
Let's get this out of the way first. The *superstar* of the "not a gitolite
problem" category is actually ssh.
Surprised? It is so common that it has [its own document][aa] to tell you why
it is *not* a gitolite problem, while [another one][sts] tries to help you
anyway!
Surprised? It is so common that it has [its own document][auth] to tell
you why it is *not* a gitolite problem, while [another one][sts] tries to
help you anyway!
[aa]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
[sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
[hc]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_hook_chaining
<a name="_git"></a>
### git
## git
* first push to a new repo
@ -110,14 +83,13 @@ anyway!
I don't know much about CI systems, but I'm pretty sure they run off of
some hook or other, but gitolite may already be using those hooks. The
section on hook chaining [here][hc] shows you how to run your own hooks.
section on hook chaining [here][hookchaining] shows you how to run your own
hooks.
In short, CI integration is no more a gitolite problem than any other
purpose for which git's hooks can be used.
<a name="_windows"></a>
### windows
## windows
I'm *interested* in making sure it works fine with Windows, simply because I
have colleagues at work who use it. But that doesn't mean I can help you; I
@ -129,9 +101,7 @@ God alone knows what else, so I know it *can* (be made to) work.
So, hang in there... it'll all work out eventually.
<a name="_apple"></a>
### apple
## apple
Weirdly enough, this is the one thing that Steve Ballmer and I probably agree
on, so I won't elaborate on that ;-)
@ -139,9 +109,7 @@ on, so I won't elaborate on that ;-)
It seems to me though, that many recent reports of "weird" behaviour reported
have come from Macs. Yet another reason for me to back off with an apology.
<a name="_just_say_NO_"></a>
### just say NO!
## just say NO!
These are the things I won't do, for various reasons, mostly technical, with a
smattering of some subjective stuff. If you've been hit by one of these, and
@ -200,9 +168,7 @@ the GPL, you can simply "fork off" ;-)
workable solution, I still would not do it. A server repo should be bare.
Period.
<a name="_behind_my_back"></a>
#### behind my back
### behind my back
Some of the "Just say NO" items are from situations where someone or something
changes stuff behind gitolite's back. I am particularly unsympathetic to this
@ -254,9 +220,7 @@ sort of thing.
</font>
<a name="_that_s_outrageous"></a>
### that's outrageous
## that's outrageous
This section is for really outrageous stuff.

57
doc/overkill.mkd
View file

@ -1,57 +0,0 @@
## when gitolite is overkill
Note: I wrote this to help people for whom gitolite is genuinely overkill. I
believe it will all work, but YMMV.
----
You don't always need something like gitolite. If you have a fixed (or very
rarely changing) number of users, and all of them have full access to all your
repos, you can use plain Unix permissions to get a lot of this done:
* dedicate a userid (say "git") to host all your repos. This user will also
have a group (normally called "git" on most distros I think)
* create a directory that is accessible (at least "r" and "x" permissions)
to the group "git", all the way upto the root. (That is, if the directory
you chose is /home/git/repos, then /, /home, /home/git, and
/home/git/repos must all be "g+rx").
* create all repos in this directory, as the "git" user, using the following
command:
git init --bare --shared reponame.git
* For each user who needs access to the repos, add them as members to the
"git" group also. On Fedora this is:
usermod -a -G git username
And that's basically it. The "init --shared" will create the repos with
"chmod -R g+s". If you have existing repos where you forgot (or didn't know)
the "--shared" argument, do this on each of them:
cd reponame.git
git init --shared --bare
chmod -R g+w .
chmod g+s `find . -type d`
I think that should do it.
Once you've setup the Unix level permissions, you may consider setting the
shell of some of the less experienced users to "git-shell" (using its full
path) if they don't really need a shell on the server. This will let them
access git remotely but not do anything else.
Combining this with settings like `receive.denyDeletes` and
`receive.denyNonFastForwards`, or at least `core.logAllRefUpdates`, can go a
long way toward preventing accidents or at least making it feasible to recover
from them.
----
You can do more complex things using Unix acls. If you do, and feel like
writing it up, send it to me and I will add it here (with credit given of
course). Personally, I can't be bothered -- once you have differing needs for
different people, you really need gitolite anyway, because you probably need
different rights for branches as well and Unix ACLs can't do that.

2
doc/packaging.mkd
View file

@ -1,4 +1,4 @@
## packaging gitolite
# F=packaging packaging gitolite
Here's how you'd package gitolite. In the following description, location "X"
can be, say, `/usr/share/gitolite/conf` or some such, and similarly location

34
doc/progit-article.mkd
View file

@ -1,17 +1,13 @@
# (master copy of progit chapter on gitolite)
# F=progit (master copy of progit chapter on gitolite)
## Gitolite ##
Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][gldpg]. The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with.
[gldpg]: http://sitaramc.github.com/gitolite/doc/progit-article.html
Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][progit]. The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with.
Git has started to become very popular in corporate environments, which tend to have some additional requirements in terms of access control. Gitolite was originally created to help with those requirements, but it turns out that it's equally useful in the open source world: the Fedora Project controls access to their package management repositories (over 10,000 of them!) using gitolite, and this is probably the largest gitolite installation anywhere too.
Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
<a name="_Installing_"></a>
### Installing ###
Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it. You need an account on a Unix server of some kind; various Linux flavours, and Solaris 10, have been tested. You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed. In the examples below, we will use the `gitolite` account on a host called `gitserver`.
@ -25,24 +21,17 @@ We will describe this last method in this article; for the other methods please
To begin, create a user called `git` on your server and login to this user. Copy your ssh pubkey (a file called `~/.ssh/id_rsa.pub` if you did a plain `ssh-keygen` with all the defaults) from your workstation, renaiming it to `YourName.pub`. Then run these commands:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
gitolite/src/gl-system-install
gl-setup -q ~/YourName.pub
# for example, I would run 'gl-setup -q ~/sitaram.pub'
Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation. You administer your gitolite setup by making changes to this repository and pushing. See [adding users and repos][aur] to start with.
[aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
<a name="_Customising_the_Install_"></a>
And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation. You administer your gitolite setup by making changes to this repository and pushing. See [adding users and repos][add] to start with.
### Customising the Install ###
While the default, quick, install works for most people, there are some ways to customise the install if you need to. If you omit the `-q` argument, an editor pops up with a file for you to edit, so you can change certain server-side parameters, such as the location of the actual repositories. This "rc" file is documented in [doc/gitolite.rc.mkd][rcdoc] so you should be able to make any changes you need quite easily, save it, and continue.
<a name="_Config_File_and_Access_Control_Rules_"></a>
While the default, quick, install works for most people, there are some ways to customise the install if you need to. If you omit the `-q` argument, an editor pops up with a file for you to edit, so you can change certain server-side parameters, such as the location of the actual repositories. This "rc" file is documented in [doc/gitolite.rc.mkd][rc] so you should be able to make any changes you need quite easily, save it, and continue.
### Config File and Access Control Rules ###
@ -58,7 +47,6 @@ Once the install is done, you switch to the `gitolite-admin` repository (placed
#gitolite conf
# please see doc/gitolite.conf.mkd for details on syntax and features
repo gitolite-admin
RW+ = sitaram
@ -67,7 +55,7 @@ Once the install is done, you switch to the `gitolite-admin` repository (placed
Notice that "sitaram" (the name of the pubkey in the gl-setup command you used earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
The config file syntax for gitolite is documented in [doc/gitolite.conf.mkd][confdoc] so we'll only mention some highlights here.
The config file syntax for gitolite is documented in [doc/gitolite.conf.mkd][conf] so we'll only mention some highlights here.
You can group users or repos for convenience. The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
@ -104,8 +92,6 @@ There are two levels of access control in gitolite. The first is at the reposit
The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied.
<a name="_Advanced_Access_Control_with_deny_rules_"></a>
### Advanced Access Control with "deny" rules ###
So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`. However, gitolite allows another permission: `-`, standing for "deny". This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
@ -130,8 +116,6 @@ You can also use deny rules to hide specific repos from people (or gitweb, or gi
See the documentation for more on this.
<a name="_Restricting_pushes_by_files_changed_"></a>
### Restricting pushes by files changed ###
In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch. For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*. You can tell gitolite:
@ -145,8 +129,6 @@ In addition to restricting what branches a user can push changes to, you can als
This powerful feature is documented in `conf/example.conf`.
<a name="_Personal_Branches_"></a>
### Personal Branches ###
Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment.
@ -157,14 +139,10 @@ This would normally cause the same branch name clutter as in a centralised VCS,
Gitolite lets you define a "personal" or "scratch" namespace prefix for each developer (for example, `refs/personal/<devname>/*`); see the "personal branches" section in `doc/3-faq-tips-etc.mkd` for details.
<a name="_Wildcard_repositories_"></a>
### "Wildcard" repositories ###
Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented in `doc/wildcard-repositories.mkd`.
<a name="_Other_Features_"></a>
### Other Features ###
We'll round off this discussion with a sampling of other features, all of which, and many more, are described in great detail in the "faqs, tips, etc" and other documents.

37
doc/report-output.mkd
View file

@ -1,22 +1,10 @@
# output of the "info" and "expand" commands
# F=info_expand output of the "info" and "expand" commands
Running "ssh git@server info" or "ssh git@server expand" gives you certain
output. This doclet describes the output; you're welcome to help me make it
clearer :)
In this document:
* <a href="#_the_info_command">the "info" command</a>
* <a href="#_interpreting_the_output">interpreting the output</a>
* <a href="#_using_patterns_to_limit_output">using patterns to limit output</a>
* <a href="#_side_note_openssh_5_6">side note: openssh 5.6</a>
* <a href="#_the_expand_command">the "expand" command</a>
----
<a name="_the_info_command"></a>
### the "info" command
## #info the "info" command
Usage:
@ -49,9 +37,7 @@ is often blank.
@R_ @W_ testing
R W vkc
<a name="_interpreting_the_output"></a>
#### interpreting the output
### interpreting the output
The meaning of C, R, and W are self-explanatory, but they may be prefixed or
suffixed by a symbol:
@ -74,9 +60,7 @@ suffixed by a symbol:
The `_` suffix is special. This says the user has only implicit access (due
to one of the `@all` uses), but no explicit access.
<a name="_using_patterns_to_limit_output"></a>
#### using patterns to limit output
### #limitoutput using patterns to limit output
Here are a couple of samples with optional patterns:
@ -95,17 +79,14 @@ Here are a couple of samples with optional patterns:
In "big-config" mode (i.e., when `GL_BIG_CONFIG` is set) the pattern is
**mandatory**. You can try and cheat the system by passing in a "." but
gitolite truncates the output after 20 results to prevent a DOS. (This limit
can be changed; see `$BIG_INFO_CAP` in [doc/gitolite.rc.mkd][rcdoc]).
[rcdoc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
can be changed; see `$BIG_INFO_CAP` in the documentation for
[`~/.gitolite.rc`][rc]).
The pattern is also mandatory when an admin wants to find out what access some
*other* user has, which you may have guessed from the syntax in the "usage"
line above.
<a name="_side_note_openssh_5_6"></a>
#### side note: openssh 5.6
### #openssh5.6 side note: openssh 5.6
It used to be that the gitolite documentation would say "just use `ssh
git@server`" in the past, because gitolite defaults to the "info" command if
@ -121,9 +102,7 @@ add the `-T` option to ssh (`ssh -T git@server`).
[openssh56]: http://www.openssh.org/txt/release-5.6
<a name="_the_expand_command"></a>
### the "expand" command
## #expand the "expand" command
Usage:

86
doc/shell-games.mkd
View file

@ -1,86 +0,0 @@
## avoiding the shell on the server
Gitolite now tries to prevent gitolite-admin push privileges from being used
to obtain a shell on the server. This was not always the case (older gitolite
did not make this distinction), but I've been moving towards this for a while
now, and, while there could still be holes in that separation, they will be
fixed as and when found.
Thus, settings that have security implications can be set only from the rc
file, which needs to be edited directly on the server. And adding a new hook
requires shell access anyway.
While this is great for my main target (corporate environments), some people
don't like it. They want to do all of this from the *gitolite-admin* repo,
because the security concern mentioned above does not bother them. They don't
want to log on to the server to make a change in the rc file or don't want to
run gl-setup to propagate a new set of hooks. In addition, they may want all
of these animals versioned in the "gitolite-admin" repo itself, which
certainly makes sense.
So here's how you might do that.
First, arrange to have all your special files added to the gitolite-admin
repo. The best option is to keep all of this in a single subdirectory (let's
call it "local" in our example). So your `~/.gitolite.rc` might go into
`local/gitolite.rc`, and all your local hooks into `local/hooks` etc. Add
them, commit, and push.
Note: do not create any top level directory called "conf", "contrib", "doc",
"hooks", or "src" -- those names are used by gitolite itself.
Second, create a `post-update.secondary` hook and place it in the *gitolite*
clone's `hooks/common` directory, containing the following code:
#!/bin/bash
[ "$GL_REPO" = "gitolite-admin" ] || exit 0
[ -z "$GL_RC" ] && { echo "ENV GL_RC not set"; exit 1; }
GL_ADMINDIR=`$GL_BINDIR/gl-query-rc GL_ADMINDIR`
cp $GL_ADMINDIR/local/gitolite.rc $HOME/.gitolite.rc
cp -a $GL_ADMINDIR/local/hooks/* $GL_ADMINDIR/hooks/common
/Full/Path/To/gl-install -q
# the path should be the same as that for gl-auth-command in the
# "command=" parameter of ~/.ssh/authorized_keys on the server
Don't forget to make it executable!
After this, run the upgrade instructions for the install method you used (just
as if the `post-update.secondary` file you just created came from a gitolite
software update).
All future changes to the rc file can be done via local/gitolite.rc in the
admin repo, and hooks can be added to local/hooks.
**Note**: One quirk of how gitolite [propagates hooks][hpd] is that now this
`post-update.secondary` exists in all normal repos also. Just ignore it; it's
not doing any harm.
[hpd]: http://sitaramc.github.com/gitolite/doc/hook-propagation.html
**Warning**: Nothing in gitolite *removes* hooks, so if you delete (or even
rename) a script, it still stays on the server -- you'll have to delete them
manually from the server.
----
So what's this actually doing?
Well, first, note that `$GL_ADMINDIR` contains files from both gitolite
itself, as well as from the gitolite-admin repo. "conf/VERSION", "src",
"doc", and "hooks" come from gitolite itself, while the other 2 files in
"conf", and all of "keydir" come from the gitolite-admin repo. ("logs"
doesn't come from anywhere).
In addition, any other files in the "master" branch of the gitolite-admin repo
get checked out here, which in this case would mean the entire "local/"
hierarchy you created above.
Now, since the "hooks/common" directory is coming from gitolite itself,
clearly this is where the internal "install" routine expects to find new or
updated hooks to propagate. So you just copy your local hooks (in the
"local/hooks" directory) to "hooks/common" and run the installer again. Done!

140
doc/ssh-troubleshooting.mkd
View file

@ -1,52 +1,20 @@
# ssh troubleshooting
----
# F=sts ssh troubleshooting
**This document must be read in full the first time. If you start from some
nice looking section in the middle it may not help you unless you're already
an expert at ssh**.
In this document:
* <a href="#_IMPORTANT_READ_THIS_FIRST">IMPORTANT -- READ THIS FIRST</a>
* <a href="#_caveats">caveats</a>
* <a href="#_naming_conventions_used">naming conventions used</a>
* <a href="#_taking_stock_relevant_files_and_directories">taking stock -- relevant files and directories</a>
* <a href="#_normal_gitolite_key_handling">normal gitolite key handling</a>
* <a href="#_Other_resources_">(Other resources)</a>
* <a href="#_common_problems">common problems</a>
* <a href="#_step_by_step">step by step</a>
* <a href="#_random_tips_tricks_and_notes">random tips, tricks, and notes</a>
* <a href="#_giving_shell_access_to_gitolite_users">giving shell access to gitolite users</a>
* <a href="#_losing_your_admin_key">losing your admin key</a>
* <a href="#_simulating_ssh_copy_id">simulating ssh-copy-id</a>
* <a href="#_problems_with_using_non_openssh_public_keys">problems with using non-openssh public keys</a>
* <a href="#_windows_issues">windows issues</a>
* <a href="#_appendix_1_ssh_daemon_asks_for_a_password">appendix 1: ssh daemon asks for a password</a>
* <a href="#_appendix_2_which_key_is_which_running_sshkeys_lint">appendix 2: which key is which -- running sshkeys-lint</a>
* <a href="#_typical_cause_s_">typical cause(s)</a>
* <a href="#_appendix_3_ssh_client_may_not_be_offering_the_right_key">appendix 3: ssh client may not be offering the right key</a>
* <a href="#_appendix_4_host_aliases">appendix 4: host aliases</a>
* <a href="#_appendix_5_why_bypassing_gitolite_causes_a_problem">appendix 5: why bypassing gitolite causes a problem</a>
----
This document should help you troubleshoot ssh-related problems in installing
and accessing gitolite.
<a name="_IMPORTANT_READ_THIS_FIRST"></a>
## IMPORTANT -- READ THIS FIRST
### IMPORTANT -- READ THIS FIRST
<a name="_caveats"></a>
#### caveats
### caveats
* Before reading this document, it is **mandatory** to read and **completely
understand** [doc/gitolite-and-ssh.mkd][doc9gas], which is a very detailed
look at how gitolite uses ssh's features on the server side. Don't assume
you know all that; if you knew it, you wouldn't be needing *this* document
either!
understand** [this][gl_ssh], which is a very detailed look at how gitolite
uses ssh's features on the server side. Don't assume you know all that;
if you knew it, you wouldn't be needing *this* document either!
* This document, and others linked from this, together comprise all the help
I can give you in terms of the ssh aspect of using gitolite. If you're
@ -58,13 +26,9 @@ and accessing gitolite.
rather spend time on actual gitolite features, code, and documentation
than authentication (i.e., ssh, in the common case).
Surprised? [This][wo] might help explain better.
Surprised? [This][auth] might help explain better.
----
<a name="_naming_conventions_used"></a>
#### naming conventions used
### naming conventions used
* Your workstation is the **client**. Your userid on the client does not
matter, and it has no relation to your gitolite username.
@ -73,9 +37,7 @@ and accessing gitolite.
this is an RPM/DEB install, the hosting user is probably called
"gitolite", however we will use "git" in this document.
<a name="_taking_stock_relevant_files_and_directories"></a>
#### taking stock -- relevant files and directories
### taking stock -- relevant files and directories
* the client has a `~/.ssh` containing a few keypairs. It may also have a
`config` file.
@ -92,9 +54,7 @@ and accessing gitolite.
* the server also has a `~/.gitolite/keydir` which contains a bunch of
`*.pub` files.
<a name="_normal_gitolite_key_handling"></a>
#### normal gitolite key handling
### normal gitolite key handling
Here's how normal gitolite key handling works:
@ -120,16 +80,12 @@ Here's how normal gitolite key handling works:
between gitolite's "marker" lines (`# gitolite start` and `# gitolite
end`).
<a name="_Other_resources_"></a>
### (Other resources)
## (Other resources)
People who think installing gitolite is too hard should take a look at this
[tutorial][tut] to **see how simple it *actually* is**.
<a name="_common_problems"></a>
### common problems
## common ssh problems
Since I'm pretty sure at least some of you didn't bother to read the
"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -169,9 +125,7 @@ the rest in sequence. Appendix 5 has some background info.
does not appear to be a git repository`, and yet you are sure 'reponame'
exists, you haven't mis-spelled it, etc.
<a name="_step_by_step"></a>
### step by step
## step by step
Since I'm pretty sure at least some of you didn't bother to read the
"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -193,13 +147,9 @@ Done? OK, now the general outline for ssh troubleshooting is this:
need to make sure that this specific key is being offered/sent by the
client, instead of the default key. See appendix 3 and 4.
<a name="_random_tips_tricks_and_notes"></a>
## random tips, tricks, and notes
### random tips, tricks, and notes
<a name="_giving_shell_access_to_gitolite_users"></a>
#### giving shell access to gitolite users
### giving shell access to gitolite users
We've managed (thanks to an idea from Jesse Keating) to make it possible for a
single key to allow both gitolite access *and* shell access.
@ -216,20 +166,14 @@ access would not manage to get himself shell access.
Giving someone shell access requires that you should have shell access in the
first place, so the simplest way is to enable it from the server side only.
<a name="_losing_your_admin_key"></a>
#### losing your admin key
### losing your admin key
If you lost the admin key, and need to re-establish ownership of the
gitolite-admin repository with a fresh key, get a shell on the server and use
the program called `gl-admin-push` that comes with gitolite. See instructions
[here][gssp].
[here][adminpush].
[gssp]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo
<a name="_simulating_ssh_copy_id"></a>
#### simulating ssh-copy-id
### simulating ssh-copy-id
don't have `ssh-copy-id`? This is broadly what that command does, if you want
to replicate it manually. The input is your pubkey, typically
@ -252,9 +196,7 @@ typically) also must be `go-w`, but that needs root. And typically
they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)]
<a name="_problems_with_using_non_openssh_public_keys"></a>
#### problems with using non-openssh public keys
### problems with using non-openssh public keys
Gitolite accepts public keys only in openssh format. Trying to use an "ssh2"
key (used by proprietary SSH software) results in:
@ -267,9 +209,7 @@ To convert ssh2-compatible keys to openssh run:
then use the resulting pubkey as you normally would in gitolite.
<a name="_windows_issues"></a>
#### windows issues
### windows issues
On windows, I have only used msysgit, and the openssh that comes with it.
Over time, I have grown to distrust putty/plink due to the number of people
@ -278,13 +218,9 @@ used them for any kind of git access). If you have unusual ssh problems that
just don't seem to have any explanation, try removing all traces of
putty/plink, including environment variables, etc., and then try again.
Thankfully, someone contributed [contrib/putty.mkd][putty].
Thankfully, someone contributed [contrib/putty.mkd][contrib_putty].
----
<a name="_appendix_1_ssh_daemon_asks_for_a_password"></a>
### appendix 1: ssh daemon asks for a password
## appendix 1: ssh daemon asks for a password
> **NOTE**: This section should be useful to anyone trying to get
> password-less access working. It is not necessarily specific to gitolite,
@ -352,9 +288,7 @@ This is a quick checklist:
this file for messages matching the approximate time of your last attempt
to login, to see if they tell you what is the problem.
<a name="_appendix_2_which_key_is_which_running_sshkeys_lint"></a>
### appendix 2: which key is which -- running sshkeys-lint
## appendix 2: which key is which -- running sshkeys-lint
Follow these steps on the client:
@ -389,9 +323,7 @@ need. Be careful:
* if you're running ssh-agent, you may have to delete (using `ssh-add -D`)
and re-add identities for it to pick up the renamed ones correctly
<a name="_typical_cause_s_"></a>
#### typical cause(s)
### typical cause(s)
The admin often has passwordless shell access to `git@server` already, and
then used that same key to get access to gitolite (i.e., copied that same
@ -407,9 +339,7 @@ as YourName.pub, then run `gl-setup YourName.pub` on the server. Remember to
adjust your agent identities using ssh-add -D and ssh-add if you're using
ssh-agent, otherwise these new keys may not work.
<a name="_appendix_3_ssh_client_may_not_be_offering_the_right_key"></a>
### appendix 3: ssh client may not be offering the right key
## appendix 3: ssh client may not be offering the right key
* make sure the right private key is being offered. Run ssh in very
verbose mode and look for the word "Offering", like so:
@ -431,9 +361,7 @@ ssh-agent, otherwise these new keys may not work.
In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
the access again.
<a name="_appendix_4_host_aliases"></a>
### appendix 4: host aliases
## F=sshhostaliases appendix 4: host aliases
(or "making git use the right options for ssh")
@ -467,23 +395,9 @@ If you have *more than one* pubkey with access to the *same* server, you
**must** use this method to make git pick up the right key. There is no other
way to do this, as far as I know.
----
[doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
[install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
[o3]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#methods
[fc]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#fc
[urls]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#URLs_for_gitolite_managed_repos
[repout]: http://sitaramc.github.com/gitolite/doc/report-output.html
[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[openssh56]: http://www.openssh.org/txt/release-5.6
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
[wo]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
[putty]: http://sitaramc.github.com/gitolite/contrib/putty.html
<a name="_appendix_5_why_bypassing_gitolite_causes_a_problem"></a>
### appendix 5: why bypassing gitolite causes a problem
## appendix 5: why bypassing gitolite causes a problem
When you bypass gitolite, you end up running your normal shell instead of the
special gitolite entry point script `gl-auth-command`.

280
doc/3-faq-tips-etc.mkd → doc/tips-notes.mkd
View file

@ -1,47 +1,6 @@
# assorted faqs, tips, and notes on gitolite
# F=tips assorted tips and notes
In this document:
* <a href="#_common_errors_and_mistakes">common errors and mistakes</a>
* <a href="#_other_errors_warnings_notes_">other errors, warnings, notes...</a>
* <a href="#_cloning_an_empty_repo">cloning an empty repo</a>
* <a href="#_all_syntax_for_repos">`@all` syntax for repos</a>
* <a href="#_features">features</a>
* <a href="#_syntax_and_normal_usage">syntax and normal usage</a>
* <a href="#_one_user_many_keys">one user, many keys</a>
* <a href="#_security_access_control_and_auditing">security, access control, and auditing</a>
* <a href="#_two_levels_of_access_rights_checking">two levels of access rights checking</a>
* <a href="#_better_logging">better logging</a>
* <a href="#_delegating_parts_of_the_config_file">delegating parts of the config file</a>
* <a href="#_convenience_features">convenience features</a>
* <a href="#_what_repos_do_I_have_access_to_">what repos do I have access to?</a>
* <a href="#_support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
* <a href="#_personal_branches">"personal" branches</a>
* <a href="#_custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
* <a href="#_bypassing_gitolite">bypassing gitolite</a>
* <a href="#_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo">gl-admin-push: bypassing gitolite for the gitolite-admin repo</a>
* <a href="#_disabling_write_access_to_take_backups">disabling write access to take backups</a>
* <a href="#_INconvenience_features">INconvenience features</a>
* <a href="#_deleting_a_repo">deleting a repo</a>
* <a href="#_renaming_a_repo">renaming a repo</a>
* <a href="#_helping_with_gitweb">helping with gitweb</a>
* <a href="#_easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
* <a href="#_umask_setting">umask setting</a>
* <a href="#_advanced_features">advanced features</a>
* <a href="#_repos_named_with_wildcards">repos named with wildcards</a>
* <a href="#_admin_defined_commands">admin defined commands</a>
* <a href="#_access_control_for_external_commands">access control for external commands</a>
* <a href="#_svnserve">svnserve</a>
* <a href="#_odds_and_ends">odds and ends</a>
* <a href="#_poking_the_admin_repo_to_force_a_compile">"poking" the admin repo to force a compile</a>
* <a href="#_design_choices">design choices</a>
* <a href="#_keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
----
<a name="_common_errors_and_mistakes"></a>
### common errors and mistakes
## common errors and mistakes
* adding `repositories/` at the start of the repo name in the `git clone`.
This error is typically made by the *admin* himself -- because he knows
@ -63,13 +22,9 @@ In this document:
Please see doc/ssh-troubleshooting.mkd for what all this means.
<a name="_other_errors_warnings_notes_"></a>
## other errors, warnings, notes...
### other errors, warnings, notes...
<a name="_cloning_an_empty_repo"></a>
#### cloning an empty repo
### cloning an empty repo
Cloning an empty repo is only possible with clients greater than 1.6.2. So at
least one of your clients needs to have a recent git. Once at least one
@ -80,9 +35,7 @@ end hung up unexpectedly`. However, you can ignore this, since it doesn't
seem to hurt anything. [Update 2009-09-14; this has been fixed in git
1.6.4.3]
<a name="_all_syntax_for_repos"></a>
#### `@all` syntax for repos
### `@all` syntax for repos
There *is* a way to use the `@all` syntax for repos also, as described in
`doc/gitolite.conf.mkd`. However, there are a couple of minor cautions:
@ -91,23 +44,15 @@ There *is* a way to use the `@all` syntax for repos also, as described in
the potential for defeating a crucial optimisation and slowing down *all*
access, we do not support this.
<a name="_features"></a>
### features
## features
Apart from the big ones listed in the top level README, and subjective ones
like "better config file format", gitolite has evolved to have many useful
features than the original goal of branch-level access control.
<a name="_syntax_and_normal_usage"></a>
### syntax and normal usage
#### syntax and normal usage
<a name="multikeys"></a>
<a name="_one_user_many_keys"></a>
##### one user, many keys
#### #multikey one user, many keys
If you have a user who has more than one pubkey (like from different machines)
the simplest way to deal with it is to add subdirectories and add keys there.
@ -117,13 +62,14 @@ For example, I might have these files in `keydir/`:
home/sitaram.pub
laptop/sitaram.pub
<font color="gray">
##### F=oldmultikeys old style multi keys
The older method will continue to work, simply because I prefer it. But I am
not going to document it except for the example below, nor am I going to
support it in terms of questions. Sorry. Apparently it was too complex to
understand, even for some smart folks I know. This tells me it was probably
ill thought out and should have been obsoleted as soon as e0fe73a was pushed.
This is an older method of enabling multi-keys. It will continue to work and
be supported in *code*, simply because I prefer it. But I am not going to
document it except for the example below, nor am I going to support it in
terms of questions. Sorry. Apparently it was too complex to understand, even
for some smart folks I know. This tells me it was probably ill thought out
and should have been obsoleted as soon as e0fe73a was pushed.
Anyway, here's *all* the documentation for it -- some sample pubkey filenames
and the corresponding derived usernames:
@ -146,15 +92,9 @@ and the corresponding derived usernames:
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
</font>
### F=_tipssec security, access control, and auditing
<a name="_security_access_control_and_auditing"></a>
#### security, access control, and auditing
<a name="_two_levels_of_access_rights_checking"></a>
##### two levels of access rights checking
#### #2levels two levels of access rights checking
Gitolite has two levels of access checks. The **first check** is what I will
call the **pre-git** level. At this stage, the `gl-auth-command` has been
@ -189,9 +129,7 @@ any of the refexes match, the push succeeds. If none of them match, it fails.
Gitolite also allows "exclude" or "deny" rules. See later in this document
for details.
<a name="_better_logging"></a>
##### better logging
#### better logging
If you have been too liberal with the permission to rewind, it has built-in
logging as an emergency fallback if someone goes too far, or for audit
@ -217,31 +155,23 @@ The other parts of the log line are the name of the repo, the refname being
updated, the user updating it, and the refex pattern (from the config file)
that matched, in case you need to debug the config file itself.
<a name="_delegating_parts_of_the_config_file"></a>
##### delegating parts of the config file
#### delegating parts of the config file
You can now split up the config file and delegate the authority to specify
access control for their own pieces. See [delegation][] for details.
access control for their own pieces. See [delegation][deleg] for details.
<a name="_convenience_features"></a>
### F=_tnconv convenience features
#### convenience features
<a name="_what_repos_do_I_have_access_to_"></a>
##### what repos do I have access to?
#### what repos do I have access to?
Sometimes there are too many repos, maybe even named similarly, or with the
potential for typos, confusion about hyphens/underscores or upper/lower case,
etc. You'd just like a simple way to know what repos you have access to.
Gitolite provides two commands (`info` and `expand`) to help you find this
information; please check [doc/report-output.mkd][repout] for details.
Gitolite provides two commands ([`info`][info] and [`expand`][expand])
to help you find this information.
<a name="_support_for_git_installed_outside_default_PATH"></a>
##### support for git installed outside default PATH
#### support for git installed outside default PATH
The normal solution is to add to the system default PATH somehow, either by
munging `/etc/profile` or by enabling `PermitUserEnvironment` in
@ -273,9 +203,7 @@ the full PATH in the rc file, like so:
$ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
<a name="_personal_branches"></a>
##### "personal" branches
#### #pers "personal" branches
"personal" branches are great for corporate environments, where
unauthenticated pull/clone is a no-no. Since a dev workstation cannot do
@ -283,31 +211,26 @@ authentication, even work shared just between 2 devs has to go *via* the
server. This causes the same branch name clutter as in a centralised VCS,
plus setting up permissions for this becomes a chore for the admin.
gitolite lets you define a "personal" or "scratch" namespace prefix for each
developer (e.g., `refs/personal/<devname>/*`). Just add a line like:
Personal branches exist **in a namespace** of their own. The syntax is
RW+ personal/USER/ = @userlist
RW+ personal/USER/ = @userlist
This means I (user "sitaram") can do anything to any branch whose name starts
with `personal/sitaram/` assuming I'm in "userlist".
where the "personal" can be anything you like (but cannot be empty), and the
"/USER/" part is **necessary (including both slashes)**. A user "alice" (if
she's in the userlist) can then push any branches inside `personal/alice/`.
Which means she can push `personal/alice/foo` and `personal/alice/bar`, but
NOT `personal/alice`.
You can have any number of such lines with different prefixes (for example,
using topic names instead of "personal") or even suffixes if you like. The
important thing is that the "branch" name should contain `/USER/` (including
the slashes). At runtime this will match whoever is the current user. Access
is still determined by the right hand side of course.
(Background: at runtime the "USER" component will be replaced by the name of
the invoking user. Access is determined by the right hand side, as usual).
<a name="_custom_hooks_and_custom_git_config"></a>
##### custom hooks and custom git config
#### custom hooks and custom git config
You can specify hooks that you want to propagate to all repos, as well as
per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
`doc/gitolite.conf.mkd` for details.
<a name="_bypassing_gitolite"></a>
##### bypassing gitolite
#### bypassing gitolite
Sometimes you'll need to access one of the gitolite-managed repos directly on
the server, without going through gitolite. Reasons may be some automatic
@ -328,9 +251,7 @@ to set that variable permanently, preferring this mode instead:
GL_BYPASS_UPDATE_HOOK=1 git push
<a name="_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo"></a>
##### gl-admin-push: bypassing gitolite for the gitolite-admin repo
#### F=adminpush gl-admin-push: bypassing gitolite for the gitolite-admin repo
The method described in the previous section (setting `GL_BYPASS_UPDATE_HOOK`)
will work for all the repos managed by gitolite, **except** for the special
@ -360,9 +281,7 @@ the server. Here's how:
Note that this method will work for *any* repo, not just the special admin
repo.
<a name="_disabling_write_access_to_take_backups"></a>
##### disabling write access to take backups
#### #disable disabling write access to take backups
If you want to take normal, OS-level, backups of the system, you might want
git to be quiescent during that time, so that the backup is clean. The best
@ -387,17 +306,13 @@ I leave it to you to
that no push is *in progress* by checking for any `git-receive-pack`
processes in a `ps` output.
<a name="_INconvenience_features"></a>
### INconvenience features
#### INconvenience features
<a name="_deleting_a_repo"></a>
##### deleting a repo
#### #repodel deleting a repo
By design, there is no code in gitolite to *delete* a repo if the repo was
specified by name in the config file. (Wildcard repos *can* be deleted by the
user; see [here][rmrepo] for details).
user; see [here][wild_repodel] for details).
If you *do* want to permanently delete a *non*-wildcard repo, here's what you
do:
@ -408,9 +323,7 @@ do:
* *then* remove the repo from `~/repositories` on the server (or whatever
you set `$REPO_BASE` to in the `~/.gitolite.rc`)
<a name="_renaming_a_repo"></a>
##### renaming a repo
#### renaming a repo
This is similar; there's no code to do this in gitolite. What you do is:
@ -422,9 +335,7 @@ This is similar; there's no code to do this in gitolite. What you do is:
The order of these 2 steps is important; do not reverse them :-)
<a name="_helping_with_gitweb"></a>
#### helping with gitweb
### helping with gitweb
Although gitweb is a completely separate program, gitolite can do quite a
lot to help you manage gitweb access as well; once the initial setup is
@ -433,11 +344,7 @@ complete, you can do it all from within the gitolite config file!
If you just want gitweb to show some repositories, see [here][gwd] for how to
specify which repos to show.
[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
<a name="_easier_to_link_gitweb_authorisation_with_gitolite"></a>
##### easier to link gitweb authorisation with gitolite
#### #gitwebauth easier to link gitweb authorisation with gitolite
Over and above whether a repo is even *shown* by gitweb, you may want to
further restrict people, allowing them to view *only* those repos for which
@ -471,74 +378,27 @@ Gitweb allows you to specify a subroutine to decide on access. We use that
feature and tie it to gitolite. Configuration example can be found in
`contrib/gitweb/`.
<a name="_umask_setting"></a>
##### umask setting
#### #umask umask setting
Gitweb not able to read your repos? You can change the umask for newly
created repos to something more relaxed -- see the `REPO_UMASK` setting in the [`~/.gitolite.rc`][rc] file.
created repos to something more relaxed -- see the `REPO_UMASK` setting in the
[rc file documentation][rc].
[rc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
### advanced features
<a name="_advanced_features"></a>
There are some really cool features that are now in pretty wide use.
#### advanced features
* **[repos named with wildcards][wild]** is useful when some or most of your
repos fit a pattern, avoiding the need to name repos individually in the
config file. New repos matching the pattern can be created by any user
(if you give them rights to), with a set of permissions assigned to
"roles", and the creator can then place users into those roles.
<a name="_repos_named_with_wildcards"></a>
##### repos named with wildcards
Please see `doc/wildcard-repositories.mkd` for all the details.
<a name="_admin_defined_commands"></a>
##### admin defined commands
This requires the wildcards feature to be enabled, but is then an extremely
powerful feature. See `doc/admin-defined-commands.mkd`.
<a name="_access_control_for_external_commands"></a>
##### access control for external commands
Gitolite now has a mechanism for allowing access control for arbitrary
external commands, as long as they are invoked via ssh and present a
server-side command that contains enough information to make an access control
decision.
Note that this is incompatible with giving people shell access as described in
`doc/ssh-troubleshooting.mkd` -- people who have shell access are not
subject to this mechanism (it wouldn't make sense to try and control someone
who has shell access anyway).
In general, external commands require changes in one or both the config files;
the sample files in `conf/` double as documentation, so you should look there
for examples and usage.
Commands implemented so far are:
* rsync
* svnserve (see next section for a brief description; this has been
contributed by Simon and Vladimir)
<a name="_svnserve"></a>
###### svnserve
If you are transitioning from SVN to gitolite, and have a lot of users using
public-key authentication with SVN, this feature may be useful to you. Once
you migrate all users' public keys into gitolite, you can set the `$SVNSERVE`
variable in `~/.gitolite.rc` to tie `svnserve` with gitolite's authentication
system. Assuming you installed gitolite to the same user as the one you used
for SVN, SVN connectivity will be retained, and users will be able to use
both SVN and git using the same SSH configuration.
<a name="_odds_and_ends"></a>
* **[admin defined commands][ADCs]** allow controlled access to specific
commands and scripts without giving users full shell access.
### odds and ends
<a name="_poking_the_admin_repo_to_force_a_compile"></a>
#### "poking" the admin repo to force a compile
Sometimes you need to force a compile, as if you pushed the gitolite-admin
@ -549,29 +409,3 @@ repo. I have a git alias that looks like this:
so I just run `git poke`. This toggles between deleting and creating a dummy
branch called "poke". Either operation will trigger the hooks.
<a name="_design_choices"></a>
### design choices
<a name="_keeping_the_parser_and_the_access_control_separate"></a>
#### keeping the parser and the access control separate
There are two programs concerned with access control:
* `gl-auth-command`, the program that is run via `~/.ssh/authorized_keys`;
this decides whether git should even be allowed to run (basic R/W/no
access). (This one cannot decide on the branch-level access; it is not
known at this point what branch is being accessed)
* the update-hook on each repo, which decides the per-branch permissions
I have chosen to keep the relatively complex task of parsing the config file
out of them to keep them simpler (and faster). So any changes to the config
have to be first "compiled", and the access control programs use this
"compiled" version of the config. (The compile step also refreshes
`~/.ssh/authorized_keys`).
[repout]: http://sitaramc.github.com/gitolite/doc/report-output.html
[delegation]: http://sitaramc.github.com/gitolite/doc/delegation.html
[rmrepo]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#rmrepo

67
doc/uninstall.mkd
View file

@ -1,67 +0,0 @@
## uninstalling gitolite
Sometimes you might find gitolite is overkill -- you have only one user
(yourself) pushing maybe. Or maybe gitolite is just not enough -- you want a
web-based front end that users can use to manage their keys themselves, etc.,
in which case you'd probably switch to [github][g1], [girocco][g2],
[indefero][g3] or [gitorious][g4]. [Gerrit][g5] is quite nice too, if you
want collaborative code review there's nothing like it. Either way, you'd
like to uninstall gitolite.
[g1]: http://github.com
[g2]: http://repo.or.cz/w/girocco.git
[g3]: http://www.indefero.net/
[g4]: http://gitorious.com/
[g5]: http://code.google.com/p/gerrit/
Uninstalling gitolite is fairly easy, although it is manual. (We'll assume
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
not, adjust accordingly):
**server side tasks**
* edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
gitolite end` markers and all the lines between them. This will prevent
any of your users from attempting a push while you are doing this.
If you are the only user, and/or *need* one or more of those keys to
continue to access this account (like if one of them is your laptop or
your home desktop etc.) then instead of deleting the line you can just
delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
* Now remove (or move aside or rename to something else if you're paranoid)
the following files and directories.
~/.gitolite
~/.gitolite.rc
~/repositories/gitolite-admin.git
* You can remove all of `~/repositories` if you have not really started
using gitolite properly yet; that's your choice.
If you *do* need to preserve the other repos and continue to use them,
remove all the `update` hooks that git installs on each repository. The
easiest way is:
find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
but you can do it manually if you want to be careful.
**client side tasks**
* Any remote users that still have access must update their clone's remote
URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
actual path used, in order for the remote to still work. This is because
you'll now be accessing it through plain ssh, which means you have to give
it the full path.
* Finally, you as the gitolite admin will probably have a host stanza for
"gitolite" in your *client*'s `~/.ssh/config`. Find and delete lines that
look like this:
host gitolite
user git
hostname your.server
port 22
identityfile ~/.ssh/your-gitolite-admin-username

92
doc/user-manual.mkd → doc/user.mkd
View file

@ -1,4 +1,4 @@
# what users (not admins) need to know about gitolite
# F=user what users (not admins) need to know about gitolite
...written for the one guy in the world no one will think of as "just a normal
user" ;-)
@ -7,22 +7,7 @@ This document has some text, and a lot of links. Most of this info *is*
available in the rest of the documentation, but it's scattered and sparse.
Collecting all of it, or at least links to it, in one place sounds useful.
In this document:
* <a href="#_accessing_gitolite">accessing gitolite</a>
* <a href="#_always_available_commands">always available commands</a>
* <a href="#_digression_two_kinds_of_repos">digression: two kinds of repos</a>
* <a href="#_commands_only_available_with_wildrepos_on">commands only available with "wildrepos" on</a>
* <a href="#_listing_repos_you_created">listing repos you created</a>
* <a href="#_set_get_additional_permissions_for_repos_you_created">set/get additional permissions for repos you created</a>
* <a href="#_adding_a_description_to_repos_you_created">adding a description to repos you created</a>
* <a href="#_site_local_commands">"site-local" commands</a>
----
<a name="_accessing_gitolite"></a>
### accessing gitolite
## accessing gitolite
The most common setup is based on ssh, where your admin asks you to send him
your public key, and uses that to setup your access.
@ -34,9 +19,7 @@ document), or an ssh command (like `ssh git@server info`).
Note that you do *not* get a shell on the server -- the whole point of
gitolite is to prevent that!
<a name="_always_available_commands"></a>
### always available commands
## always available commands
The only command that is *always* available to every user is the [`info`
command][info], which tells you what version of gitolite and git are on the
@ -44,48 +27,36 @@ server, and what repositories you have access to. The list of repos is very
useful if you have doubts about the spelling of some new repo that you know
was setup.
[info]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_info_command
<a name="_digression_two_kinds_of_repos"></a>
### digression: two kinds of repos
## digression: two kinds of repos
Gitolite has two kinds of repos. Normal repos are specified by their full
names in the config file. "Wildcard" repos are specified by a regex in the
config file. If you look at the documentation on the [`info` command][info]
you will see there are a couple of lines that look like regex patterns,
against which you see an additional "C" permission not available with the
others.
config file. Try the [`info` command][info] and see if it shows any lines
that look like regex patterns, (with a "C" permission in addition to the "R"
and the "W").
This means you are allowed to create brand new repos whose names fit that
pattern. When you create such a repo, your "ownership" of it (as far as
gitolite is concerned) is noted by creating a 1-line file called "gl-creater"
(note spelling!) in the repo directory, with just your gitolite userid in it.
If you see any, it means you are allowed to create brand new repos whose names
fit that pattern. When you create such a repo, your "ownership" of it (as far
as gitolite is concerned) is *automatically* recorded by creating a 1-line
file called "gl-creater" (note spelling!) in the repo directory, with just
your gitolite userid in it.
This happens automatically. But for repos that were migrated into gitolite
and whose names fit a pattern, the admin has to manually create those files,
otherwise you won't be able to execute certain commands that you otherwise
might have access to.
This is for new repos you create. But for repos that already existed and were
migrated into gitolite by the admin, the admin has to manually create that
"gl-creater" file, otherwise you won't be able to execute certain commands
that you otherwise might have access to.
"Wildrepos" is an optional feature of gitolite that the admin has to "turn
on".
"Wildrepos" is an optional feature of gitolite that the admin has to
explicitly enable.
<a name="_commands_only_available_with_wildrepos_on"></a>
## commands only available with "wildrepos" on
### commands only available with "wildrepos" on
<a name="_listing_repos_you_created"></a>
#### listing repos you created
### listing repos you created
The info command will not show you your own wildcard repos. To get that list,
try the [`expand` command][expand].
[expand]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_expand_command
<a name="_set_get_additional_permissions_for_repos_you_created"></a>
#### set/get additional permissions for repos you created
### set/get additional permissions for repos you created
The gitolite config may have several permissions lines for your repo, like so:
@ -120,11 +91,7 @@ given read access to the special 'gitolite-admin' repo. Sorry. The idea is
that your admin will tell you what "roles" he added into rules for your repos,
and what permissions those roles have.
[setperms]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html#_handing_out_rights_to_wildcard_matched_repos
<a name="_adding_a_description_to_repos_you_created"></a>
#### adding a description to repos you created
### #setdesc adding a description to repos you created
The `setdesc` and `getdesc` commands work similarly to the `setperms` and
`getperms` commands. You just say
@ -135,9 +102,7 @@ and if you want to check you just say
ssh git@server getdesc pub/<yourname>/<your_reponame>
<a name="_site_local_commands"></a>
### "site-local" commands
## "site-local" commands
The main purpose of gitolite is to prevent you from getting a shell. But
there are commands that you often need to run on the server (i.e., cannot be
@ -151,10 +116,9 @@ starting point for his own, if he chooses.
Think of these commands as equivalent to those in `COMMAND_DIR` in `man
git-shell`.
Most of the shipped ADCs are briefly described [here][ADCs], with links to
more details if available. However, **please understand** that these commands
may not be available, or their behaviour may have been changed to suit local
requirements, and of course new ones may have been added. You'll have to ask
your local admin for answers, not me!
Most of the shipped ADCs are briefly described [here][shipped_ADCs], with links
to more details if available. However, **please understand** that these
commands may not be available, or their behaviour may have been changed to
suit local requirements, and of course new ones may have been added. You'll
have to ask your local admin for answers, not me!
[ADCs]: http://sitaramc.github.com/gitolite/contrib/adc/README.html

4
doc/who-uses-it.mkd
View file

@ -1,4 +1,4 @@
# who uses gitolite
# F=who who uses gitolite
> > If you're using gitolite and find it very useful in some way, I would
> > love to describe your use of it or add a link to your own description
@ -12,7 +12,6 @@ for them (their config file was so big that without the big-config changes
gitolite would just run out of memory and die!).
[fedora]: http://lists.fedoraproject.org/pipermail/devel-announce/2010-July/000647.html
[bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
The **KDE project** [uses][kde] gitolite (in combination with redmine for
issue tracking and reviewboard for code review). Apart from the usual access
@ -39,7 +38,6 @@ little one-man show!
He explains his use of it [here][hiren].
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
[hiren]: http://ece.uwaterloo.ca/~hdpatel/uwhtml/wildrepos-in-gitolite/
**Gentoo Linux** has [just moved][gentoo1] their git repositories from gitosis

100
doc/wildcard-repositories.mkd
View file

@ -1,4 +1,4 @@
## repositories named with wildcards
# F=wild repositories named with wildcards
***IMPORTANT NOTE***:
@ -10,33 +10,11 @@ I haven't found any yet, but that doesn't mean there aren't any.
----
In this document:
* <a href="#_quick_introduction">quick introduction</a>
* <a href="#_rc_file_setting_required">rc file setting required</a>
* <a href="#_examples_of_wildcard_repos">examples of wildcard repos</a>
* <a href="#_wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
* <a href="#_wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
* <a href="#_side_note_valid_regexes">side-note: valid regexes</a>
* <a href="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
* <a href="#_contrast_with_refexes">contrast with refexes</a>
* <a href="#_handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
* <a href="#_admin_adding_other_roles_than_READERS_and_WRITERS">(admin) adding other roles than READERS and WRITERS</a>
* <a href="#_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_">**IMPORTANT WARNING ABOUT THIS FEATURE**</a>
* <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#_reporting">reporting</a>
* <a href="#_deleting_a_wild_repo">deleting a wild repo</a>
* <a href="#_how_it_actually_works">how it actually works</a>
----
This document is mostly "by example".
----
<a name="_quick_introduction"></a>
### quick introduction
## quick introduction
The wildrepos feature allows you to specify access control rules using regular
expression patterns, so you can have many actual repos being served by a
@ -44,17 +22,13 @@ single set of rules in the config file. The regex pattern can also include
the word `CREATOR` in it, allowing you to parametrise the name of the user
creating the repo. The examples below will make this clearer.
<a name="_rc_file_setting_required"></a>
### rc file setting required
## rc file setting required
This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable in `doc/gitolite.rc.mkd`
for more information on this.
<a name="_examples_of_wildcard_repos"></a>
### examples of wildcard repos
## examples of wildcard repos
As the introduction said, you can include the word `CREATOR` in the regex
pattern, though it is not mandatory. We'll look at examples of both types of
@ -71,9 +45,7 @@ keep track of who actually created the repo (except for granting access), but
needs more communication / co-operation among the users to avoid repo name
clashes.
<a name="_wildcard_repos_with_creator_name_in_them"></a>
#### wildcard repos with creator name in them
### wildcard repos with creator name in them
Here's an example snippet:
@ -102,9 +74,7 @@ new repo, as user "u4" (a student):
Notice the *two* empty repo inits, and the order in which they occur ;-)
<a name="_wildcard_repos_without_creator_name_in_them"></a>
#### wildcard repos without creator name in them
### wildcard repos without creator name in them
Here's how the same example would look if you did not want the CREATOR's name
to be part of the actual repo name.
@ -129,7 +99,7 @@ and have a TA create the repos in advance.
In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details.
<a name="_side_note_valid_regexes"></a>
## F=wildregex valid regexes and how they are used
### side-note: valid regexes
@ -140,8 +110,6 @@ look like a regex to gitolite. Use `foo/..*` if you want that.
Also, `..*` by itself is not considered a valid repo pattern. Try
`[a-zA-Z0-9].*`.
<a name="_side_note_line_anchored_regexes"></a>
### side-note: line-anchored regexes
A regex like
@ -157,8 +125,6 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters.
<a name="_contrast_with_refexes"></a>
#### contrast with refexes
Just for interest, note that this is in contrast to the refexes for the normal
@ -169,9 +135,7 @@ if no one will actually push such a branch! You can anchor both sides if you
really care, by using `master$` instead of `master`, but that is *not* the
default for refexes.
<a name="_handing_out_rights_to_wildcard_matched_repos"></a>
### handing out rights to wildcard-matched repos
## F=setperms handing out rights to wildcard-matched repos
In the examples above, we saw two special "user" names: READERS and WRITERS.
The permissions they have are controlled by the config file, but ***who is
@ -193,7 +157,7 @@ Create a small text file that contains the permissions you desire:
WRITERS u6
(hit ctrl-d here)
...and use the new "setperms" command to set permissions for your repo:
...and use the new **setperms** command to set permissions for your repo:
$ ssh git@server setperms assignments/u4/a12 < myperms
New perms are:
@ -201,7 +165,7 @@ Create a small text file that contains the permissions you desire:
WRITERS u6
'setperms' will helpfully print what the new permissions are but you can also
use 'getperms' to check:
use **getperms** to check:
$ ssh git@server getperms assignments/u4/a12
READERS u5
@ -215,8 +179,6 @@ The following points are important:
word is the role (in this example, READERS or WRITERS), and the rest
are simple usernames.
<a name="_admin_adding_other_roles_than_READERS_and_WRITERS"></a>
### (admin) adding other roles than READERS and WRITERS
Let's say your needs are more complex and you need more roles. For example,
@ -244,9 +206,7 @@ people, say by sending something like this to `setperms`:
You can enable this by setting the `GL_WILDREPOS_PERM_CATS` variable in the rc
file. The rc file documentation (`doc/gitolite.rc.mkd`) explains how.
<a name="_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_"></a>
#### **IMPORTANT WARNING ABOUT THIS FEATURE**
#### #rolenamewarn **IMPORTANT WARNING ABOUT THIS FEATURE**
Please make sure that none of the role names conflict with any of the
**usernames** in the system. For example, if you have a user called "foo",
@ -256,34 +216,28 @@ make sure you do not include "foo" as a valid role in
You can keep things sane by using UPPERCASE names for roles, while keeping all
your usernames lowercase; then you don't have to worry about this problem.
<a name="_setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
## setting a gitweb description for a wildcard-matched repo
### setting a gitweb description for a wildcard-matched repo
Similar to the getperms/setperms commands, there are the
[getdesc/setdesc][setdesc] commands, thanks to Teemu.
Similar to the getperms/setperms commands, there are the getdesc/setdesc
commands, thanks to Teemu.
<a name="_reporting"></a>
### reporting
## reporting
In order to see what repositories were created from a wildcard, use the
"expand" command, described briefly in [doc/report-output.mkd][repout].
["expand"][expand] command.
<a name="_deleting_a_wild_repo"></a>
## deleting a wild repo
### deleting a wild repo
See [repo deletion][wild_repodel] for more on this. Note that this requires you
to install/setup "adc"s (admin defined commands). See
[admin-defined-commands][ADCs] for how to do that.
See [repo deletion][rmr] for more on this. Note that this requires you to
install/setup "adc"s (admin defined commands). See
[doc/admin-defined-commands.mkd][adc] for how to do that.
----
[adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
[rmr]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
Enjoy, and please use with care. This is pretty powerful stuff. As they say:
if you break it, you get to keep both pieces :)
<a name="_how_it_actually_works"></a>
### how it actually works
## F=_wildhow how it actually works
This section tells you what is happening inside gitolite so you can understand
this feature better. Let's use the config example at the beginning of this
@ -347,9 +301,3 @@ that repo, the ruleset looks like:
I hope that helps.
----
Enjoy, and please use with care. This is pretty powerful stuff. As they say:
if you break it, you get to keep both pieces :)
[repout]: http://sitaramc.github.com/gitolite/doc/report-output.html

30
t/README.mkd → t/README-t.mkd
View file

@ -1,26 +1,14 @@
## notes on the testing setup
# F=_t notes on the testing setup
**WARNING: PLEASE use a dedicated user for doing this**. Various files and
directories get overwritten and it's much simpler this way.
In this document:
* <a href="#_terminology">terminology</a>
* <a href="#_notes_and_background">notes and background</a>
* <a href="#_playing_with_gitolite">playing with gitolite</a>
* <a href="#_testing_gitolite">testing gitolite</a>
* <a href="#_instructions_for_adding_new_tests">instructions for adding new tests</a>
<a name="_terminology"></a>
### terminology
## terminology
#define PW "patches welcome!"
#define TODO PW
<a name="_notes_and_background"></a>
### notes and background
## notes and background
All testing is done on one **brand new** userid. We use ssh host alias tricks
to simulate multiple gitolite users within this, so `ssh gitolite info` gets
@ -34,9 +22,7 @@ mirroring, smart http, and password-based access.
Note that the test driver has evolved as new scripts were added; you will see
that older scripts are a little less sophisticated.
<a name="_playing_with_gitolite"></a>
### playing with gitolite
## playing with gitolite
(Please heed the warning at the top of this document and use a dedicated user
for this).
@ -85,9 +71,7 @@ access simply using a different URL. For example, `git clone u1:testing` and
`git clone u2:testing` may give you different results depending on what rights
you gave users "u1" and "u2" in your config.
<a name="_testing_gitolite"></a>
### testing gitolite
## testing gitolite
First, do what the "playing with gitolite" section says. That is a
pre-requisite.
@ -100,9 +84,7 @@ Once that is done, run this command (still in `$HOME` of the gl-test userid):
numbers be the actual test numbers, making it look like I have over 2000
tests, when in reality I have about 600)
<a name="_instructions_for_adding_new_tests"></a>
### instructions for adding new tests
## instructions for adding new tests
(TODO)