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

document overhaul

Browse source 
- explicit 'list' gives way to mindmap, ...
  - 'fm2mt.pl' to produce master-toc.mkd from the mindmap
  - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself

and LOTS of changes to the actual docs
This commit is contained in:
Sitaram Chamarty 2012-04-05 21:31:23 +05:30
parent 7c6728af89
commit de40461d9a
51 changed files with 2255 additions and 842 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
doc/WARNINGS.mkd Normal file
View file

@ -0,0 +1,72 @@
# WARNINGS
Gitolite does NOT like it if you fiddle with files, directories, permissions,
etc., on the server except as directed in the documentation. Gitolite also
expects all the directories and files it manages/uses to be owned by the
hosting user and not have strange permissions and ownerships.
Very few people have fallen foul of this, but the ones who *did* became very
obnoxious about it, hence this warning.
Gitolite depends on several system-installed packages: openssh, git, perl, sh
being the main ones. They should all be configured sensibly and with most of
the normal defaults. (For example, if your sshd config says the authorized
keys file should be placed in some directory other than the default, expect
trouble).
----
For the entertainment of the sensible majority, and as a way of thanking all
of you, here are some examples of requests (demands in some cases) I have
received over the last couple of years.
* deleting environment variables copied from client session
demand: add code to delete certain environment variables at startup
because "the openssh servers in the linux distribution that [he] use[s],
are configured to copy `GIT_*` variables to the remote session".
This is wrong on so many levels it's almost plonk-able!
* using `cp` instead of `ln`
Guy has an NTFS file system mounted on Linux. So... no symlinks (an NTFS
file system on Windows works fine because msysgit/cygwin manage to
*simulate* them. NTFS mounted on Linux won't do that!)
He wanted all the symlink stuff to be replaced by copies.
No. Way.
* non-bare repos on the server
Some guy gave me a complicated spiel about git-svn not liking bare repos
or whatever. I tuned off at the first mention of those 3 letters so I
don't really know what the actual problem was.
But it doesn't matter. Even if someone (Ralf H) had not chipped in with a
workable solution, I still would not do it. A server repo should be bare.
Period.
* incomplete ownership of `GL_REPO_BASE`
This guy had a repo-base directory where not all of the files were owned
by the git user. As a result, some of the hooks did not get created. He
claimed my code should detect OS-permissions issues while it's doing its
stuff.
No. I refuse to have the code constantly look over its shoulder making
sure fundamental assumptions are being met.
* empty template directory
(See man git-init for what a template directory is).
The same guy with the environment variables had an empty template
directory because he "does not like to have sample hooks in every
repository". So naturally, the hooks directory does not get created when
you run a `git init`. He expects gitolite to compensate for it.
Granted, it's only a 1-line change. But again, this falls under
"constantly looking over your shoulder to double check fundamental
assumptions". Where does it end?

34
doc/add.mkd
View file

@ -1,34 +0,0 @@
# adding users and repos
Do NOT add repos directly on the server. Clone the 'gitolite-admin' repo to
your workstation, make changes to it, then add, commit, and push. When the
push hits the server, the server "acts" upon your changes.
Full documentation on the conf file is [here][conf].
Here's a sample sequence, on your workstation, after your install is done
git clone git@host:gitolite-admin
cd gitolite-admin
vi conf/gitolite.conf
# now add lines like these:
repo foo
RW+ = me
RW = alice
R = wally
# now save the file and add it
git add conf
# add a couple of users; get their pubkeys by email or something, then:
cp /some/where/alice.pub keydir
cp /else/where/wally.pub keydir
git add keydir
# now commit and push
git commit -m 'added repo foo'
git push
# at this point gitolite will create the new repo 'foo' (if it did not
# already exist) then update the authorized keys file to include alice and
# wally's pubkeys

42
doc/admin.mkd Normal file
View file

@ -0,0 +1,42 @@
# gitolite administration
## #server server-side administration
The following activities require command line access to the server
* changing anything in the [rc][] file
* installing custom [hooks][], whether to all repos or just some repos
* moving [existing][] (bare) repos into gitolite control
Please read the [WARNINGS][] page first.
## #conf access control (the gitolite.conf file)
Most of gitolite's power is in the conf/gitolite.conf file, which specifies
detailed access control for repos.
### #confex example of a conf file
Here is an example of a simple conf/gitolite.conf file.
@staff = dilbert alice # line 1
@projects = foo bar # line 2
repo @projects baz # line 3
RW+ = @staff # line 4
- master = ashok # line 5
RW = ashok # line 6
R = wally # line 7
config hooks.emailprefix = '[%GL_REPO] ' # line 8
Use the following links to learn more:
* the basic [syntax][] -- comments, whitespace, include files, etc.
* defining [groups][], as in lines 1 and 2
* adding and removing [users][]
* adding and removing [repos][], as in line 3
* defining access [rules][], as in lines 4, 5, 6, and 7
* gitolite [options][]
* [git config][git-config] keys and values, as in line 8
* ["wild"][wild] repos -- ad hoc, user-created, repos

31
doc/conf.mkd
View file

@ -1,31 +0,0 @@
# the gitolite.conf file
This file is the crux of all of gitolite's access control. The basic syntax
is very simple.
Note: `<user>+` means one or more user or user group names, `<repo>+` means
one or more repo or repo group names, and `<refex>*` means zero or more
refexes.
* [group][group] definitions (optional, for convenience)
@<group> = <user>+
@<group> = <repo>+
* [repo][repo] definitions and access [rules][]
repo <repo>+
<perm> <refex>* = <user>+
# one or more such lines
* [gitolite options][options] that apply to the repo(s) in the last
"repo ..." line, for example:
option deny-rules = 1
* [git config][git-config] keys and values that also apply to the last named
repo(s), for example:
config hooks.emailprefix = '[%GL_REPO] '
In addition, you can also have [include][] statements.

17
doc/cust.mkd
View file

@ -2,17 +2,20 @@
Much of gitolite (g3)'s functionality comes from programs and scripts that are Much of gitolite (g3)'s functionality comes from programs and scripts that are
not considered "core". This keeps the core simpler, and allows you to enhance not considered "core". This keeps the core simpler, and allows you to enhance
gitolite for your own purposes without too much fuss. gitolite for your own purposes without too much fuss. (As an extreme example,
even mirroring is not in core now!)
(Also, please see the [developer notes][dev-notes] page).
## types of non-core programs ## types of non-core programs
There are 5 basic types of non-core programs. There are 5 basic types of non-core programs.
* *commands* can be run from the shell command line. Those listed in the * *commands* can be run from the shell command line. Among those, the ones
COMMANDS hash of the rc file can also be run remotely. listed in the COMMANDS hash of the rc file can also be run remotely.
* *hooks* are standard git hooks; see below. * *hooks* are standard git hooks; see below.
* *sugar scripts* change the conf language for your convenience. The word * *sugar scripts* change the conf language for your convenience. The word
sugar comes from "syntactics sugar". sugar comes from "syntactic sugar".
* *triggers* are to gitolite what hooks are to git. I just chose a * *triggers* are to gitolite what hooks are to git. I just chose a
different name to avoid confusion and constant disambiguation in the docs. different name to avoid confusion and constant disambiguation in the docs.
* **VREFs** are extensions to the access control check part of gitolite. * **VREFs** are extensions to the access control check part of gitolite.
@ -22,7 +25,7 @@ some description of each.
## #commands gitolite "commands" ## #commands gitolite "commands"
Gitolite comes with several commands that users can run. Remote user run the Gitolite comes with several commands that users can run. Remote users run the
commands by saying: commands by saying:
ssh git@host command-name [args...] ssh git@host command-name [args...]
@ -56,8 +59,8 @@ The rest is between you and 'man githooks' :-)
## #sugar syntactic sugar ## #sugar syntactic sugar
Sugar scripts help you change the perceived syntax of the conf language. The Sugar scripts help you change the perceived syntax of the conf language. The
base syntax of the language is as described [here][conf], so sugar scripts base syntax of the language is very simple, so sugar scripts take something
take something *else* and convert it into that. *else* and convert it into that.
That way, the admin sees additional features (like allowing continuation That way, the admin sees additional features (like allowing continuation
lines), while the parser in the core gitolite engine does not change. lines), while the parser in the core gitolite engine does not change.

114
doc/deleg.mkd Normal file
View file

@ -0,0 +1,114 @@
# delegating access control responsibilities
Delegation allows you to divide up a large conf file into smaller groups of
repos (called **subconf**s) and hand over responsibility to manage them to
**sub-admin**s. Gitolite can prevent one sub-admin from being able to set
access rules for any other sub-admin's repos.
Delegation is achieved by combining two gitolite features: [subconf][] and the
[NAME VREF][NAME].
To understand delegation, read both those links then come back to this
example.
## example
@webbrowsers = firefox lynx browsers/..*
@webservers = apache nginx servers/..*
@malwares = conficker storm ms/..*
# side note: if anyone objects, we claim ms stands for "metasploit" ;-)
# the admin repo access was probably like this to start with:
repo gitolite-admin
RW+ = sitaram
# now add these lines to the config for the admin repo
RW = alice bob mallory
RW VREF/NAME/conf/subs/webbrowsers = alice
RW VREF/NAME/conf/subs/webservers = bob
RW VREF/NAME/conf/subs/malwares = mallory
- VREF/NAME/ = alice bob mallory
Finally, you tell gitolite to pull in these files using the "subconf" command
subconf "subs/*.conf"
And that's it.
## #subconf the subconf command
Subconf is exactly like the include command in syntax:
subconf "foo/bar.conf"
but while reading the included file, it sets a "subconf name" of "foo".
When a subconf name is in effect, there are some restrictions on what repos
can be managed.
For example, in the include file in the above example, you can only have
"repo" lines for:
* a repo called "foo"
* a group called "@foo" defined outside the include file
* a member of a group called "@foo" (again, defined outside)
* a repo that matches a member of a group called "@foo" if that member is a
regular expression pattern
Here's an example. If the main conf file contains
@foo = aa bb cc/..*
then the subconf can only accept repo statements that refer to 'foo', '@foo',
'aa', 'bb', or any repo whose name starts with 'cc/'.
### how the "subconf name" is derived
For subconf lines that look just like include statements, i.e.,
subconf "foo/bar.conf"
subconf "frob/*.conf"
# assume frob has files aa.conf, bb.conf
the subconf name as each file is being processed is the base name of the file.
This means it would be "bar" for the first line, "aa" when processing
"frob/aa.conf", and "bb" when processing "frob/bb.conf".
A variation of subconf exists that can explicitly state the subconf name:
subconf foo "frob/*.conf"
In this variation, regardless of what file in "frob/" is being read, the
subconf name in effect is "foo".
## security notes
### 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
(say `@foo`) defined in the main config file, do this:
@myfoo = @foo
# now do whatever you want with @myfoo
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.
### delegating pubkeys
Short answer: not gonna happen.
The delegation feature is meant only for access control rules, not pubkeys.
Adding/removing pubkeys is a much more significant event than changing branch
level permissions for people already on staff, and only the main admin should
be allowed to do it.
Gitolite's "userids" all live in the same namespace. This is unlikely to
change, so please don't ask -- it gets real complicated to do otherwise.
Allowing sub-admins to add users means username collisions, which also means
security problems (admin-A creates a pubkey for Admin-B, thus gaining access
to all of Admin-B's stuff).
If you feel the need to delegate even that, please just go the whole hog and
give them separate gitolite instances (i.e., running under different gitolite
hosting users)!

33
doc/dev-notes.mkd
View file

@ -3,9 +3,6 @@
Gitolite has a huge bunch of existing features that gradually need to moved Gitolite has a huge bunch of existing features that gradually need to moved
over. Plus you may want to write your own programs to interact with it. over. Plus you may want to write your own programs to interact with it.
Hints for developers wishing to help migrate features over from g2 are
[here][dev-hints].
Here are some random notes on developing hooks, commands, triggers, and sugar Here are some random notes on developing hooks, commands, triggers, and sugar
scripts. scripts.
@ -20,15 +17,15 @@ In general, the following environment variables should always be available:
Commands invoked by a remote client will also have `GL_USER` set. Hooks will Commands invoked by a remote client will also have `GL_USER` set. Hooks will
have `GL_REPO` also set. have `GL_REPO` also set.
Finally, note that triggers get a lot of relevant information as arguments; Finally, note that triggers get a lot of relevant information from gitolite as
see [here][triggers] for details. arguments; see [here][triggers] for details.
## APIs ## APIs
### the shell API ### the shell API
The following commands exist to help you write shell scripts that interact The following commands exist to help you write shell scripts that interact
easily with gitolite. Each of them responds to `h` so please run that for easily with gitolite. Each of them responds to `-h` so please run that for
more info. more info.
* `gitolite access` to check access rights given repo, user, type of access * `gitolite access` to check access rights given repo, user, type of access
@ -38,7 +35,7 @@ more info.
src/commands/desc src/commands/desc
* `gitolite git-config` to check gitolite options or git config variables * `gitolite git-config` to check gitolite options or git config variables
directly from gitolite's "compiled output, (i.e., without looking at the directly from gitolite's "compiled" output, (i.e., without looking at the
actual `repo.git/config` file or using the `git config` command). Example actual `repo.git/config` file or using the `git config` command). Example
use: none yet use: none yet
@ -53,16 +50,18 @@ perl API module) for ideas.
...is implemented by Gitolite::Easy; the comments in src/Gitolite/Easy.pm ...is implemented by Gitolite::Easy; the comments in src/Gitolite/Easy.pm
serve as documentation. serve as documentation.
## your own hooks ## writing your own...
### anything but the update hook ### ...hooks
#### anything but the update hook
If you want to add your own hook, it's easy as long as it's not the 'update' If you want to add your own hook, it's easy as long as it's not the 'update'
hook. Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`. hook. Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`.
The rest is between you and 'man githooks' :-) The rest is between you and 'man githooks' :-)
### update hook #### update hook
If you want to add additional `update` hook functionality, do this: If you want to add additional `update` hook functionality, do this:
@ -83,7 +82,7 @@ Note: a normal update hook expects 3 arguments (ref, old SHA, new SHA). A
VREF will get those three, followed by at least 4 more. Your VREF should just VREF will get those three, followed by at least 4 more. Your VREF should just
ignore the extra args. ignore the extra args.
## your own commands ### ...commands
You can add your own commands. You can run them on the server (example, You can add your own commands. You can run them on the server (example,
`gitolite access`). Then you can enable certain commands to be allowed to run `gitolite access`). Then you can enable certain commands to be allowed to run
@ -94,19 +93,15 @@ receive the arguments you append. In addition, the env var `GL_USER` is
available if it is being run remotely. src/commands/desc is the best example available if it is being run remotely. src/commands/desc is the best example
at present. at present.
## your own trigger programs ### ...trigger programs
Trigger programs are just commands whose names have been added to the Trigger programs run at specific points in gitolite's execution, with specific
appropriate list in the [rc][] file. Triggers get specific arguments arguments being passed to them. See the [triggers][] page for details.
depending on when they are called; see [here][triggers] for details.
You can write programs that are both manually runnable as well as callable by You can write programs that are both manually runnable as well as callable by
trigger events, especially if they don't *need* any arguments. trigger events, especially if they don't *need* any arguments.
Look in the distributed [rc][] file for example programs; at this point there ### ..."sugar"
aren't many.
## your own "sugar"
Syntactic sugar helpers are NOT complete, standalone, programs. They must Syntactic sugar helpers are NOT complete, standalone, programs. They must
include a perl sub called `sugar_script` that takes in a listref, and returns include a perl sub called `sugar_script` that takes in a listref, and returns

16
doc/dev-status.mkd
View file

@ -2,20 +2,19 @@
Not yet done (will be tackled in this order unless someone asks): Not yet done (will be tackled in this order unless someone asks):
* detailed documentation for new features * svnserve (someone is testing it)
* querying the outside world for group info (see gl-get-membership-program
in g2)
* mirroring
* pulling in documentation for things that are the same in g2 * pulling in documentation for things that are the same in g2
* "unrestricted arguments" for some ADCs (like git-annexe)
* smart http * smart http
* special features (no-create-repos, shell-access, gl-all-read-all, etc) * special features (no-create-repos, gl-all-read-all, etc)
* mechanism for ADCs using unchecked arguments -- this is not just a matter
of writing it; I have to think about *how* it will be done. (AFAIK the
only tool affected is git-annexe)
Help needed: Help needed:
* I'd like distro packagers to play with it and help with migration advice * I'd like distro packagers to play with it and help with migration advice
for distro-upgrades for distro-upgrades
* [rsync][pw2], htpasswd * rsync, htpasswd
* git-annexe support (but this has a pre-requisite in the previous list) * git-annexe support (but this has a pre-requisite in the previous list)
Won't be done unless someone asks (saw no evidence that anyone used them in g2 Won't be done unless someone asks (saw no evidence that anyone used them in g2
@ -30,6 +29,7 @@ Done:
* core code * core code
* test suite * test suite
* some documentation * mirroring
* most documentation
* distro packaging instructions * distro packaging instructions
* migration advice for common cases * migration advice for common cases

190
doc/emergencies.mkd Normal file
View file

@ -0,0 +1,190 @@
# help for emergencies
----
"Don't Panic!"
----
## #lost-key lost admin key/access
If you lost your gitolite **admin** key or access, here's what you do. We'll
assume your username is 'alice'.
* Make yourself a new keypair and copy the public key to the server as
'alice.pub'.
* Log on to the server, and run `gitolite setup -pk alice.pub`.
That's it; the new alice.pub file replaces whatever existed in the repo
before.
## #bypass bypassing gitolite
You may have lost access because of a conf file error, in which case the above
trick won't help. What you want is to make changes to the repo (or perhaps
just rewind) and push that. Here's how to do that:
* Log on to the server.
* Clone the admin repo using the full path: `git clone
$HOME/repositories/gitolite-admin.git temp`.
* Make whatever changes you want -- add/replace a key, 'git revert' or 'git
reset --hard' to an older commit, etc. Anything you need to fix the
problem, really.
* Run `gitolite push` (or possibly `gitolite push -f`). Note that's
'gitolite push', not 'git push'.
<font color="red">
**NOTE**: gitolite does **no access checking** when you do this!
</font>
## #clean cleaning out a botched install
If you've read the [files involved in gitolite][files] page, you probably know
the answer, but here's a list of files you should blow away.
* **gitolite sources** -- can be found by running `which gitolite`. If it's
a symlink, go to its target directory.
* **gitolite admin directory** -- `$HOME/.gitolite`. Save the 'logs'
directory if you want to preserve them for any reason.
* **the rc file** -- `$HOME/.gitolite.rc`. If you made any changes to it
you can save it as some other name instead of deleting it.
* **the gitolite-admin repo** -- `$HOME/repositories/gitolite-admin.git`.
You can clone it somewhere to save it before blowing it away if you wish.
* **git repositories** -- `$HOME/repositories`. The install process will
not touch any existing repos except 'gitolite-admin.git', so you do not
have to blow away (or move) your work repos to fix a botched install.
Only when you update the conf to include those repos and push the changes
will those repos be touched. And even then all that happens is that the
update hook, if any, is replaced with gitolite's own hook.
* **ssh stuff** -- exercise caution when doing this, but in general it
should be safe to delete all lines between the "gitolite start" and
"gitolite end" markers in `$HOME/.ssh/authorized_keys`.
Gitolite does not touch any other files in the ssh directory.
## #ce common errors
* `WARNING: keydir/<yourname>.pub duplicates a non-gitolite key, sshd will ignore it`
You used a key that is already set to give you shell access. You cannot
use the same key to get shell access as well as access gitolite repos.
Solution: use a different keypair for gitolite. There's a slightly longer
discussion in the [setup][] page. Also see [why bypassing causes a
problem][ybpfail] and both the documents in [ssh][] for background.
* `Empty compile time value given to use lib at hooks/update line 6`
(followed by `Can't locate Gitolite/Hooks/Update.pm in @INC` a couple of
lines later).
You're bypassing gitolite. You cloned the repo using the full path (i.e.,
including the `repositories/` prefix), either directly on the server, or
via ssh but with a key that gives you **shell** access.
Solution: same as for the previous bullet.
NOTE: If you really *must* do it, and this is a one-time thing, you can
try `gitolite push` instead of `git push`. **BUT**... this defeats all
gitolite access control, so if you're going to do this often, maybe you
don't need gitolite!
## #ue uncommon errors
* `WARNING: split conf not set, gl-conf present for <repo>`
(case 1) This can happen if you have a *bare* repo (i.e., some `repo.git`
directory) copied from g2 with `GL_BIG_CONFIG` on, and you pushed a change
to the conf or ran certain commands *before* adding the newly added repo
to the conf file.
(case 2) This can also happen if you changed something like this
repo foo
...<some rules>...
to this
@grp = foo
repo @grp
...<some rules>...
Also, even running `gitolite setup` will not fix this.
The root cause is an internal consistency check that I do not wish to
disable or subvert. It is there for a reason, and I would prefer a
warning that a human can investigate.
If you're sure the reasons are one of the two above, you can either add
the repo to the conf file in case 1, or manually remove the gl-conf file
from the repo.git directory in case 2.
Either way, run `gitolite setup` afterwards to make sure things are in
good shape.
If you think neither of those is the cause, email me.
## #ngp things that are not gitolite problems
There are several things that appear to be gitolite problems but are not. I
cannot help with most of these (although the good folks on irc or the mailing
list -- see [contact][] -- might be able to; they certainly appear to have a
lot more patience than I do, bless 'em!)
* **client side software**
* putty/plink
* jgit/Eclipse
* Mac OS client **or** server
* putty/plink
* windows as a server
* ...probably some more I forgot; will update this list as I remember...
* did I mention putty/plink?
* **ssh**
The *superstar* of the "not a gitolite problem" category is actually ssh.
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][ssh] tries to
help you anyway!
Everything I know is in that latter link. Please email me about ssh ONLY
if you find something wrong or missing in those documents.
* **git**
I wish I had a dollar for each time someone did a *first push* on a new
repo, got an error because there were "no refs in common (etc.)", and
asked me why gitolite was not allowing the push.
Gitolite is designed to look like just another bare repo server to a
client (except requiring public keys -- no passwords allowed). It is
*completely transparent* when there is no authorisation failure (i.e.,
when the access is allowed, the remote client has no way of knowing
gitolite was even installed!)
Even "on disk", apart from reserving the `update` hook for itself,
gitolite does nothing to your bare repos unless you tell it to (for
example, adding 'gitweb.owner' and such to the config file).
BEFORE you think gitolite is the problem, try the same thing with a normal
bare repo. In most cases you can play with it just by doing something
like this:
mkdir /tmp/throwaway
cd /tmp/throwaway
git clone --mirror <some repo you have a URL for> bare.git
git clone bare.git worktree
cd worktree
<...try stuff>

71
doc/external.mkd Normal file
View file

@ -0,0 +1,71 @@
# interfacing with external tools
> ----
> **Note**: The old gitolite (v1.x, v2.x) used to tie itself into knots
> dealing with gitweb and daemon. One of the goals of g3 was to get out of
> that game, which your author does not play anyway. This means statements
> like "...special user called 'gitweb'..." really apply to the [non-core][]
> programs that gitolite ships with, not to "core" gitolite, and any or all
> of this functionality can be disabled by commenting out certain lines in
> the [rc][] file.
> ----
> Also, **note** that gitolite does **not** install or configure
> gitweb/git-daemon -- that is a one-time setup you must do separately.
> ----
## gitweb
The following repos are deemed to be readable by gitweb:
* any repos readable by the special user `gitweb`
* any repos containing one or more of the following types of lines:
config gitweb.owner = owner name
config gitweb.description = some description
config gitweb.category = some category
Side note: the following shorter forms are available as [syntactic
sugar][sugar] for the above longer forms:
owner = owner name
desc = some description
category = some category
The list of gitweb-readable repos is written to a file whose name is given by
the [rc][] file variable `GITWEB_PROJECTS_LIST`. The default value of this
variable, if it is not specified or empty, is `$HOME/projects.list`.
In addition, each of the config variables described above is written to the
repo to which it pertains, so that gitweb can use them.
### #umask changing the UMASK
Gitweb typically runs under a different userid, and the default permissions
that gitolite sets make them unreadable.
See the section on the `UMASK` variable in the documentation for the [rc
file][rc].
## git-daemon
Any repo readable by the special user `daemon` is deemed to be readable by
git-daemon. For each of these repos, an empty file called
`git-daemon-export-ok` is created in the repository (i.e., the `repo.git`
directory inside `$HOME/repositories`).
## tips
Setting descriptions en-masse usually does not make sense, but you can
certainly do things like
repo @all
R = gitweb daemon
assuming you have other means of setting 'gitweb.description' and
'gitweb.owner'.
Also see [this][deny-rules] for a twist on that.

53
doc/extras/auth.mkd
View file

@ -3,7 +3,7 @@
This document will explain why an "ssh issue" is almost never a "gitolite 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. issue", and, indirectly, why I dont get too excited about the former.
Note: for actual ssh troubleshooting see [this][ssh-troubleshooting]. Note: for actual ssh troubleshooting see [this][sts].
Here is a fundamental point: <font color="red">**Gitolite does not do Here is a fundamental point: <font color="red">**Gitolite does not do
authentication. It only does authorisation**.</font> authentication. It only does authorisation**.</font>
@ -18,41 +18,42 @@ So first, let's loosely define these words:
> **Authorisation** is the process of asking what you want to do and > **Authorisation** is the process of asking what you want to do and
> deciding if you're allowed to do it or not. > deciding if you're allowed to do it or not.
Now, if you managed to read about [gitolite and ssh][gitolite-and-ssh], you Now, if you managed to read about [gitolite and ssh][glssh], you
know that gitolite is meant to be invoked as: know that gitolite is meant to be invoked as:
/full/path/to/gl-auth-command some-authenticated-gitolite-username /full/path/to/gitolite-shell some-authenticated-gitolite-username
(where the "gitolite username" is a "virtual" username; it does not have to (where the "gitolite username" is a "virtual" username; it does not have to
be, and usually *isn't*, an actual *unix* username). be, and usually *isn't*, an actual *unix* username).
As you can see, authentication happens before gitolite is called. As you can see, authentication happens before gitolite is called.
## but... but... you have all that ssh stuff in there! ## but... but... you have all that ssh stuff in gitolite!
The default mode of using gitolite does use ssh keys, but all it's doing is No I don't. Not in "core" gitolite from g3 onwards :-)
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 The default setup does use ssh keys, but it's only helping you **setup**
are [smart http][http], and ldap-backed sshd. In both cases, gitolite has no ssh-based authentication **as a convenience to you**. But in fact it is a
role to play in creating users, setting up their passwords/keys, etc. There's *completely* separate program that you can disable (in the rc file) or replace
even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with with something else of your choice.
the authkeys file in such installations.
For example, in both [smart http][http] and ldap-backed sshd, gitolite has no
role to play in creating users, setting up their passwords/keys, etc.
## 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) (where "X" is some ssh related behaviour change or feature)
Well, if it's not a security issue I *probably* won't. I'm willing to change Well, if it's not a security issue I won't. But since it's no longer part of
my mind if enough people convince me they need it. (There's a mailing list if "core" gitolite, I can be much more relaxed about taking patches, or even
you want to find others who also need the same thing.) alternative implementations.
While we're on the subject, locking someone out is *not* a security issue. While we're on the subject, locking someone out is *not* a security issue.
Even if you locked yourself (the admin) out, the docs tell you how to recover Even if you [lost the admin key][lost-key], the docs tell you how to recover
from such errors. You do need some password based method to get a shell from such errors. You do need some password based method to get a shell
command line on the server, of course. command line on the server, of course.
## appendix: how to use other authentication systems with gitolite ## #otherauth how to use other authentication systems with gitolite
The bottom line in terms of how to invoke gitolite has been described above, 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 and as long as you manage to do that gitolite won't even know how the
@ -84,6 +85,22 @@ to generate keypairs and send them to the admin, but they can be more
centrally stored and perhaps used by other programs or tools simultaneously, centrally stored and perhaps used by other programs or tools simultaneously,
which can be useful. which can be useful.
Finally, gitolite allows you to store *group* information externally too. See ## #ldap getting user group info from LDAP
[here][ldap] for more on this.
Gitolite's [groups][] are pretty convenient, but some organisations already
have similar (or sufficient) information in their LDAP store.
Gitolite can tap into that information, with a little help. Write a program
which, given a username, queries your LDAP store and returns a space-separated
list of groups that the user is a member of. Then put the full path to this
program in an [rc][] variable called `GROUPLIST_PGM`, like so:
GROUPLIST_PGM => '/home/git/bin/ldap-query-groups',
Now you can use those groupnames in access rules in gitolite, just as if you
had declared their memberships in the conf file.
Caution: your program must do its own logging if you want the audit trail of
"why/how did this user get access to this repo at this time?" to resolve
properly. Gitolite does not do any logging of the results of the queries
because for people who don't need it that would be a huge waste.

8
doc/extras/gitolite-and-ssh.mkd
View file

@ -99,13 +99,13 @@ 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 you look in the `authorized_keys` file, you'll see entries like this (I chopped
off the ends of course; they're pretty long lines): off the ends of course; they're pretty long lines):
command="[path]/gl-auth-command sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t... command="[path]/gitolite-shell sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
command="[path]/gl-auth-command usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT... command="[path]/gitolite-shell usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
First, it finds out which of the public keys in this file match the incoming First, it finds out which of the public keys in this file match the incoming
login. That's crypto stuff, and I won't go into it. Once the match has been login. That's crypto stuff, and I won't go into it. Once the match has been
found, it will run the command given on that line; e.g., if I logged in, it found, it will run the command given on that line; e.g., if I logged in, it
would run `[path]/gl-auth-command sitaram`. So the first thing to note is would run `[path]/gitolite-shell sitaram`. So the first thing to note is
that such users do not get "shell access", which is good! that such users do not get "shell access", which is good!
Before running the command, however, sshd sets up an environment variable Before running the command, however, sshd sets up an environment variable
@ -113,7 +113,7 @@ called `SSH_ORIGINAL_COMMAND` which contains the actual git command that your
workstation sent out. This is the command that *would have run* if you did workstation sent out. This is the command that *would have run* if you did
not have the `command=` part in the authorised keys file. not have the `command=` part in the authorised keys file.
When `gl-auth-command` gets control, it looks at the first argument When `gitolite-shell` gets control, it looks at the first argument
("sitaram", "usertwo", etc) to determine who you are. It then looks at the ("sitaram", "usertwo", etc) to determine who you are. It then looks at the
`SSH_ORIGINAL_COMMAND` variable to find out which repository you want to `SSH_ORIGINAL_COMMAND` variable to find out which repository you want to
access, and whether you're reading or writing. access, and whether you're reading or writing.

64
doc/extras/nagp.mkd
View file

@ -1,64 +0,0 @@
# not a gitolite problem
These are issues I do not want to be emailed about. That does not mean you
cannot get help -- in all cases, you're welcome to ask on [irc or the mailing
list][contact]. Irc especially has people with much more patience than I
have, God bless them...
## specific clients, or specific server OSs
These are things I can not support. That does not mean they will not work
with gitolite -- on the contrary, lots of people are using them.
But I personally don't use them, and I won't use them, and in my admittedly
limited experience they have given me good reason to stay well away.
Please ask for help on the [mailing list or IRC][contact]. Please do not
email me directly.
* putty/plink
* jgit/Eclipse
* Mac OS client or server
* windows as a server
* ...probably some more I forgot; will update this list as I remember...
## ssh
The *superstar* of the "not a gitolite problem" category is actually ssh.
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][ssh] tries to
help you anyway!
Everything I know is in that latter link. Please email me about ssh ONLY if
you find something wrong or missing in those documents.
## git
Example 1: when a first `git push` to a new repo fails, it is not because of
gitolite, it is because you need to say `git push origin master` or something.
This is a git issue.
There are several such examples. Gitolite is designed to look like just
another bare repo server to a client (except requiring public keys -- no
passwords allowed). It is *completely transparent* when there is no
authorisation failure (i.e., when the access is allowed, the remote client has
no way of knowing gitolite was even installed!)
Even "on disk", apart from reserving the `update` hook for itself, gitolite
does nothing to your bare repos unless you tell it to (for example, adding
'gitweb.owner' and such to the config file).
BEFORE you think gitolite is a problem, try the same thing with a normal bare
repo. In most cases you can play with it just by doing something like this:
mkdir /tmp/throwaway
cd /tmp/throwaway
git clone --mirror <some repo you have a URL for> bare.git
git clone bare.git worktree
cd worktree
<...try stuff>
----
In addition, the original nagp has more funny stuff...

203
doc/extras/putty.mkd Normal file
View file

@ -0,0 +1,203 @@
# putty and msysgit
This document is intended for those who wish to use Putty/Plink with msysgit.
If you need more help with putty or component programs I suggest looking at [the official putty documentation](http://the.earth.li/~sgtatham/putty/latest/htmldoc/).
**If you are not already using Putty for SSH it is recommended you do _NOT_ use it with msysgit.**
**Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the [ssh-troubleshooting document][sts].**
<a name="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.
How to do that on your version of windows will likely vary, and is not covered here. For purposes of example, on a 64 bit Windows Vista machine the GIT\_SSH value could be:
C:\Program Files (x86)\PuTTY\plink.exe
Note the lack of quotes.
Testing that msysgit is properly configured can be done from the git bash shell. Simply type (case sensitive, include the quotes):
"$GIT_SSH" -V
You should get a response similar to this:
plink: Release 0.60
If instead you get a "command not found" type error you likely have a typo in your environment variable.
<a name="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"/>
## 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.
Either way, you will want to use puttygen. Note that you can go the other way if you want to stop using putty but keep the key by exporting the key to OpenSSH format.
<a name="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".
It is recommended to give the key a meaningful comment.
<a name="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.
If the key does not have a meaningful comment I would suggest adding one at this point.
<a name="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"/>
### 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"/>
### 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"/>
## 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"/>
## 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:
ssh://user@host.example.ext:port/repo
You can use:
ssh://session_name/repo
<a name="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:
The server's host key is not cached in the registry. You
have no guarantee that the server is the computer you
think it is.
The server's rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Connection abandoned.
fatal: The remote end hung up unexpectedly
Or, in the case of the host key changing, something like this:
WARNING - POTENTIAL SECURITY BREACH!
The server's host key does not match the one PuTTY has
cached in the registry. This means that either the
server administrator has changed the host key, or you
have actually connected to another computer pretending
to be the server.
The new rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Connection abandoned.
fatal: The remote end hung up unexpectedly
The solution is to call plink directly, or start putty and connect with it first. To use plink, open the Git Bash shell and enter:
"$GIT_SSH" hostname_or_session_name
When you do you will see something like this:
The server's host key is not cached in the registry. You
have no guarantee that the server is the computer you
think it is.
The server's rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
If you trust this host, enter "y" to add the key to
PuTTY's cache and carry on connecting.
If you want to carry on connecting just once, without
adding the key to the cache, enter "n".
If you do not trust this host, press Return to abandon the
connection.
Store key in cache? (y/n)
Or, in the case of a changed key, a response like this:
WARNING - POTENTIAL SECURITY BREACH!
The server's host key does not match the one PuTTY has
cached in the registry. This means that either the
server administrator has changed the host key, or you
have actually connected to another computer pretending
to be the server.
The new rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
If you were expecting this change and trust the new key,
enter "y" to update PuTTY's cache and continue connecting.
If you want to carry on connecting but without updating
the cache, enter "n".
If you want to abandon the connection completely, press
Return to cancel. Pressing Return is the ONLY guaranteed
safe choice.
Update cached key? (y/n, Return cancels connection)
In either case hit y and the key will be stored.
<a name="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:
"$GIT_SSH" -v user@hostname
Or, if using sessions with a pre-entered username:
"$GIT_SSH" -v session_name
In either case, you should look for lines like:
Trying Pageant key #0
Authenticating with public key "My Key" from agent
The first says which (numerical) key the ageant is trying. The second tells you the key comment for the authenticating key. To my knowledge the second line should only show up once, for the valid key.
<a name="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:
ssh user@host command etc etc
You will want to use:
"$GIT_SSH" user@host command etc etc
Otherwise everything should be identical.
<a name="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.

114
doc/extras/ssh-troubleshooting.mkd
View file

@ -14,7 +14,7 @@ and accessing gitolite.
* Before reading this document, it is **mandatory** to read and **completely * Before reading this document, it is **mandatory** to read and **completely
understand** [this][ssh], which is a very detailed look at how gitolite understand** [this][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; 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! if you did, you wouldn't be needing *this* document either!
* This document, and others linked from this, together comprise all the help * 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 I can give you in terms of the ssh aspect of using gitolite. If you're
@ -80,11 +80,6 @@ Here's how normal gitolite key handling works:
between gitolite's "marker" lines (`# gitolite start` and `# gitolite between gitolite's "marker" lines (`# gitolite start` and `# gitolite
end`). end`).
### (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**.
### common ssh problems ### common ssh problems
Since I'm pretty sure at least some of you didn't bother to read the Since I'm pretty sure at least some of you didn't bother to read the
@ -94,15 +89,16 @@ you there again. Especially the first bullet.
Done? OK, read on... Done? OK, read on...
The following problem(s) indicate that pubkey access is not working at all, so The following problem(s) indicate that pubkey access is not working at all, so
you should start with [appendix 1][stsapp1_]. If that doesn't fix the problem, continue you should start with [appendix 1][stsapp1]. If that doesn't fix the problem, continue
with the other appendices in sequence. with the other appendices in sequence.
* running any git clone/fetch/ls-remote or just `ssh git@server info` asks * running any git clone/fetch/ls-remote or just `ssh git@server info` asks
you for a password. you for a password.
The following problem(s) indicate that your pubkey is bypassing gitolite and The following problem(s) indicate that your pubkey is bypassing gitolite and
going straight to a shell. You should start with [appendix 2][stsapp2_] and continue with going straight to a shell. You should start with [appendix 2][sshkeys-lint]
the rest in sequence. [Appendix 5][stsapp5_] has some background info. and continue with the rest in sequence. [Appendix 5][ybpfail] has some
background info.
* running `ssh git@server info` gets you the output of the GNU 'info' * running `ssh git@server info` gets you the output of the GNU 'info'
command instead of gitolite's version and access info. command instead of gitolite's version and access info.
@ -114,8 +110,8 @@ the rest in sequence. [Appendix 5][stsapp5_] has some background info.
(note absence of `repositories/`)] (note absence of `repositories/`)]
* you are able to clone repositories but are unable to push changes back * you are able to clone repositories but are unable to push changes back
(the error complains about the `GL_RC` environment variable not being set, (the error complains about the `GL_BINDIR` environment variable not being
and the `hooks/update` failing in some way). set, and the `hooks/update` failing in some way).
[If you run `git remote -v` you will find that your clone URL included the [If you run `git remote -v` you will find that your clone URL included the
`repositories/` described above!] `repositories/` described above!]
@ -136,42 +132,39 @@ Done? OK, now the general outline for ssh troubleshooting is this:
* make sure the server's overall setup even *allows* pubkey based login. * make sure the server's overall setup even *allows* pubkey based login.
I.e., check that git fetch/clone/ls-remote commands or a plain `ssh I.e., check that git fetch/clone/ls-remote commands or a plain `ssh
git@server info` do NOT ask for a password. If you do get asked for a git@server info` do NOT ask for a password. If you do get asked for a
password, see [appendix 1][stsapp1_]. password, see [appendix 1][stsapp1].
* match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys * match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys
file. To do this, run `sshkeys-lint`, which tells you in detail what key file. To do this, run `sshkeys-lint`, which tells you in detail what key
has what access. See [appendix 2][stsapp2_]. has what access. See [appendix 2][sshkeys-lint].
* at this point, we know that we have the right key, and that if sshd * at this point, we know that we have the right key, and that if sshd
receives that key, things will work. But we're not done yet. We still receives that key, things will work. But we're not done yet. We still
need to make sure that this specific key is being offered/sent by the need to make sure that this specific key is being offered/sent by the
client, instead of the default key. See [appendix 3][stsapp3_] and [appendix 4][sshhostaliases]. client, instead of the default key. See [appendix 3][stsapp3] and
[appendix 4][ssh-ha].
### random tips, tricks, and notes ### random tips, tricks, and notes
#### 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 Thanks to an idea from Jesse Keating, a single key can allow both gitolite
single key to allow both gitolite access *and* shell access. access *and* shell access.
This is done by copying the pubkey (to which you want to give shell access) to This is done by manually prefixing the username with "-s" as an extra argument
the server and running in the "command=" part of `~/.ssh/authorized_keys`. For example
gl-tool add-shell-user ~/foo.pub command="/home/g3/gitolite/src/gitolite-shell u1",no-port-[...etc...]
**IMPORTANT UPGRADE NOTE**: previous implementations of this feature were should be edited to be
crap. There was no easy/elegant way to ensure that someone who had repo admin
access would not manage to get himself shell access.
Giving someone shell access requires that you should have shell access in the command="/home/g3/gitolite/src/gitolite-shell -s u1",no-port-[...etc...]
first place, so the simplest way is to enable it from the server side only.
#### losing your admin key and moved out of the gitolite area of the authkeys file.
If you lost the admin key, and need to re-establish ownership of the It should be easy to make src/triggers/post-compile/ssh-authkeys read a list
gitolite-admin repository with a fresh key, get a shell on the server and use of shell capable users from some file on the server and put in the "-s" for
the program called `gl-admin-push` that comes with gitolite. See instructions those users. Patches welcome.
[here][adminpush].
#### simulating ssh-copy-id #### simulating ssh-copy-id
@ -199,11 +192,12 @@ bigger problems than gitolite install not working!)]
#### 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" Gitolite accepts public keys only in openssh format. Trying to use an "ssh2"
key (used by proprietary SSH software) results in: key (used by proprietary SSH software) will not be a happy experience.
src/triggers/post-compile/ssh-authkeys can be made to detect non-openssh
formats and automatically convert them; patches welcome!
WARNING: a pubkey file can only have one line (key); ignoring YourName.pub The actual conversion command, if you want to just do it manually for now and
be done with it, is:
To convert ssh2-compatible keys to openssh run:
ssh-keygen -i -f /tmp/ssh2/YourName.pub > /tmp/openssh/YourName.pub ssh-keygen -i -f /tmp/ssh2/YourName.pub > /tmp/openssh/YourName.pub
@ -218,9 +212,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 just don't seem to have any explanation, try removing all traces of
putty/plink, including environment variables, etc., and then try again. putty/plink, including environment variables, etc., and then try again.
Thankfully, someone contributed [contrib/putty.mkd][contrib_putty]. Thankfully, someone contributed [this][putty].
### #stsapp1_ appendix 1: ssh daemon asks for a password ### #stsapp1 appendix 1: ssh daemon asks for a password
> **NOTE**: This section should be useful to anyone trying to get > **NOTE**: This section should be useful to anyone trying to get
> password-less access working. It is not necessarily specific to gitolite, > password-less access working. It is not necessarily specific to gitolite,
@ -231,7 +225,7 @@ You have generated a keypair on your workstation (`ssh-keygen`) and copied the
public part of it (`~/.ssh/id_rsa.pub`, by default) to the server. public part of it (`~/.ssh/id_rsa.pub`, by default) to the server.
On the server you have appended this file to `~/.ssh/authorized_keys`. Or you On the server you have appended this file to `~/.ssh/authorized_keys`. Or you
ran something, like the `gl-setup` step during a gitolite install, which ran something, like the `gitolite setup` step during a gitolite install, which
should have done that for you. should have done that for you.
You now expect to log in without having to type in a password, but when you You now expect to log in without having to type in a password, but when you
@ -280,6 +274,10 @@ This is a quick checklist:
`AllowUsers` config entry, then only users mentioned in that line are `AllowUsers` config entry, then only users mentioned in that line are
allowed to log in! allowed to log in!
* while you're in there, check that file does NOT have a setting for
`AuthorizedKeysFile`. See `man sshd_config` for details. This setting is
a show stopper for gitolite to use ssh.
* some OSs/distributions require that the "git" user should have a password * some OSs/distributions require that the "git" user should have a password
and/or not be a locked account. You may want to check that as well. and/or not be a locked account. You may want to check that as well.
@ -288,27 +286,27 @@ This is a quick checklist:
this file for messages matching the approximate time of your last attempt this file for messages matching the approximate time of your last attempt
to login, to see if they tell you what is the problem. to login, to see if they tell you what is the problem.
### #stsapp2_ appendix 2: which key is which -- running sshkeys-lint ### #sshkeys-lint appendix 2: which key is which -- running sshkeys-lint
Follow these steps on the client: The sshkeys-lint program can be run on the server or the client. Run it with
'-h' to get a help message.
On the server you can run `gitolite sshkeys-lint` and it will tell you, for
each key in the admin directory's keydir, what access is available. This is
especially good at finding duplicate keys and such.
To run it on the client you have to copy the file src/commands/sshkeys-lint
from some gitolite clone, then follow these steps:
* get a copy of `~/.ssh/authorized_keys` from the server and put it in * get a copy of `~/.ssh/authorized_keys` from the server and put it in
`/tmp/foo` or something `/tmp/foo` or something
* cd to `~/.ssh` * cd to `~/.ssh`
* run `sshkeys-lint *.pub < /tmp/foo` * run `/path/to/sshkeys-lint *.pub < /tmp/foo`
This tells you, for each pubkey, what type of access (if any) it has to the Note that it is not trying to log in or anything -- it's just comparing
server. fingerprints as computed by `ssh-keygen -l`.
Note that it is not trying to log in or anything -- it's just comparing bits
of text (the contents of STDIN taken as an authkeys file, and the contents of
each of the `*.pub` files one by one).
> Note: It's also a stand-alone program, so even if your gitolite version is
> old, you can safely bring over just this program from a more recent
> gitolite and use it, without having to upgrade gitolite itself.
If the pubkey file you're interested in appears to have the correct access to If the pubkey file you're interested in appears to have the correct access to
the server, you're done with this step. the server, you're done with this step.
@ -327,7 +325,7 @@ need. Be careful:
The admin often has passwordless shell access to `git@server` already, and 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 then used that same key to get access to gitolite (i.e., copied that same
pubkey as YourName.pub and ran `gl-setup` on it). pubkey as YourName.pub and ran `gitolite setup` on it).
As a result, the same key appears twice in the authkeys file now, and since As a result, the same key appears twice in the authkeys file now, and since
the ssh server will always use the first match, the second occurrence (which the ssh server will always use the first match, the second occurrence (which
@ -335,11 +333,11 @@ invokes gitolite) is ignored.
To fix this, you have to use a different keypair for gitolite access. The To fix this, you have to use a different keypair for gitolite access. The
best way to do this is to create a new keypair, copy the pubkey to the server best way to do this is to create a new keypair, copy the pubkey to the server
as YourName.pub, then run `gl-setup YourName.pub` on the server. Remember to as YourName.pub, then run `gitolite setup -pk YourName.pub` on the server.
adjust your agent identities using ssh-add -D and ssh-add if you're using Remember to adjust your agent identities using ssh-add -D and ssh-add if
ssh-agent, otherwise these new keys may not work. you're using ssh-agent, otherwise these new keys may not work.
### #stsapp3_ appendix 3: ssh client may not be offering the right key ### #stsapp3 appendix 3: ssh client may not be offering the right key
* make sure the right private key is being offered. Run ssh in very * make sure the right private key is being offered. Run ssh in very
verbose mode and look for the word "Offering", like so: verbose mode and look for the word "Offering", like so:
@ -348,7 +346,7 @@ ssh-agent, otherwise these new keys may not work.
If some keys *are* being offered, but not the key that was supposed to be If some keys *are* being offered, but not the key that was supposed to be
used, you may be using ssh-agent (next bullet). You may also need to used, you may be using ssh-agent (next bullet). You may also need to
create some host aliases in `~/.ssh/config` ([appendix 4][sshhostaliases]). create some host aliases in `~/.ssh/config` ([appendix 4][ssh-ha]).
* (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no * (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no
identities." or "Could not open a connection to your authentication identities." or "Could not open a connection to your authentication
@ -361,7 +359,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 In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
the access again. the access again.
### F=sshhostaliases appendix 4: host aliases ### #ssh-ha appendix 4: ssh host aliases
(or "making git use the right options for ssh") (or "making git use the right options for ssh")
@ -397,10 +395,10 @@ way to do this, as far as I know.
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
### #stsapp5_ appendix 5: why bypassing gitolite causes a problem ### #ybpfail appendix 5: why bypassing gitolite causes a problem
When you bypass gitolite, you end up running your normal shell instead of the When you bypass gitolite, you end up running your normal shell instead of the
special gitolite entry point script `gl-auth-command`. special gitolite entry point script `gitolite-shell`.
This means commands (like 'info') are interpreted by the shell instead of This means commands (like 'info') are interpreted by the shell instead of
gitolite. gitolite.

12
doc/extras/ssh.mkd
View file

@ -2,10 +2,10 @@
There are two documents you need to read, in order: There are two documents you need to read, in order:
* [gitolite and ssh][glssh] -- this explains how gitolite uses openssh's * [Gitolite and ssh][glssh] explains how gitolite uses openssh features to
features to provide any number of virtual users over just one actual create any number of virtual users over just one actual (unix) user, and
(unix) user, and so on distinguish between them by their public keys.
* [ssh troubleshooting][sts] -- this is a rather long document but as far * [Ssh troubleshooting][sts] is a rather long document that, as far as I
as I know almost every known ssh related issue is in here. If you find know, covers almost every known ssh related issue. If you find something
something missing, send me an email with details. missing, send me an email with details so I can update it.

6
doc/extras/unique.mkd
View file

@ -1,6 +0,0 @@
# unique setups
This page is for unique setups that I support. At present there is only one
-- Fedora.

87
doc/files.mkd Normal file
View file

@ -0,0 +1,87 @@
# files involved in gitolite
## install
Let's say you start from a totally clean slate:
$ pwd
/home/gl-test
$ ls -a
. .. .bash_logout .bash_profile .bashrc
You run `git clone -b g3 git://github.com/sitaramc/gitolite` (the '-b' option
does the equivalent of 'git checkout g3' after the clone is done).
Now you have
$ ls -aF
./ ../ .bash_logout .bash_profile .bashrc gitolite/
$ ls -aF gitolite
./ ../ check-g2-compat* doc/ dot.pl .git/ install* src/ t/
If we were an existing user, we'd run the migration checker 'check-g2-compat'
(see [here][g2migr]). For now we're only interested in "gitolite/src", so:
$ ls -aF gitolite/src
./ ../ commands/ gitolite* Gitolite/ gitolite-shell* syntactic-sugar/ triggers/ VREF/
We check our PATH to make sure `$HOME/bin` is in it:
$ echo $PATH
/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/gl-test/.local/bin:/home/gl-test/bin
Since it is, we run `mkdir bin; gitolite/install -ln`, and get:
$ mkdir bin
$ gitolite/install -ln
$ ls -aF
./ ../ .bash_logout .bash_profile .bashrc bin/ gitolite/
$ ls -aF bin
./ ../ gitolite@
$ file bin/gitolite
bin/gitolite: symbolic link to `/home/gl-test/gitolite/src/gitolite'
That's the install done. At the end of it, we have just *one* symlink in
`$HOME/bin`; everything else is in a different directory.
## setup
Now you copy your pubkey (typically `id_rsa.pub`) from your workstation to the
server, then run `gitolite setup -pk "yourname.pub"`. Which gives you this:
$ ls -aF
./ .bash_logout .bashrc gitolite/ .gitolite.rc repositories/ .ssh/
../ .bash_profile bin/ .gitolite/ projects.list sitaram.pub
$ ls -aF bin
./ ../ gitolite@
$ ls -aF .gitolite
./ ../ conf/ hooks/ keydir/ logs/
$ ls -aF repositories
./ ../ gitolite-admin.git/ testing.git/
$ ls -aF .ssh
./ ../ authorized_keys*
And that's the setup done. At the end of this step, you have
* `~/bin/gitolite` -- a symlink to `~/gitolite/src/gitolite`. The target of
this symlink tells gitolite where the rest of the code is.
* `~/gitolite/src` -- the rest of the code.
* `~/.gitolite` -- the gitolite "admin" directory. The only thing you
should directly touch here are the [log][] files and [hooks][]. (I.e., do
NOT change the conf or keydir contents here; see adding [users][] and
[repos][] for how to do that.
* `~/.gitolite.rc` -- the [rc][] file.
* `~/repositories` -- which contains all the repositories that gitolite will
be managing.
* `~/.ssh` -- which contains (at least) the `authorized_keys` file that
provides access to users. You can look inside that file and correlate it
with what the [ssh][] docs tell you, if you wish.

94
doc/fm2mt.pl Executable file
View file

@ -0,0 +1,94 @@
#!/usr/bin/perl
use strict;
use warnings;
use 5.10.0;
# usage: ./fm2mt.pl < g3-master-toc.mm > master-toc.mkd
use HTML::Entities;
sub out { my $out = shift; print $out; }
# freemind to "dense" HTML
my @in = fm2indent();
out("# gitolite documentation");
my $started = 0;
for (@in) {
my($indent, $text) = split ' ', $_, 2;
$indent--;
if (not $indent) {
out "\n\n## $text\n";
$started = 0;
next;
}
if ($indent == 1) {
# (dense mode) $text = color("red", $text);
}
if ($indent <= 2) {
# (dense mode) $text = size(2 - $indent, $text);
} else {
# 3 or more
# (dense mode) $text = ("/" x ($indent-4)) . color("gray", $text);
}
# normal mode
$text = "\n" . (" " x ($indent-1)) . " * $text";
# (dense mode) out " -- " if $started++;
out $text;
}
sub size {
my ($s, $t) = @_;
return "<font size=\"+" . $s . "\">$t</font>" if $s;
return $t;
}
sub color {
my ($c, $t) = @_;
return "<font color=\"$c\">$t</font>";
}
sub get_indent {
my $_ = shift;
chomp;
return () unless /\S/;
if (/^(#+) (.*)/) {
return (length($1)-1, $2);
}
if (/^( +) \* (.*)/) {
my $t = $2;
my $i = length($1);
die 1 if $i % 4;
$i = $i/4 + 3;
return ($i, $t);
}
return ();
}
sub fm2indent {
my @out = ();
my $indent=0;
while (<>)
{
next unless /^<node / or /^<\/node/;
if (/^<\/node>$/)
{
$indent--;
next;
}
next unless /TEXT="([^"]*)"/;
my $text = decode_entities($1);
push @out, "\n$indent $text" if $indent;
$indent++ unless (/\/>/);
}
return @out;
}

19
doc/g2incompat.mkd
View file

@ -7,24 +7,27 @@ severity. **The ones in the first section are IMPORTANT because they allow
access that was previously not allowed -- please fix your config before using access that was previously not allowed -- please fix your config before using
the new gitolite!** the new gitolite!**
### fallthru in NAME rules ### NAME rules
Fallthru on all VREFs is "success" now, so any NAME/ rules you have **MUST** 1. NAME/ rules must be changed to VREF/NAME/
change the ruleset in some way to maintain the same restrictions. The
simplest is to add the following line to the end of each repo's rule list:
- NAME/ = @all 2. Fallthru on all VREFs is "success" now, so any NAME/ rules you have
**MUST** change the ruleset in some way to maintain the same restrictions.
The simplest is to add the following line to the end of each repo's rule
list:
- VREF/NAME/ = @all
### subconf command in admin repo ### subconf command in admin repo
(This is also affected by the previous issue, 'fallthru in NAME rules'; please (This is also affected by the previous issue, 'NAME rules'; please read that
read that as well). as well).
If you're using delegation in your admin conf setup, please add the following If you're using delegation in your admin conf setup, please add the following
lines to the end of the gitolite-admin rules in your conf/gitolite.conf file: lines to the end of the gitolite-admin rules in your conf/gitolite.conf file:
repo gitolite-admin repo gitolite-admin
- NAME/ = @all - VREF/NAME/ = @all
subconf "fragments/*.conf" subconf "fragments/*.conf"

2
doc/g2migr.mkd
View file

@ -53,7 +53,7 @@ put that contain the words "see docs":
same as above same as above
* `fallthru in NAME rules` * `NAME rules`
**This is a significant difference and affects access badly (gives access **This is a significant difference and affects access badly (gives access
that would otherwise not be given)**. Please see the [list of non-RC that would otherwise not be given)**. Please see the [list of non-RC

153
doc/g3-master-toc.mm Executable file
View file

@ -0,0 +1,153 @@
<map version="0.9.0">
<!-- To view this file, download free mind mapping software FreeMind from http://freemind.sourceforge.net -->
<node CREATED="1331107648858" ID="ID_187992057" MODIFIED="1333299050498" TEXT="g3-master-index">
<node CREATED="1333299038338" ID="ID_1574733847" MODIFIED="1333536460445" POSITION="right" TEXT="[Introduction][index]">
<node CREATED="1333466035663" ID="ID_974293172" MODIFIED="1333536536267" TEXT="(for [current][g2] gitolite (v2) users)"/>
<node CREATED="1333466047943" ID="ID_1283272433" MODIFIED="1333536530576" TEXT="[quick links][ql]"/>
<node CREATED="1333326589821" ID="ID_195282410" MODIFIED="1333340829999" TEXT="[what][] is gitolite"/>
<node CREATED="1333326593927" ID="ID_1110367572" MODIFIED="1333340841907" TEXT="[why][] might you need it"/>
<node CREATED="1333536552704" ID="ID_1607033994" MODIFIED="1333536835577" TEXT="[contact][] info, mailing list, IRC channel"/>
<node CREATED="1333536577819" ID="ID_1858469252" MODIFIED="1333536835576" TEXT="[license][] info"/>
</node>
<node CREATED="1333300010980" ID="ID_1728019284" MODIFIED="1333616327427" POSITION="right" TEXT="help for [emergencies][]">
<node CREATED="1333300016176" ID="ID_30257493" MODIFIED="1333453799784" TEXT="[lost][lost-key] admin key/access"/>
<node CREATED="1333327185236" ID="ID_910862972" MODIFIED="1333471145297" TEXT="[bypass][]ing gitolite"/>
<node CREATED="1333328183948" ID="ID_564351456" MODIFIED="1333453834497" TEXT="[clean][]ing out a botched install"/>
<node CREATED="1333326808789" ID="ID_54380370" MODIFIED="1333631901528" TEXT="[common][ce] errors (TBD)"/>
<node CREATED="1333597279461" ID="ID_547537696" MODIFIED="1333631907824" TEXT="[uncommon][ue] errors"/>
<node CREATED="1333328539885" ID="ID_162892604" MODIFIED="1333527642132" TEXT="things that are [not gitolite problems][ngp]"/>
</node>
<node CREATED="1333466070125" ID="ID_1329733023" MODIFIED="1333527838066" POSITION="right" TEXT="[WARNINGS][]"/>
<node CREATED="1333326560775" ID="ID_1030406941" MODIFIED="1333631954561" POSITION="right" TEXT="[quick][qi] install, setup, and clone"/>
<node CREATED="1333465293309" ID="ID_1405252383" MODIFIED="1333526188455" POSITION="right" TEXT="[install][]">
<node CREATED="1333327826145" ID="ID_519306224" MODIFIED="1333467083667" TEXT="notes and naming conventions"/>
<node CREATED="1333328069297" ID="ID_624460163" MODIFIED="1333465312762" TEXT="requirements">
<node CREATED="1333328127550" ID="ID_368487912" MODIFIED="1333537067223" TEXT="your skills"/>
<node CREATED="1333328123855" ID="ID_1146334636" MODIFIED="1333339551947" TEXT="server"/>
<node CREATED="1333328126057" ID="ID_899541385" MODIFIED="1333328127275" TEXT="client"/>
</node>
<node CREATED="1333328151051" ID="ID_1577506173" MODIFIED="1333465323159" TEXT="getting the software"/>
<node CREATED="1333328156575" ID="ID_208746322" MODIFIED="1333465333727" TEXT="the actual install"/>
<node CREATED="1333467553366" ID="ID_926614739" MODIFIED="1333467556140" TEXT="upgrading"/>
<node CREATED="1333328592876" ID="ID_237795046" MODIFIED="1333466108368" TEXT="packaging gitolite"/>
<node CREATED="1333327776230" ID="ID_1431739921" MODIFIED="1333467569937" TEXT="migrating"/>
</node>
<node CREATED="1333301194129" ID="ID_746196740" MODIFIED="1333471816303" POSITION="right" TEXT="[setup][]"/>
<node CREATED="1333299674481" ID="ID_714407264" MODIFIED="1333528325006" POSITION="right" TEXT="gitolite [admin][]istration">
<node CREATED="1333299694885" ID="ID_1916098884" MODIFIED="1333537908466" TEXT="[server][]-side">
<node CREATED="1333327917312" ID="ID_1266878047" MODIFIED="1333537539764" TEXT="([link][WARNINGS]: important cautions on server side activity)"/>
<node CREATED="1333301196071" ID="ID_760433725" MODIFIED="1333537537075" TEXT="changing settings in the [rc][] file"/>
<node CREATED="1333537546089" ID="ID_2500021" MODIFIED="1333537553267" TEXT="installing custom [hooks][]"/>
<node CREATED="1333537563152" ID="ID_472486055" MODIFIED="1333537616205" TEXT="([link][existing]: moving existing repos into gitolite)"/>
</node>
<node CREATED="1333299702754" ID="ID_609351656" MODIFIED="1333537921248" TEXT="[access control][conf] (the gitolite.conf file)">
<node CREATED="1333566502470" ID="ID_1931486515" MODIFIED="1333583575642" TEXT="[example][confex] of a conf file"/>
<node CREATED="1333300715360" ID="ID_41940351" MODIFIED="1333547591053" TEXT="basic [syntax][]">
<node CREATED="1333300732151" ID="ID_1494555007" MODIFIED="1333300733944" TEXT="include files"/>
<node CREATED="1333300741424" ID="ID_416012685" MODIFIED="1333513004487" TEXT="([link][sugar]: syntactic sugar)"/>
</node>
<node CREATED="1333300461624" ID="ID_1848362678" MODIFIED="1333529103568" TEXT="[groups][] (of users and repos)">
<node CREATED="1333300884900" ID="ID_1412135290" MODIFIED="1333300893755" TEXT="special: &apos;@all&apos;"/>
<node CREATED="1333300437860" ID="ID_897670108" MODIFIED="1333300770020" TEXT="(link: storing user group info in LDAP)"/>
</node>
<node CREATED="1333299715546" ID="ID_1916374076" MODIFIED="1333529107922" TEXT="adding and removing [users][]">
<node CREATED="1333326840977" ID="ID_1723439755" MODIFIED="1333517370375" TEXT="multiple keys per user"/>
</node>
<node CREATED="1333299719741" ID="ID_275665792" MODIFIED="1333529112764" TEXT="adding and removing [repos][]">
<node CREATED="1333327426500" ID="ID_1964948889" MODIFIED="1333518450199" TEXT="renaming repos"/>
</node>
<node CREATED="1333300309235" ID="ID_1437714859" MODIFIED="1333529121211" TEXT="defining access [rules][]">
<node CREATED="1333584760127" ID="ID_469376519" MODIFIED="1333584767343" TEXT="what does a rule look like?"/>
<node CREATED="1333326976405" ID="ID_563906836" MODIFIED="1333584770230" TEXT="when are the rules checked?"/>
<node CREATED="1333535584526" ID="ID_957313656" MODIFIED="1333584774497" TEXT="how are the rules matched?"/>
<node CREATED="1333301045521" ID="ID_1228046254" MODIFIED="1333536127886" TEXT="summary of [permissions][perms]"/>
<node CREATED="1333599586661" ID="ID_1785519868" MODIFIED="1333599590134" TEXT="additional topics">
<node CREATED="1333599591055" ID="ID_1379421123" MODIFIED="1333599606966" TEXT="[rule accumulation][rule-accum]"/>
<node CREATED="1333599613910" ID="ID_1760840175" MODIFIED="1333599634987" TEXT="applying [deny rules][deny-rules] during the pre-git check"/>
</node>
<node CREATED="1333535705100" ID="ID_1768473150" MODIFIED="1333535718347" TEXT="([link][refex]: refexes)"/>
<node CREATED="1333535719180" ID="ID_431454064" MODIFIED="1333626093118" TEXT="([link][write-types]: different types of write operations)"/>
<node CREATED="1333300541352" ID="ID_1407372791" MODIFIED="1333536011832" TEXT="([link][vref]: virtual refs)"/>
</node>
<node CREATED="1333521966550" ID="ID_462181887" MODIFIED="1333529126015" TEXT="gitolite [options][]"/>
<node CREATED="1333521972558" ID="ID_1180232837" MODIFIED="1333536152124" TEXT="&quot;[git config][git-config]&quot; keys and values"/>
<node CREATED="1333299726939" ID="ID_1229702100" MODIFIED="1333601090414" TEXT="[&quot;wild&quot;][wild] repos (user created repos)">
<node CREATED="1333329088398" ID="ID_533855844" MODIFIED="1333630553509" TEXT="quick introduction"/>
<node CREATED="1333599529910" ID="ID_1393418948" MODIFIED="1333630403135" TEXT="(admin) declaring wild repos in the conf file"/>
<node CREATED="1333629999807" ID="ID_139250181" MODIFIED="1333630432141" TEXT="(user) [creating][create] a specific repo"/>
<node CREATED="1333599928516" ID="ID_439610891" MODIFIED="1333600901677" TEXT="repo patterns"/>
<node CREATED="1333329137043" ID="ID_1876270574" MODIFIED="1333599539626" TEXT="roles"/>
<node CREATED="1333329119800" ID="ID_1196899132" MODIFIED="1333600898568" TEXT="adding other roles">
<node CREATED="1333630582435" ID="ID_792555451" MODIFIED="1333630596161" TEXT="[IMPORTANT WARNING ABOUT THIS FEATURE][rolenamewarn]"/>
</node>
<node CREATED="1333299760157" ID="ID_1787203633" MODIFIED="1333600934866" TEXT="listing wild repos"/>
<node CREATED="1333299751513" ID="ID_1503072743" MODIFIED="1333600958915" TEXT="deleting wild repos"/>
</node>
</node>
</node>
<node CREATED="1333326619348" ID="ID_697668065" MODIFIED="1333537363837" POSITION="right" TEXT="what your [user][]s need to know"/>
<node CREATED="1333300236173" ID="ID_1026631043" MODIFIED="1333607025161" POSITION="right" TEXT="[special][] features/setups">
<node CREATED="1333327232490" ID="ID_849345095" MODIFIED="1333631333199" TEXT="[disabling pushes][writable] to take backups"/>
<node CREATED="1333300243659" ID="ID_106425369" MODIFIED="1333604404937" TEXT="[personal][pers] branches"/>
<node CREATED="1333300501314" ID="ID_1819387758" MODIFIED="1333606161557" TEXT="[delegating][deleg] access control responsibilities">
<node CREATED="1333606177736" ID="ID_1153299625" MODIFIED="1333606191734" TEXT="([link][NAME]: the NAME VREF)"/>
<node CREATED="1333300531135" ID="ID_206710372" MODIFIED="1333606536438" TEXT="the [subconf][] command"/>
</node>
<node CREATED="1333300925828" ID="ID_1848845001" MODIFIED="1333626115598" TEXT="([link][partial-copy]: faking selective READ control)"/>
</node>
<node CREATED="1333327469941" ID="ID_1230549116" MODIFIED="1333607053576" POSITION="right" TEXT="interfacing with [external][] tools">
<node CREATED="1333327476469" ID="ID_1887257091" MODIFIED="1333327480072" TEXT="gitweb">
<node CREATED="1333504877358" ID="ID_1448276401" MODIFIED="1333625357439" TEXT="changing the [UMASK][umask]"/>
</node>
<node CREATED="1333327480559" ID="ID_513431483" MODIFIED="1333327483014" TEXT="git-daemon"/>
</node>
<node CREATED="1333326753755" ID="ID_16865998" MODIFIED="1333625410973" POSITION="right" TEXT="[mirroring][]"/>
<node CREATED="1333299976094" ID="ID_1948442779" MODIFIED="1333625437290" POSITION="right" TEXT="[rare][]/one-time activities">
<node CREATED="1333299985915" ID="ID_530631392" MODIFIED="1333471109149" TEXT="moving [existing][] repos into gitolite"/>
<node CREATED="1333300099453" ID="ID_1521618753" MODIFIED="1333625463686" TEXT="[moving][] servers"/>
</node>
<node CREATED="1333299141061" ID="ID_37630832" MODIFIED="1333625569805" POSITION="right" TEXT="[customisation][cust]">
<node CREATED="1333299458493" ID="ID_992003929" MODIFIED="1333625583059" TEXT="types of non-core programs">
<node CREATED="1333625624553" ID="ID_1205434644" MODIFIED="1333639834277" TEXT="([link][non-core]: non-core programs shipped with gitolite)"/>
</node>
<node CREATED="1333625674563" ID="ID_603892527" MODIFIED="1333625679247" TEXT="[commands][]"/>
<node CREATED="1333625679584" ID="ID_230664255" MODIFIED="1333625682401" TEXT="[hooks][]"/>
<node CREATED="1333625689987" ID="ID_112339937" MODIFIED="1333625696128" TEXT="syntactic [sugar][]"/>
<node CREATED="1333625703698" ID="ID_1165978069" MODIFIED="1333625715099" TEXT="([link][triggers]: triggers)"/>
<node CREATED="1333625717605" ID="ID_1483309372" MODIFIED="1333625734532" TEXT="([link][vref]: VREFs)"/>
<node CREATED="1333625757836" ID="ID_1102952567" MODIFIED="1333625766871" TEXT="[developer notes][dev-notes]">
<node CREATED="1333625797339" ID="ID_1760918724" MODIFIED="1333625812051" TEXT="environment variables and other inputs"/>
<node CREATED="1333625816655" ID="ID_420128580" MODIFIED="1333625818681" TEXT="APIs">
<node CREATED="1333625820871" ID="ID_672321981" MODIFIED="1333625823262" TEXT="the shell API"/>
<node CREATED="1333625823632" ID="ID_206993094" MODIFIED="1333625825547" TEXT="the perl API"/>
</node>
<node CREATED="1333625864473" ID="ID_1009525945" MODIFIED="1333625888705" TEXT="writing your own...">
<node CREATED="1333625889803" ID="ID_323248071" MODIFIED="1333625890797" TEXT="hooks"/>
<node CREATED="1333625891081" ID="ID_774724756" MODIFIED="1333625895322" TEXT="commands"/>
<node CREATED="1333625956866" ID="ID_1107908272" MODIFIED="1333625960910" TEXT="trigger programs"/>
<node CREATED="1333625961452" ID="ID_159826002" MODIFIED="1333625967173" TEXT="sugar"/>
</node>
</node>
</node>
<node CREATED="1333300577608" ID="ID_583410113" MODIFIED="1333537235253" POSITION="right" TEXT="background info">
<node CREATED="1333299088617" ID="ID_1919571562" MODIFIED="1333537208005" TEXT="[files and directories][files] involved in install+setup"/>
<node CREATED="1333300378018" ID="ID_584192327" MODIFIED="1333536676126" TEXT="[auth][]entication versus authorisation">
<node CREATED="1333300390847" ID="ID_384452374" MODIFIED="1333453722001" TEXT="interfacing with [other authentication][otherauth] systems"/>
<node CREATED="1333300437860" ID="ID_99922512" MODIFIED="1333453750215" TEXT="getting user group info from [LDAP][ldap]"/>
</node>
<node CREATED="1333301124871" ID="ID_931083276" MODIFIED="1333453771459" TEXT="[ssh][]"/>
<node CREATED="1333301127955" ID="ID_1527577153" MODIFIED="1333453780482" TEXT="[regular expressions][regex]"/>
</node>
<node CREATED="1333300587911" ID="ID_91544543" MODIFIED="1333641141649" POSITION="right" TEXT="contributed software, tools, and documentation">
<node CREATED="1333300608550" ID="ID_1486318266" MODIFIED="1333626152668" TEXT="TBD"/>
</node>
<node CREATED="1333301296248" ID="ID_571518549" MODIFIED="1333526198202" POSITION="right" TEXT="TBD">
<node CREATED="1333327082853" ID="ID_488765250" MODIFIED="1333327089444" TEXT="log file format, LOG_EXTRA"/>
<node CREATED="1333301298504" ID="ID_60946303" MODIFIED="1333301300418" TEXT="smart http"/>
<node CREATED="1333301308136" ID="ID_1900285587" MODIFIED="1333301311863" TEXT="hub"/>
<node CREATED="1333301312124" ID="ID_843247306" MODIFIED="1333301313052" TEXT="sskm"/>
<node CREATED="1333328274461" ID="ID_248606591" MODIFIED="1333328277083" TEXT="mob branches"/>
<node CREATED="1333328277387" ID="ID_1027016949" MODIFIED="1333328280083" TEXT="password access"/>
</node>
</node>
</map>

66
doc/git-config.mkd Normal file
View file

@ -0,0 +1,66 @@
# "git-config" keys and values
Here's all you want to know about setting repo-specific git-config values.
(Original version thanks to teemu dot matilainen at iki dot fi)
> ----
> **Note**: this won't work unless the rc file has the right settings;
> please see `$GIT_CONFIG_KEYS` in the [rc file doc][rc].
> ----
The syntax is simple:
config sectionname.keyname = [optional value_string]
For example:
repo gitolite
config hooks.mailinglist = gitolite-commits@example.tld
config hooks.emailprefix = "[gitolite] "
config foo.bar = ""
config foo.baz =
This does either a plain "git config section.key value" (for the first 3
examples above) or "git config --unset-all section.key" (for the last
example). Other forms of the `git config` command (`--add`, the
`value_regex`, etc) are not supported.
> ----
> **WARNING**: simply deleting the config line from the `conf/gitolite.conf`
> file will *not* delete the variable from `repo.git/config`. The syntax in
> the last example is the *only* way to make gitolite execute a
> `--unset-all` operation on the given key.
> ----
You can also use the special value `%GL_REPO` in the string to save typing:
repo foo bar baz
config hooks.mailinglist = %GL_REPO-commits@example.tld
config hooks.emailprefix = "[%GL_REPO] "
You can repeat the 'config' line as many times as you like, and the last
occurrence will be the one in effect. This allows you to override settings
just for one project, as in this example:
repo @all
config hooks.mailinglist = %GL_REPO-commits@example.tld
config hooks.emailprefix = "[%GL_REPO] "
repo customer-project
# different mailing list
config hooks.mailinglist = announce@customer.tld
The "delete config variable" syntax can also be used, if you wish:
repo secret # no emails for this one please
config hooks.mailinglist =
config hooks.emailprefix =
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.

6
doc/group.mkd → doc/groups.mkd
View file

@ -1,6 +1,4 @@
# parts of the conf file # group definitions
## #group group definitions
You can group repos or users for convenience. The syntax is the same for both You can group repos or users for convenience. The syntax is the same for both
and does not distinguish; until you *use* the group name it could really be and does not distinguish; until you *use* the group name it could really be
@ -26,7 +24,7 @@ right there (meaning later additions will not appear in the second group).
# wally is NOT part of @staff # wally is NOT part of @staff
### special group `@all` ## special group `@all`
`@all` is a special group name that is often convenient to use if you really `@all` is a special group name that is often convenient to use if you really
mean "all repos" or "all users". mean "all repos" or "all users".

46
doc/index.mkd
View file

@ -5,49 +5,47 @@ fine-grained access control and many more powerful features.
Here's more on [what][] it is and [why][] you might need it. Here's more on [what][] it is and [why][] you might need it.
<font color="gray">
## #g2 (for current gitolite (v2) users)
For current gitolite (call it "g2" for convenience) users, For current gitolite (call it "g2" for convenience) users,
* [Why][g3why] I rewrote gitolite. * [Why][g3why] I rewrote gitolite.
* Development [status][dev-status] (**should change often for a while**) * Development [status][dev-status].
* Specific migration [issues and steps][g2migr]. * Specific migration [issues and steps][g2migr].
Quick links: </font>
* [Minimum requirements][minreq]. ## #ql quick links
* Here's how to [get started][qi] installing and setting it up
* Minimum [requirements][req].
* Here's how to do a [quick install, setup, and clone][qi].
* Don't know ssh well enough? [Learn][ssh]. It's **IMPORTANT**. * Don't know ssh well enough? [Learn][ssh]. It's **IMPORTANT**.
* [Add users and repos][add]. * Add [users][] and [repos][].
* Learn about fine-grained access control with the [conf][] file * Learn about fine-grained access control with the [conf][] file.
* Explain gitolite to your [users][]. * Explain gitolite to your [users][user].
Not so "quick" links: The rest of the documentation is in the "master index" link at the top of each
page on this website. This is the first place you should search when looking
* The "master table of contents" link at the top of each page is the for specific information.
**first** place you should check when looking for anything.
* Want to do more than just add users and repos and control their access?
Here's how to [customise][cust] your server installation.
Additional reading for Unix newbies:
* [Regular Expressions][regex]
## #what What is gitolite? ## #what What is gitolite?
Gitolite is an access control layer on top of git. Here are the features that Gitolite is an access control layer on top of git. Here are the features that
most people see: most people see:
* use a single unix user ("real" user) on the server * Use a single unix user ("real" user) on the server.
* provide access to many gitolite users * Provide access to many gitolite users:
* they are not "real" users * they are not "real" users
* they do not get shell access * they do not get shell access
* control access to many git repositories * Control access to many git repositories:
* read access controlled at the repo level * read access controlled at the repo level
* write access controlled at the branch/tag/file/directory level, * write access controlled at the branch/tag/file/directory level,
including who can rewind, create, and delete branches/tags including who can rewind, create, and delete branches/tags
* can be installed without root access, assuming git and perl are already * Can be installed without root access, assuming git and perl are already
installed installed.
* authentication is most commonly done using sshd, but you can also use * Authentication is most commonly done using sshd, but you can also use
httpd if you prefer (this may require root access). httpd if you prefer (this may require root access).
## #contact contact ## #contact contact

168
doc/install.mkd
View file

@ -1,37 +1,122 @@
# different ways to install gitolite # installing gitolite
Gitolite has only one server side "command" now, much like git itself. And
it's been designed so that you don't even really have to *install* it, as you
will see.
**NOTE**: if you're migrating from g2, there are some settings that MUST be **NOTE**: if you're migrating from g2, there are some settings that MUST be
dealt with **before** running `gitolite setup`; please read the [g2 dealt with **before** running `gitolite setup`; please read the [g2
migration][g2migr] page and linked pages, and especially the one on migration][g2migr] page and linked pages, and especially the one on
'presetting the rc file][rc-preset]. [presetting the rc file][rc-preset].
## simplest ## notes and naming conventions
1. Put all of `src` in one place, doesn't matter where; let's call it Gitolite uses a single "real" (i.e., unix) user to provide secure access to
/foo/bar. git repos to any number of "virtual" users, without giving them a shell.
2. Use the full path to run any gitolite commands, for example: The real user used is called the **hosting user**. Typically this user is
*git*, and that is what we will use throughout the documentation. However
RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
and examples accordingly.
/foo/bar/gitolite setup -pk sitaram.pub Notes:
## almost as simple * Any unix user can be a hosting user.
* Which also means you can have several hosting users on the same machine.
* The URLs used will be of the form `git@host:reponame` (or its longer
equivalent starting with `ssh://`). The `.git` at the end is optional. I
recommend you leave it out, so your reponames are consistent with what the
conf file uses.
1. (same as above) ## #req requirements
2. Symlink /foo/bar/gitolite to some directory that is on your PATH. For ### your skills
example:
ln -sf /foo/bar/gitolite ~/bin * If you're installing gitolite, you're a "system admin", like it or not.
Ssh is therefore a necessary skill. Please take the time to learn at
least enough to get passwordless access working.
Now you can just say * You also need to be somewhat familiar with git itself. You cannot
administer a whole bunch of git repositories if you don't know the basics
of git.
gitolite setup -pk sitaram.pub * Some familiarity with Unix and shells is probably required.
## packagers * Regular expressions are a big part of gitolite in many places but
familiarity is not necessary to do *basic* access control.
### server
* any Unix system with a posix compatible "sh".
* git version 1.6.6 or later
* perl 5.8.8 or later
* openssh (almost any version). Optional if you're using the http backend
(which is still a TODO item!)
* a dedicated Unix userid to be the hosting user, usually "git" but it can
be any user, even your own normal one. (If you're using an RPM/DEB the
install probably created one called "gitolite").
Also see the [WARNINGS][] page for more on what gitolite expects on the server
side.
### client
* openssh client
* git 1.6.6 or later. Almost any git client will work, as long as it knows
how to use ssh keys and send the right one along.
## getting the software
git clone -b g3 git://github.com/sitaramc/gitolite
The -b g3' is needed until g3 becomes "master". Current estimates put this
around June 2012, when the old gitolite (upto v2.x) will be retired and
supported only for security issues.
## the actual install
Gitolite has only one server side "command" now, much like git itself. This
command is `gitolite`. You don't need to place it anywhere special; worst
case you run it with the full path.
"Installation" consists of the following options:
1. Keep the sources anywhere and use the full path to run the `gitolite`
command.
2. Keep the sources anywhere and symlink *just* the `gitolite` program to
some directory on your `$PATH`.
3. Copy the sources somewhere and use that path to run the `gitolite`
command.
Option 2 is the best for general use.
There is a program called 'install' that helps you do these easily. Assuming
your cloned the repo like this:
git clone -b g3 git://github.com/sitaramc/gitolite
you can run the 'install' command in 3 different ways:
# option 1
gitolite/install
# option 2
gitolite/install -ln
# defaults to $HOME/bin, or use a specific directory:
gitolite/install -ln /usr/local/bin
# option 3
gitolite/install -to /usr/local/gitolite/bin
Creating a symlink doesn't need a separate program but 'install' also runs
`git describe` to create a VERSION file, which, trust me, is important!
**Next step**: run [**setup**][setup].
## upgrading
Just put the new version on top of wherever you kept the old one. That's it.
If you feel it should require a little more effort, pretend I said "you have
to then run `gitolite setup`". Won't hurt...
## packaging gitolite
1. Put src/Gitolite in `/usr/share/perl5/vendor_perl` or some such place. 1. Put src/Gitolite in `/usr/share/perl5/vendor_perl` or some such place.
@ -39,25 +124,44 @@ migration][g2migr] page and linked pages, and especially the one on
git's 150 executables in /usr/libexec/git-core, so maybe git's 150 executables in /usr/libexec/git-core, so maybe
/usr/libexec/gitolite?) /usr/libexec/gitolite?)
3. Symlink 'gitolite' to /usr/bin or something, similar to step 2 above, 3. Symlink 'gitolite' to /usr/bin or something, similar to option 2.
OR **Bottom line**:
Put it directly in /usr/bin, and hardcode `GL_BINDIR` into it to tell it
where the others are. I'd prefer it if you did not do this but you can.
----
Bottom line:
* `GL_BINDIR` must point to a place that contains `commands`, `VREF`, and * `GL_BINDIR` must point to a place that contains `commands`, `VREF`, and
`syntactic-sugar` (so they must all be sibling directories). `syntactic-sugar` (so they must all be sibling directories).
* The `Gitolite` directory can also be there, or it can be anywhere in * The `Gitolite` directory can also be there, or it can be anywhere in
perl's `@INC` path. perl's `@INC` path.
## upgrading ## migrating
Just put the new version on top of wherever you kept the old one. That's it. There are a lot of migration hints and notes; see links at the top of this
document.
If you feel it should require a little more effort, pretend I said "you have But here's the **bottom line** on migrating:
to then run `gitolite setup`". Can't hurt...
Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
any repository except the gitolite-admin repo. The only thing it will
normally touch is the `update` hook. So one fool-proof way of "migrating"
from any older gitolite is this:
1. Wipe out the old gitolite, but **carefully**
* clone `~/repositories/gitolite-admin.git` to someplace, then delete it
(and only it, none of the other repos!) from `~/repositories`
* rename `~/.gitolite.rc` to something else
* move the ~/.gitolite/logs` directory somewhere else, then delete `~/.gitolite`
2. Install gitolite g3; see [quick install and setup][qi] or [install][]
followed by [setup][].
3. Make sure your gitolite-admin clone has the correct pubkey for the
administrator in its `keydir` directory, then `git push -f` to the server
to overwrite the "default" admin repo created by the install.
4. Handle any errors, look for migration issues, etc., as described in the
links at the top of this page.
This also includes building up your new `~/.gitolite.rc` file.
You're done.

45
doc/list
View file

@ -1,45 +0,0 @@
index.mkd
why.mkd
g3why.mkd
dev-status.mkd
g2migr.mkd
g2rcdiff.mkd
g2incompat.mkd
g2dropped.mkd
g2alt.mkd
minreq.mkd
qi.mkd
install.mkd
add.mkd
users.mkd
conf.mkd
group.mkd
repo.mkd
rules.mkd
refex.mkd
write-types.mkd
rc.mkd
cust.mkd
triggers.mkd
vref.mkd
non-core.mkd
dev-notes.mkd
misc.mkd
pw.mkd
testing.mkd
extras/auth.mkd
extras/nagp.mkd
extras/regex.mkd
extras/ssh.mkd
extras/gitolite-and-ssh.mkd
extras/ssh-troubleshooting.mkd

32
doc/minreq.mkd
View file

@ -1,32 +0,0 @@
# minimum requirements for gitolite
**Client**:
* git 1.6.6 or greater
* an ssh client that can talk to an openssh server, and can generate keys in
openssh's default format (the pubkey is just one long line). Gitolite
will [not currently][pw1] convert such keys.
For people still using Windows, msysgit works fine. If you're using
[putty/plink][ens], God bless you. (It'll work, but I still want him to bless
you).
TODO: when smart http support works, ssh will no longer be a *requirement*,
merely a *strong* suggestion :-)
**Server**
* git 1.6.6 or greater
* perl 5.8.8 or greater
* an ssh server compatible with openssh, especially it's authorized keys
file format and features.
* any Unix or Unix like OS. That said, I've occasionally had some weird
reports from [Mac OSX servers][ens]; good luck.
* a single, dedicated, userid to host it (usually 'git' or 'gitolite').
These version numbers are subject to fine-tuning as I get feedback and make
fixes where possible and needed.
Sshd must be configured so that each users authkeys file is in the user's
`$HOME`, inside `.ssh/authorized_keys`, and not in some central
/var/something.

42
doc/mirroring.mkd
View file

@ -1,18 +1,19 @@
# mirroring using gitolite # mirroring using gitolite
**WARNING** existing gitolite mirroring users please note: significant changes **WARNING** existing gitolite mirroring users please note: **there are
in syntax and usage compared to g2. The most important change is that `config significant changes** in syntax and usage compared to g2. The most important
gitolite.mirror.master` changes to `option mirror.master`, and similarly for change is that `config gitolite.mirror.master` changes to `option
'slaves' and redirectOK. In addition, the special value for 'redirectOK' mirror.master`, and similarly for 'slaves' and redirectOK. In addition, the
changes from '1' to 'all'. The second big change is the disappearance of the special value for 'redirectOK' changes from '1' to 'all'. The second big
ambiguously named 'keys' (for example `gitolite.mirror.hourly` etc., in the change is the disappearance of the ambiguously named 'keys' (for example
old mirroring doc) -- all that complexity is yours to handle now :-) `gitolite.mirror.hourly` etc., in the old mirroring doc) -- all that
complexity is yours to handle now :-)
---- ----
Mirroring is simple: you have one "master" and one or more "slaves". The Mirroring is simple: you have one "master" server and one or more "slave"
slaves get updates only from the master; to the rest of the world they are at servers. The slaves get updates only from the master; to the rest of the
best read-only. world they are at best read-only.
Gitolite extends this simple notion in the following ways: Gitolite extends this simple notion in the following ways:
@ -52,12 +53,12 @@ file settings and syntax.
### the initial setup and the rc file ### the initial setup and the rc file
On each server: On **each** server:
* install gitolite normally. Make clones of each server's 'gitolite-admin' * install gitolite normally. Make clones of the server's 'gitolite-admin'
repo on your workstation so you can admin them all from one place. repo on your workstation so you can admin them all from one place.
* give each server a short, simple, "hostname" and set the HOSTNAME in the * give the server a short, simple, "hostname" and set the HOSTNAME in the
rc file to this name, for example 'mars'. rc file to this name, for example 'mars'.
* run ssh-keygen if needed and get an ssh key pair for the server. Copy the * run ssh-keygen if needed and get an ssh key pair for the server. Copy the
@ -65,14 +66,14 @@ On each server:
prefixed. So the pubkey for server 'mars' would be stored as prefixed. So the pubkey for server 'mars' would be stored as
'server-mars.pub'. 'server-mars.pub'.
* copy all keys to **each of** the admin repo clones on your workstation and * copy all keys to all the admin repo clones on your workstation and and add
and add them as usual. them as usual. This is an `O(N^2)` operation ;-)
You may have guessed that the prefix 'server-' is special, and You may have guessed that the prefix 'server-' is special, and
distinguishes a human user from a mirroring peer. distinguishes a human user from a mirroring peer.
* create "host" aliases on each machine to refer to all other machines. See * create "host" aliases to refer to all other machines. See [here][ssh-ha]
[here][ssh-ha] for what/why/how. for what/how.
The host alias for a host (in all other machines' `~/.ssh/config` files) The host alias for a host (in all other machines' `~/.ssh/config` files)
MUST be the same as the `HOSTNAME` in the referred host's MUST be the same as the `HOSTNAME` in the referred host's
@ -108,13 +109,12 @@ On each server:
because on the first push to the master it will update all the slaves because on the first push to the master it will update all the slaves
anyway. anyway.
* when that is all done and tested, **enable mirroring** on each server by * when that is all done and tested, **enable mirroring** by going through
going through the rc file and uncommenting all the lines mentioning the rc file and uncommenting all the lines mentioning `Mirroring`.
`Mirroring`.
### conf file settings and syntax ### conf file settings and syntax
Mirroring is defined by the following [option][]s. You can have different Mirroring is defined by the following [options][]. You can have different
settings for different repos, and of course some repos may not have any mirror settings for different repos, and of course some repos may not have any mirror
options at all -- they are then purely local. options at all -- they are then purely local.

132
doc/misc.mkd
View file

@ -1,132 +0,0 @@
# odds and ends
Most of these items don't fit anywhere or fit in more than one place or are of
the nature of background information.
## #include include files
Gitolite allows you to break up the configuration into multiple files and
include them in the main file for convenience.
include "foo.conf"
will include the contents of the file "foo.conf" from the "conf" directory.
Details:
* You can also use a glob (`include "*.conf"`), or put your include files
into subdirectories of "conf" (`include "foo/bar.conf"`), or both
(`include "repos/*.conf"`).
* Included files are always searched relative to the gitolite-admin repo's
"conf/" directory.
* If you ended up recursing, 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>
## #deny-rules applying deny rules at the pre-git access check
The access [rules][] rules section describes the problem. To recap, you want
this:
@staff = alice bob wally ashok
repo foo
RW+ = alice # line 1
RW+ dev = bob # line 2
- = wally # line 3
RW temp/ = @staff # line 4
to deny Wally even *read* access.
The way to do this is to add this line to the repo:
option deny-rules = 1
If you want this for all your repos, just add this somewhere at the top of
your conf file
repo @all
option deny-rules = 1
## #rule-accum rule accumulation
Gitolite was meant to collect rules from multiple places and apply them all.
For example, this:
repo foo
RW = u1
@gr1 = foo bar
repo @gr1
RW = u2
R = u3
repo @all
R = gitweb
is effectively the same as this, for repo foo:
repo foo
RW = u1
RW = u2
R = u3
R = gitweb
This extends to patterns also, but I'll leave an example for later.
## #subconf the subconf command
This is just like the include command:
subconf "foo/bar.conf" # example 1
subconf "foo/*.conf" # example 2
with the difference that, for the duration of the file(s) being included, a
subconf restriction is in effect. This restrictions limits the repos that can
be access controlled by the lines within the included file(s).
Here's how it works. First, a subconf *name* is derived from the filename
being included, which is basically the basename of the file. For example 1
that is "bar". For example 2, assuming foo contains "a.conf" and "b.conf",
the subconf name is "a" while processing "a.conf", and "b" while processing
"b.conf".
A variation of the subconf command allows you to specify the subconf *name*
explicitly, while including files as before:
subconf frob "foo/bar.conf # example 3
subconf frob "foo/*.conf # example 4
In this case the subconf name is "frob" in both cases.
A subconf restricts the repos that can be named in 'repo' lines while the
subconf is in effect. If the subconf name is "foo", the conf lines parsed
while under the subconf restriction can only refer to
* a repo called 'foo'
* a repo group called '@foo'
* the members of the same repo group '@foo'
* match a regex that is a member of the repo group '@foo'
In the last 3 cases, the repo group '@foo' must be defined in the main conf
file (i.e., outside the subconf restriction).
For example, if you have this in the main conf file:
@foo = bar baz frob/..*
subconf "foo.conf"
then foo.conf can only refer to 'foo', '@foo', 'bar', 'baz', or any repo name
matching the pattern `frob/..*`.
## #HOSTNAME HOSTNAME substitution
Wherever gitolite sees the word `%HOSTNAME`, it will replace it with the
HOSTNAME supplied in the rc file, if one was supplied. This is mainly useful
in [mirroring][].

16
doc/mkdoc
View file

@ -13,6 +13,8 @@ use Tsh;
$ENV{TSH_ERREXIT} = 1; $ENV{TSH_ERREXIT} = 1;
try " try "
./fm2mt.pl < g3-master-toc.mm > master-toc.mkd
mkdir ../html; ok mkdir ../html; ok
git status -s -uno; !/./ git status -s -uno; !/./
git log --oneline -1 git log --oneline -1
@ -36,8 +38,8 @@ try "
" or die 2; " or die 2;
sub main { sub main {
chomp(@ARGV = `cat list`) if not @ARGV; chomp(@ARGV = `find . -name "*.mkd" | cut -c3-`) if not @ARGV;
@ARGV = grep { $_ ne 'master-toc.mkd' and /./ } @ARGV; @ARGV = grep { /./ } @ARGV;
my @save = @ARGV; my @save = @ARGV;
my $css = join("", <DATA>); my $css = join("", <DATA>);
@ -68,16 +70,16 @@ sub main {
} }
} }
open($fh, ">", "master-toc.mkd") # open($fh, ">", "master-toc.mk2")
and print $fh $mt # and print $fh $mt
and close $fh; # and close $fh;
# after this, do this for every mkd (including the master-toc.mkd) # after this, do this for every mkd (including the master-toc.mkd)
# cat $css_block > $base.html # cat $css_block > $base.html
# cat $base.mkd $mf | $MKD >> $base.html # cat $base.mkd $mf | $MKD >> $base.html
for my $mkd ("master-toc.mkd", @save) { for my $mkd (@save) {
$mkd =~ /^(?:.*\/)?([^\/]+)\.mkd$/; $mkd =~ /^(?:.*\/)?([^\/]+)\.mkd$/;
my $b = $1; my $b = $1;
@ -88,7 +90,7 @@ sub main {
my $mkt = `cat $mkd`; my $mkt = `cat $mkd`;
$mkt =~ s/^(#+) #(\S+) /$1 <a name="$2"><\/a> /mg; $mkt =~ s/^(#+) #(\S+) /$1 <a name="$2"><\/a> /mg;
open($fh, "|-", "$MKD >> ../html/$b.html") open($fh, "|-", "$MKD >> ../html/$b.html")
and print $fh $mkt, $mf and print $fh $mkt, "\n\n", $mf
and close $fh; and close $fh;
} }
} }

61
doc/non-core.mkd
View file

@ -6,8 +6,8 @@ A list of these commands can be obtained by running `gitolite help` on the
server. A different (and probably much smaller) list can be obtained by a server. A different (and probably much smaller) list can be obtained by a
remote user running `ssh git@host help`. remote user running `ssh git@host help`.
All the commands will respond to `-h`; please report a bug to me if they All the commands that ship with gitolite will respond to `-h`; please report a
don't. bug to me if they don't.
## syntactic sugar ## syntactic sugar
@ -43,7 +43,7 @@ The `POST_GIT` triggers are:
The `POST_COMPILE` triggers are: The `POST_COMPILE` triggers are:
* post-compile/ssh-authkeys -- takes the pubkeys in keydir and populates * post-compile/ssh-authkeys -- takes the pubkeys in keydir and populates
`~/.ssh/authorized_keys` `~/.ssh/authorized_keys`.
* post-compile/update-git-configs -- updates individual 'repo.git/config' * post-compile/update-git-configs -- updates individual 'repo.git/config'
files (using the 'git config ...' command) from settings supplied in the files (using the 'git config ...' command) from settings supplied in the
@ -52,7 +52,7 @@ The `POST_COMPILE` triggers are:
* post-compile/update-git-daemon-access-list -- create/delete * post-compile/update-git-daemon-access-list -- create/delete
'git-daemon-export-ok' files in each repo based on whether the conf says 'git-daemon-export-ok' files in each repo based on whether the conf says
'daemon' can read the repo or not 'daemon' can read the repo or not.
* post-compile/update-gitweb-access-list -- populates the file named in * post-compile/update-gitweb-access-list -- populates the file named in
`GITWEB_PROJECTS_LIST` in the rc file (default: `$HOME/projects.list`) `GITWEB_PROJECTS_LIST` in the rc file (default: `$HOME/projects.list`)
@ -60,7 +60,7 @@ The `POST_COMPILE` triggers are:
more than just "R = gitweb"; any repo that has any config setting with the more than just "R = gitweb"; any repo that has any config setting with the
section name 'gitweb' (like 'gitweb.owner', 'gitweb.description', etc) is section name 'gitweb' (like 'gitweb.owner', 'gitweb.description', etc) is
considered readable by gitweb, so the final list is a union of these two considered readable by gitweb, so the final list is a union of these two
methods methods.
The `POST_CREATE` triggers are: The `POST_CREATE` triggers are:
@ -69,56 +69,11 @@ The `POST_CREATE` triggers are:
## VREFs ## VREFs
You should read about [vref][]s in detail first; this won't make sense VREFs have their [own page][vref].
otherwise. For a brief recap, note that there are 2 kinds of VREFs: those
that require arguments and those that behave just like any other `update`
hook.
COUNT is an example of the former (hence the long-ish description). DUPKEYS
and EMAIL-CHECK are both examples of the latter.
* COUNT
The COUNT VREF is used like this:
- VREF/COUNT/9 = @junior-developers
In response, if anyone in the user list pushes a commit series that
changes more than 9 files, a vref of "VREF/COUNT/9" is returned. Gitolite
uses that as a "ref" to match against all the rules, hit the same rule
that invoked it, and deny the request.
If the user did not push more than 9 files, the VREF code returns nothing,
and nothing happens.
COUNT can take one more argument:
- VREF/COUNT/9/NEWFILES = @junior-developers
This is the same as before, but have to be more than 9 *new* files not
just changed files.
* DUPKEYS -- this checks keydir/ for duplicate keys and aborts the push if
it finds any. You should use this only on the gitolite-admin repo.
repo gitolite-admin
- VREF/DUPKEYS = @all
* EMAIL-CHECK -- read the comments in the code for this one. Like DUPKEYS,
it does not take any arguments.
* FILETYPE -- this is sample code for a very site-specific purpose; you'll
have to read the code
* MERGE-CHECK -- this is sample code to illustrate how one of the gitolite
built-in functions *could* have been handled, although there are some
differences
* partial-copy -- this has its own section later in this page
## special cases ## special cases
### partial-copy ### #partial-copy partial-copy
Git (and therefore gitolite) cannot do selective read control -- allowing Git (and therefore gitolite) cannot do selective read control -- allowing
someone to read branch A but not branch B. It's the entire repo or nothing. someone to read branch A but not branch B. It's the entire repo or nothing.
@ -155,6 +110,6 @@ WARNINGS:
you should delete the partial repo on the server and then run 'gitolite you should delete the partial repo on the server and then run 'gitolite
compile' to let it build again. See t/partial-copy.t for details. compile' to let it build again. See t/partial-copy.t for details.
* not tested with smart http; probabl won't work * not tested with smart http; probably won't work
* also not tested with mirroring, or with wild card repos. * also not tested with mirroring, or with wild card repos.

20
doc/options.mkd Normal file
View file

@ -0,0 +1,20 @@
# gitolite options
Some gitolite features are enabled, or gitolite's behaviour changed, by
setting "options".
Options are set by repo. The syntax is very simple:
option foo.bar = baz
Of course this is useless if some other part of gitolite, or some external
command, is not querying for the option key 'foo.bar'!
Options are therefore documented in the section/page they belong in, not here.
Here are the currently recognised options:
* [deny-rules][] -- ask gitolite to honor deny rules during the pre-git
check also.
* [mirroring][] related options -- tell gitolite who is the master server,
and who are the slaves, for each repo.

45
doc/pw.mkd
View file

@ -1,45 +0,0 @@
# patches welcome :-)
These are places where I could use some help, with hints about how you would
go about it. In addition, any of the items in [dev-status][] are up for
grabs, if you wish to jump in. But let me know before you start, and how you
plan to go about it.
## #pw2 rsync
The crux of the old rsync ADC was an access check to a repo whose name starts
with EXTCMD. g2 would treat repos whose names start with EXTCMD as "don't
create this repo". g3 makes no such distinctions, but you can get the same
effect by using a repo group name that does not exist:
repo @rsync-set1
...rules...
and check that in the script. (It might mean adding one more function to
Gitolite::Easy but that's... easy!)
## #pw1 converting non-openssh pubkeys automatically
Gitolite's [triggers][] has can be used to fix this. Here's pseudo-code:
chdir $(gitolite query-rc -n GL_ADMIN_BASE)/keydir
for each *.pub file in this directory and its subdirectories
detect its format and convert it
# just overwrite it; the original is saved in git anyway
Let's say the program is called "convert-non-openssh-keys". You send it to me
and I add it to src/commands/post-compile/. Then I update the default rc file
to look at least like this instead
POST_COMPILE =>
[
# 'post-compile/convert-non-openssh-keys',
'post-compile/ssh-authkeys',
...
...
],
making sure to place it *before* ssh-authkeys, and anyone who needs it can
just uncomment it.
Done!

53
doc/qi.mkd
View file

@ -1,26 +1,45 @@
# getting started # quick install, setup, and clone
The quickest install, assuming your `$PATH` contains `$HOME/bin`, is: (Please do not ignore the "assumptions" list below).
* get the software On the server:
git clone git://github.com/sitaramc/gitolite # get the software
git clone -b g3 git://github.com/sitaramc/gitolite
# (until this becomes "master") # install it
cd gitolite gitolite/install -ln
git checkout -f g3
* install it
ln -sf $PWD/src/gitolite $HOME/bin
If you don't like that, there are [other install methods][install].
Once the install is done, setup:
# setup the initial repos with your key
gitolite setup -pk your-name.pub gitolite setup -pk your-name.pub
And that's it. On your workstation:
Next steps are usually [adding][add] users and repos and learning about # clone the admin repo so you can start adding stuff
git clone git@host:gitolite-admin.git
## ASSUMPTIONS
* on the server, your `$PATH` contains `$HOME/bin`. If you don't like that,
there are [other install methods][install].
* "your-name.pub" is your public key from your workstation.
* also, this key does not already have shell access to this gitolite
hosting user
* the setup command does not generate any warnings.
* if it does, please see [common errors][ce] and fix things before
continuing, or read the more complete [setup][] page.
## Notes
Note that the clone path is NOT "repositories/gitolite-admin.git". If you
clone with a path that includes "repositories/", the clone should fail. If
the clone *does* succeed, a subsequent push should fail :-) See
[this][ybpfail] for some details. If that doesn't make enough sense read all
of [ssh][].
## next steps
Next steps are usually adding [users][] and [repos][] and learning about
[access control][conf]. [access control][conf].

41
doc/rare.mkd Normal file
View file

@ -0,0 +1,41 @@
# rare or one-time activities
## #existing moving existing repos into gitolite
* move the repos to `$HOME/repositories`. Make sure they are all *bare*
repos, and the directory names end in ".git".
* [add them][repos] to conf/gitolite.conf in your clone of the admin repo,
then commit and push the change.
If the repos are already covered by some [wild][] pattern, this is
optional.
* run `gitolite setup` to fix up the hooks on all repos, just in case.
## #moving moving servers
This is adapted from the "migrating" section of the [install][] page; if
you're actually *migrating* from g2 please go there!
Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
any repository except the gitolite-admin repo. The only thing it will
normally touch is the `update` hook. So one fool-proof way of "moving"
servers is this (untested but should work; feedback appreciated):
1. Install gitolite on the new server, using the same key for the admin as
for the old server.
2. Copy the [rc][] file from the old server, overwriting this one.
3. [Disable][writable] the old server so people won't push to it.
4. Copy all the repos over from the old server, including gitolite-admin.
Make sure the files end up with right ownership and permissions; if not,
chown/chmod them.
5. On a clone of the old gitolite-admin, add a new remote (or change an
existing one) to point to the new server. Then `git push -f` to this
remote.
6. On the server, run `gitolite setup`.

82
doc/rc.mkd
View file

@ -1,20 +1,82 @@
# the "rc" file ($HOME/.gitolite.rc) # the "rc" file (`$HOME/.gitolite.rc`)
The rc file for g3 is quite different from that of g2. It has been designed **NOTE**: if you're migrating from g2, there are some settings that MUST be
to be (a) the only thing unique to your site, for most installations and (b) dealt with **before** running `gitolite setup`; please read the [g2
easy to extend when new needs show up, without having to touch core gitolite. migration][g2migr] page and linked pages, and especially the one on
[presetting the rc file][rc-preset].
g2 had a nasty rc file where every variable had to be declared. As a result, ----
ADCs that needed their own settings could not use it.
Now it's a perl hash, and you can add any keys you want. The rc file for g3 is *quite* different from that of g2.
Please look at the rc file that gets installed when you setup gitolite. As As before, it is designed to be the only thing unique to your site for most
you can see there are 3 types of variables in it: setups. What is new is that it is easy to extend it when new needs come up,
without having to touch core gitolite.
The rc file is perl code, but you do NOT need to know perl to edit it. Just
mind the commas, use single quotes unless you know what you're doing, and make
sure the brackets and braces stay matched up!
Please look at the `~/.gitolite.rc` file that gets installed when you setup
gitolite. As you can see there are 3 types of variables in it:
* simple variables (like UMASK) * simple variables (like UMASK)
* lists (like `POST_COMPILE`, `POST_CREATE`) * lists (like `POST_COMPILE`, `POST_CREATE`)
* hashes (like `ROLES`, `COMMANDS`) * hashes (like `ROLES`, `COMMANDS`)
While some of the variables are documented in this file, many of them are not.
Their purposes are to be found in each of their individual documentation files Their purposes are to be found in each of their individual documentation files
around; start with [customising gitolite][cust]. around; start with [customising gitolite][cust]. If a setting is used by an
external command then running that command with '-h' may give you additional
information.
## specific variables
* `$UMASK`, octal, default `0077`
The default UMASK that gitolite uses makes all the repos and their
contents have `rwx------` permissions. People who want to run gitweb
realise that this will not do.
The correct way to deal with this is to give this variable a value like
`0027` (note the syntax: the leading 0 is required), and then make the
user running the webserver (apache, www-data, whatever) a member of the
'git' group.
If you've already installed gitolite then existing files will have to be
fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
This is because umask only affects permissions on newly created files, not
existing ones.
* `$GIT_CONFIG_KEYS`, string, default empty
This setting allows the repo admin to define acceptable gitconfig keys.
Gitolite allows you to set git config values using the "config" keyword;
see [here][git-config] 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
arbitrary repo config options *may* be a security risk -- some config
settings allow executing arbitrary commands!
You have 3 choices. By default `$GIT_CONFIG_KEYS` is left empty, which
completely disables this feature (meaning you cannot set git configs via
the repo config).
The second choice is to give it a space separated list of settings you
consider safe. (These are actually treated as a set of [regular
expression][regex] patterns, and any one of them must match).
For example:
$GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
Each pattern should match the *whole* key (in other words, there
is an implicit `^` at the start of each pattern, and a `$` at the
end).
The third choice (which you may have guessed already if you're familiar
with regular expressions) is to allow anything and everything:
`$GIT_CONFIG_KEYS = '.*';`

16
doc/refex.mkd
View file

@ -3,11 +3,15 @@
A refex is a word I made up to mean "a regex that matches a ref". If you know A refex is a word I made up to mean "a regex that matches a ref". If you know
[regular expressions][regex] you're halfway there. [regular expressions][regex] you're halfway there.
The only extra info you need is: In addition:
* for convenience, a refex not starting with `refs/` is assumed to start * if no refex is supplied, it defaults to `refs/.*`, for example in a rule
with `refs/heads/`. This means normal branches can be referred to like like this:
this:
RW = alice
* a refex not starting with `refs/` is assumed to start with `refs/heads/`.
This means normal branches can be conveniently written like this:
RW master = alice RW master = alice
# becomes 'refs/heads/master' internally # becomes 'refs/heads/master' internally
@ -18,13 +22,13 @@ The only extra info you need is:
* a refex is implicitly anchored at the start, but not at the end. In * a refex is implicitly anchored at the start, but not at the end. In
regular expression lingo, a `^` is assumed at the start (but no `$` at the regular expression lingo, a `^` is assumed at the start (but no `$` at the
end is assumed). So a refex of `master` will allow all these: end is assumed). So a refex of `master` will match all these:
refs/heads/master refs/heads/master
refs/heads/master1 refs/heads/master1
refs/heads/master2 refs/heads/master2
refs/heads/master/full refs/heads/master/full
If you want to restrict to just the one specific ref, use If you want to restrict the match to just the one specific ref, use
RW master$ = alice RW master$ = alice

23
doc/repo.mkd
View file

@ -1,23 +0,0 @@
## #repo repo definitions
Example:
repo gitolite tsh gitpod
RW+ = sitaram
RW dev = alice bob
R = @all
The "repo" line can have any number of repo names or repo group names in it.
However, it can only be one line; this will not work
repo foo
repo bar # WRONG; 'foo' is now forgotten
RW = alice
If you have too many, use a group name:
@myrepos = foo
@myrepos = bar
repo @myrepos
RW = alice

53
doc/repos.mkd Normal file
View file

@ -0,0 +1,53 @@
# adding and removing repos
> ----
> *WARNING: Do NOT add repos directly on the server. Clone the
> 'gitolite-admin' repo to your workstation, make changes to it, then add,
> commit, and push. When the push hits the server, the server "acts" upon
> your changes.*
> ----
Just as for [users][], all operations are in a clone of the gitolite-admin
repo.
To **add** a new repo, edit `conf/gitolite.conf` and add it, along with at
least one user with some permissions. Or add it to an existing repo line:
repo gitolite tsh gitpod
RW+ = sitaram
RW dev = alice bob
R = @all
The "repo" line can have any number of repo names or repo group names in it.
However, it can only be one line; this will not work
repo foo
repo bar # WRONG; 'foo' is now forgotten
RW = alice
If you have too many, use a group name:
@myrepos = foo
@myrepos = bar
repo @myrepos
RW = alice
Finally, you add, commit, and push this change. Gitolite will create a bare,
empty, repo on the server that is ready to be cloned.
**Removing** a repo is not so straightforward. You certainly must remove the
appropriate lines from the `conf/gitolite.conf` file, but gitolite will not
automatically delete the repo from the server. You have to log on to the
server and do the dirty deed yourself :-)
It is best to make the change in the conf file, push it, and *then* go to the
server and do what you need to.
**Renaming** a repo is also not automatic. Here's what you do (and the order
is important):
* go to the server and rename the repo at the Unix command line
* change the name in the conf/gitolite.conf file and add/commit/push.

81
doc/rules.mkd
View file

@ -15,7 +15,28 @@ We will use this as a running example:
RW temp/ = @staff # line 4 RW temp/ = @staff # line 4
R = ashok # line 5 R = ashok # line 5
### when does gitolite check access ### what does a rule look like?
A rule line has the structure
<permission> <zero or more refexes> = <one or more users/user groups>
The most common permissions used are:
* R, for read only
* RW, for push existing ref or create new ref
* RW+, for "push -f" or ref deletion allowed (i.e., destroy
information)
* `-` (the minus sign), to **deny** access.
There are also other, less commonly used, [types of permissions][write-types].
A refex is an expression that matches the ref (i.e., branch or tag) being
pushed. See [this][refex] for more info.
### when are the rules checked?
There are 2 places where access rules are checked.
The "pre-git" check is before git is invoked. Gitolite knows the repo name, The "pre-git" check is before git is invoked. Gitolite knows the repo name,
user name, and attempted access (R or W), but no ref name. user name, and attempted access (R or W), but no ref name.
@ -23,7 +44,7 @@ user name, and attempted access (R or W), but no ref name.
The "update" check is only for write operations, and it is just before git The "update" check is only for write operations, and it is just before git
updates a ref. This time gitolite knows the refname also. updates a ref. This time gitolite knows the refname also.
### how is a particular rule line matched ### how are the rules matched?
For the **pre-git check**, any permission that contains "R" matches a read For the **pre-git check**, any permission that contains "R" matches a read
operation, and any permission that contains "W" matches a write operation. operation, and any permission that contains "W" matches a write operation.
@ -39,8 +60,8 @@ For the **update check**, git gives us all the information we need. Then:
* all the rules for a repo are [accumulated][rule-accum] * all the rules for a repo are [accumulated][rule-accum]
* then the rules pertaining to this repo *and* this user (or to a group to * the rules pertaining to this repo *and* this user (or to a group to which
which they belong, respectively) are kept; the rest are ignored they belong, respectively) are kept; the rest are ignored
* these rules are examined *in the sequence they appeared in the conf file*. * these rules are examined *in the sequence they appeared in the conf file*.
For each rule: For each rule:
@ -73,10 +94,58 @@ deny rules for pre-git, but having got past it, he can't actually do anything.
That's by design, and as I said if you don't like it you can ask gitolite to That's by design, and as I said if you don't like it you can ask gitolite to
[deny at pre-git][deny-rules]. [deny at pre-git][deny-rules].
### summary of permissions ### #perms summary of permissions
The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`. This expands The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`. This expands
to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
`RW+CD`, all but the first one optionally followed by an `M`. And by now you `RW+CD`, all but the first two optionally followed by an `M`. And by now you
know what they all mean. know what they all mean.
## additional topics
### #rule-accum rule accumulation
Gitolite was meant to collect rules from multiple places and apply them all.
For example, this:
repo foo
RW = u1
@gr1 = foo bar
repo @gr1
RW = u2
R = u3
repo @all
R = gitweb
is effectively the same as this, for repo foo:
repo foo
RW = u1
RW = u2
R = u3
R = gitweb
This extends to patterns also, but I'll leave an example for later.
### #deny-rules applying deny rules during the pre-git check
The access rules section above describes the problem in one scenario. Here's
another. Let's say you have this at the end of your gitolite.conf file:
repo @all
R = gitweb daemon
but you don't want the gitolite-admin repo showing up on gitweb. How do you
do that? Here's how:
repo gitolite-admin
- = gitweb daemon
option deny-rules = 1
repo @all
R = gitweb daemon
Note that the order matters; the `-` rule must come *before* the `R` rule.

41
doc/setup.mkd Normal file
View file

@ -0,0 +1,41 @@
# setting up gitolite
Installing the software gets you ready to use it, but the first "use" of it is
always the "setup" command.
The first time you run it, you need to have a public key file ready. If the
main gitolite admin's username is "alice", this file should be named
"alice.pub". Then run
gitolite setup -pk alice.pub
If that command completes without any warnings, you should be done. If it had
a warning, you probably supplied a key which already has shell access to the
server. That won't work.
> ----
> Normally, gitolite is hosted on a user that no one accesses directly --
> you log on to the server using some other userid, and then `su - git`. In
> this scenario, there *is* no key being used for shell access, so there is
> no conflict.
> An alternative method is to use two different keys, and a [host
> alias][ssh-ha] to distinguish the two.
> [common errors][ce] has some links to background information on this
> issue.
> ----
The 'setup' command has other uses, so you will be running it at other times
after the install as well:
* to setup the update hook when you move [existing][] repos to gitolite.
This also applies if someone has been fiddling with the hooks on some
repos and you want to put them all right quickly.
* to replace a [lost admin key][lost-key].
When in doubt, run 'gitolite setup' anyway; it doesn't do any harm, though it
may take a minute or so if you have more than a few thousand repos!

42
doc/special.mkd Normal file
View file

@ -0,0 +1,42 @@
# special features and setups
## #writable disabling pushes to take backups
The `writable` command allows you to disable pushes to all repos or just the
named repo, in order to do file-system level things to the repo directory that
require it not to change, like using normal backup software.
Run `gitolite writable -h` for more info.
## #pers "personal" branches
"personal" branches are great for environments where developers need to share
work but can't directly pull from each other (usually due to either a
networking or authentication related reason, both common in corporate setups).
Personal branches exist **in a namespace** of their own. The syntax is
RW+ personal/USER/ = @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`.
(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).
Compared to using arbitrary branch names on the same server, this
* reduces namespace pollution by corralling all these ad hoc branches into
the "personal/" namespace.
* reduces branch name collision by giving each developer her own
sub-hierarchy within that.
* removes the need to think about access control, because a user can push
only to his own sub-hierarchy.
## delegating access control responsibilities
See [this][deleg].

46
doc/syntax.mkd Normal file
View file

@ -0,0 +1,46 @@
# #syntax basic syntax
In general, everything is **space separated**; there are no commas,
semicolons, etc., in the syntax.
**Comments** are in the usual shell-ish style.
**User names** and **repo names** are as simple as possible; they must start
with an alphanumeric, but after that they can also contain `.`, `_`, or `-`.
Usernames can optionally be followed by an `@` and a domainname containing at
least one `.` (this allows you to use an email address as someone's username).
Reponames can contain `/` characters (this allows you to put your repos in a
tree-structure for convenience)
There are no continuation lines by default. You do not need them; the section
on "groups" will tell you how you can break up large lists of names in a group
definition into multiple lines.
<font color="gray">If you *must* have them, you can optionally enable them;
see the syntactic [sugar][] section.</font>
## #include include files
Gitolite allows you to break up the configuration into multiple files and
include them in the main file for convenience.
include "foo.conf"
will include the contents of the file "foo.conf".
Details:
* You can also use a glob (`include "*.conf"`), or put your include files
into subdirectories of "conf" (`include "foo/bar.conf"`), or both
(`include "repos/*.conf"`).
* Included files are always searched from the gitolite-admin repo's "conf/"
directory, unless you supplied an absolute path. (Note: in the interests
of cloning the admin-repo sanely you should avoid absolute paths!)
* If you ended up recursing, 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>

10
doc/testing.mkd
View file

@ -1,7 +1,9 @@
# testing gitolite # testing gitolite
Here's how to *run* the tests. **WARNING: they will clobber lots of things in Here's how to *run* the tests.
your `$HOME`, so be sure to use a throwaway userid**.
<font color="red">**WARNING: they will clobber lots of things in your `$HOME`,
so be sure to use a throwaway userid**.</font>
git clone git://github.com/sitaramc/gitolite git clone git://github.com/sitaramc/gitolite
cd gitolite cd gitolite
@ -21,7 +23,3 @@ would otherwise take.
If you think that defeats the purpose of the testing, you haven't read If you think that defeats the purpose of the testing, you haven't read
[this][auth] yet. [this][auth] yet.
There are 2 specific tests that deal with ssh though, which are run only on
request, as you can see above, because they clobber your `~/.ssh`. You have
been warned.

9
doc/triggers.mkd
View file

@ -50,15 +50,16 @@ Triggers receive the following arguments:
command in the PRE_GIT trigger sequence), command in the PRE_GIT trigger sequence),
2. the name of the trigger as a string (example, `"POST_COMPILE"`), so you 2. the name of the trigger as a string (example, `"POST_COMPILE"`), so you
can call the same program from multiple triggers and know where it was can call the same program from multiple triggers and it can know where it
called from, was called from,
3. followed by zero or more arguments specific to the trigger, as given in 3. followed by zero or more arguments specific to the trigger, as given in
the next section. the next section.
## trigger-specific details ## trigger-specific arguments and other details
Here's a brief "when" and "with what arguments" for each trigger. Here are the **rest of** the arguments for each trigger, plus a brief
description of when the trigger runs:
* `ACCESS_1` runs after the first access check. Arguments: * `ACCESS_1` runs after the first access check. Arguments:
* repo * repo

95
doc/user.mkd Normal file
View file

@ -0,0 +1,95 @@
# 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" ;-)
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.
## 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.
Your actual access is either a git command (like `git clone
git@server:reponame`, and we won't be discussing these any more in this
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!
## #info the info command
The only command that is *always* available to every user is the `info`
command (run `ssh git@host info -h` for help), which tells you what version of
gitolite and git are on the 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.
## 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. Try the [`info` command][info] and see if it shows any lines
that look like regex patterns, (with a "C" permission).
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 gitolite.
## other commands
### #perms set/get additional permissions for repos you created
The gitolite config may have several permissions lines for your repo, like so:
repo pub/CREATOR/..*
RW+ = CREATOR
RW = user1 user2
R = user3
If that's all it had, you really can't do much. Any changes to access must be
done by the administrator. (Note that "CREATOR" is a reserved word that gets
expanded to your userid in some way, so the admin can literally add just the
first two lines, and *every* authenticated user now has his own personal repo
namespace, starting with `pub/<username>/`).
To give some flexibility to users, the admin could add rules like this:
RW = WRITERS
R = READERS
(he could also add other roles but then he needs to read the documentation).
Once he does this, you can then use the `perms` command (run `ssh git@host
perms -h` for help) to set permissions for other users by specifying which
users are in the list of "READERS", and which in "WRITERS".
If you think of READERS and WRITERS as "roles", it will help. You can't
change what access a role has, but you *can* say which users have that role.
**Note**: there isn't a way for you to see the actual rule set unless you're
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.
### #desc adding a description to repos you created
The `desc` command is extremely simple. Run `ssh git@host desc -h` for help.
## "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
done by pushing something to a repo).
To enable this, gitolite allows the admin to setup scripts in a special
directory that users can then run. Gitolite comes with a set of working
scripts that your admin may install, or may use as a starting point for his
own, if he chooses.
Think of these commands as equivalent to those in `COMMAND_DIR` in `man
git-shell`.
You can get a list of available commands by running `ssh git@host help`.

117
doc/users.mkd
View file

@ -1,96 +1,67 @@
# what users (not admins) need to know about gitolite # adding and removing users
...written for the one guy in the world no one will think of as "just a normal Strictly speaking, gitolite doesn't know where users come from. If that
user" ;-) surprises you, read [this][auth]. However, gitolite does help with ssh-based
authentication, so here's some info on adding and removing users.
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.
## accessing gitolite > *WARNING: Do NOT add users directly on the server. Clone the
> 'gitolite-admin' repo to your workstation, make changes to it, then add,
> commit, and push. When the push hits the server, the server "acts" upon
> your changes.*
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.
Your actual access is either a git command (like `git clone All operations are in a clone of the gitolite-admin repo.
git@server:reponame`, and we won't be discussing these any more in this
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 To **add** a user, say Alice, obtain her public key (typically
gitolite is to prevent that! `$HOME/.ssh/id_rsa.pub` on her workstation), copy it to `keydir` with the user
name as the basename (e.g., 'alice.pub' for user alice), then `git add
keydir/alice.pub`. (All keys files must have names ending in ".pub", and must
be in openssh's default format).
## #info the info command To **remove** a user, `git rm keydir/alice.pub`.
The only command that is *always* available to every user is the `info` In both cases, you must commit and push. On receiving the push, gitolite will
command (run `ssh git@host info -h` for help), which tells you what version of carry out the changes specified.
gitolite and git are on the 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.
## digression: two kinds of repos The user name is simply the base name of the public key file name. So
'alice.pub', 'foo/alice.pub' and 'bar/alice.pub', all resolve to user "alice".
Gitolite has two kinds of repos. Normal repos are specified by their full ## #multi-key multiple keys per user
names in the config file. "Wildcard" repos are specified by a regex in the
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").
If you see any, it means you are allowed to create brand new repos whose names The simplest and most understandable is to put their keys in different
fit that pattern. When you create such a repo, your "ownership" of it (as far subdirectories, (alice,pub, home/alice.pub, laptop/alice.pub, etc).
as gitolite is concerned) is *automatically* recorded by gitolite.
## other commands ### old style multi-keys
### #perms set/get additional permissions for repos you created There is another way that involves creating key files like `alice@home.pub`
and `alice@laptop.pub`, but there is a complication because gitolite also
allows *full email addresses* as user names. (I.e., `sitaramc@gmail.com.pub`
denotes the user called `sitaramc@gmail.com`).
The gitolite config may have several permissions lines for your repo, like so: This older method of enabling multi-keys was developed to deal with that. It
will continue to work and be supported in *code*, simply because I prefer it.
But I will not accept questions or doc patches for it, because it seems it is
too difficult to understand for a lot of people. This table of sample pubkey
filenames and the corresponding derived usernames is all you get:
repo pub/CREATOR/..* * plain username, no multikey
RW+ = CREATOR
RW = user1 user2
R = user3
If that's all it had, you really can't do much. Any changes to access must be sitaramc.pub sitaramc
done by the administrator. (Note that "CREATOR" is a reserved word that gets
expanded to your userid in some way, so the admin can literally add just the
first two lines, and *every* authenticated user now has his own personal repo
namespace, starting with `pub/<username>/`).
To give some flexibility to users, the admin could add rules like this: * plain username, with multikeys
RW = WRITERS sitaramc@laptop.pub sitaramc
R = READERS sitaramc@desktop.pub sitaramc
(he could also add other roles but then he needs to read the documentation). * email address as username, no multikey
Once he does this, you can then use the `perms` command (run `ssh git@host sitaramc@gmail.com.pub sitaramc@gmail.com
perms -h` for help) to set permissions for other users by specifying which
users are in the list of "READERS", and which in "WRITERS".
If you think of READERS and WRITERS as "roles", it will help. You can't * email address as username, with multikeys
change what access a role has, but you *can* say which users have that role.
**Note**: there isn't a way for you to see the actual rule set unless you're sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
given read access to the special 'gitolite-admin' repo. Sorry. The idea is sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
that your admin will tell you what "roles" he added into rules for your repos,
and what permissions those roles have.
### #desc adding a description to repos you created
The `desc` command is extremely simple. Run `ssh git@host desc -h` for help.
## "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
done by pushing something to a repo).
To enable this, gitolite allows the admin to setup scripts in a special
directory that users can then run. Gitolite comes with a set of working
scripts that your admin may install, or may use as a starting point for his
own, if he chooses.
Think of these commands as equivalent to those in `COMMAND_DIR` in `man
git-shell`.
You can get a list of available commands by running `ssh git@host help`.

83
doc/vref.mkd
View file

@ -1,5 +1,11 @@
# virtual refs # virtual refs
**IMPORTANT**: fallthru is success in VREFs, unlike the normal refs. That
won't make sense until you read further, but I had to put it up here for folks
who stop reading halfway!
----
Here's an example to start you off. Here's an example to start you off.
repo r1 repo r1
@ -39,7 +45,7 @@ is therefore a *virtual* ref. This could be a property that git knows about,
like in the example above, or comes from outside git like, say, the current like in the example above, or comes from outside git like, say, the current
time; see examples section later for some ideas. time; see examples section later for some ideas.
## fallthru is success here ## #vref-fallthru fallthru is success here
Notice that you didn't need to add an `RW+ VREF/...` rule for user `lead_dev` Notice that you didn't need to add an `RW+ VREF/...` rule for user `lead_dev`
in our example. This section explains why. in our example. This section explains why.
@ -53,7 +59,7 @@ ref involves calling an external program, many of these calls may be wasted.
There's another advantage to doing it this way: a VREF can choose to simply There's another advantage to doing it this way: a VREF can choose to simply
die if things look bad, and it will have the same effect, assuming you used die if things look bad, and it will have the same effect, assuming you used
the VREF only in [deny][] rules. the VREF only in "deny" rules.
This in turn means any existing update hook can be used as a VREF *as-is*, as This in turn means any existing update hook can be used as a VREF *as-is*, as
long as it (a) prints nothing on success and (b) dies on failure. See the long as it (a) prints nothing on success and (b) dies on failure. See the
@ -169,26 +175,65 @@ first rule, it might pass back (to gitolite) a virtual ref saying
## VREFs shipped with gitolite ## VREFs shipped with gitolite
### #NAME restricting pushes by dir/file name
The "NAME" VREF allows you to restrict pushes by the names of dirs and files
changed.
Here's an example. Say you don't want junior developers pushing changes to
the Makefile, because it's quite complex:
repo foo
RW+ = @senior_devs
RW = @junior_devs
- VREF/NAME/Makefile = @junior_devs
When a senior dev pushes, the VREF is not invoked at all. But when a junior
dev pushes, the VREF is invoked, and it returns a list of files changed **as
refs**, looking like this:
VREF/NAME/file-1
VREF/NAME/dir-2/file-3
...etc...
Each of these refs is matched against the access rules. If one of them
happens to be the Makefile, then the ref returned (VREF/NAME/Makefile) will
match the deny rule and kill the push.
Another way to use this is when you know what is allowed instead of what is
not allowed. Let's say the QA person is only allowed to touch a file called
CHANGELOG and any files in a directory called ReleaseNotes:
repo foo
RW+ = @senior_devs
RW = @junior_devs
RW+ = QA-guy
RW+ VREF/NAME/CHANGELOG = QA-guy
RW+ VREF/NAME/ReleaseNotes/ = QA-guy
- VREF/NAME/ = QA-guy
### number of new files ### number of new files
If a dev pushes more than 2 *new* files, the top commit needs to have a The COUNT VREF is used like this:
signed-off by line in its commit message. For example if he has 4 new files
this text should be:
4 new files signed-off by: <top commit author's email> - VREF/COUNT/9 = @junior-developers
The config entry for this is below (`NO_SIGNOFF` applies only to, and thus In response, if anyone in the user list pushes a commit series that
implies, `NEWFILES`): changes more than 9 files, a vref of "VREF/COUNT/9" is returned. Gitolite
uses that as a "ref" to match against all the rules, hits the same rule
that invoked it, and denies the request.
RW+ VREF/COUNT/2/NO_SIGNOFF = sitaram If the user did not push more than 9 files, the VREF code returns nothing,
- VREF/COUNT/2/NO_SIGNOFF = @all and nothing happens.
Notice how the refex in both cases is *exactly* the same. If you make it COUNT can take one more argument:
different (even change the number on my access line), things won't work.
Junior devs can't push more than 10 new files, even with a signed-off by line: - VREF/COUNT/9/NEWFILES = @junior-developers
- VREF/COUNT/10/NEWFILES = @junior_devs This is the same as before, but have to be more than 9 *new* files not
just changed files.
### advanced filetype detection ### advanced filetype detection
@ -220,6 +265,9 @@ have to change one subroutine in that script if you want to use it)
### catching duplicate pubkeys ### catching duplicate pubkeys
This checks keydir/ for duplicate keys and aborts the push if it finds any.
You should use this only on the gitolite-admin repo.
We covered this as a teaser example at the start. We covered this as a teaser example at the start.
## other ideas -- code welcome! ## other ideas -- code welcome!
@ -231,9 +279,10 @@ something like this (untested)
[ -z "$(git rev-list --first-parent --no-merges $2..$3)" ] [ -z "$(git rev-list --first-parent --no-merges $2..$3)" ]
This can be implemented using `src/VREF/MERGE-CHECK` as a model. This can be implemented using `src/VREF/MERGE-CHECK` as a model. That script
That script does what the 'in core' feature called [merge check][mergecheck] does what the 'M' qualifier does in access rules (see last part of
does, although the syntax to be used in conf/gitolite will be quite different. [this][write-types]), although the syntax to be used in conf/gitolite will be
quite different.
### other ideas for VREFs ### other ideas for VREFs

43
doc/why.mkd
View file

@ -1,4 +1,4 @@
# Why is gitolite needed? # why might you need gitolite
Gitolite is separate from git, and needs to be installed and configured. So... Gitolite is separate from git, and needs to be installed and configured. So...
why do we bother? why do we bother?
@ -14,33 +14,34 @@ allow/disallow users access to repos.
But there are several disadvantages here: But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a * Every user needs a userid and password on the server. This is usually a
killer, especially in tightly controlled environments killer, especially in tightly controlled environments.
* adding/removing access rights involves complex `usermod -G ...` mumblings * Adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with which most admins would rather not deal with.
* *viewing* (aka auditing) the current set of permissions requires running * *Viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships, multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually users and their group memberships, and then correlating all these
* auditing historical permissions or permission changes is pretty much manually.
impossible without extraneous tools * Auditing historical permissions or permission changes is pretty much
* errors or omissions in setting the permissions exactly can cause problems impossible without extraneous tools.
of either kind: false accepts or false rejects * Errors or omissions in setting the permissions exactly can cause problems
* without going into ACLs it is not possible to give some people read-only 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 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 world-readable). Group access just doesn't have enough granularity.
* it is absolutely impossible to restrict pushing by branch name or tag * It is absolutely impossible to restrict pushing by branch name or tag
name. name.
Gitolite does away with all this: Gitolite does away with all this:
* it uses ssh magic to remove the need to give actual unix userids to * It uses ssh magic to remove the need to give actual unix userids to
developers developers.
* it uses a simple but powerful config file format to specify access rights * It uses a simple but powerful config file format to specify access rights.
* access control changes are affected by modifying this file, adding or * Access control changes are affected by modifying this file, adding or
removing user's public keys, and "compiling" the configuration removing user's public keys, and "compiling" the configuration.
* this also makes auditing trivial -- all the data is in one place, and * 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. changes to the configuration are also logged, so you can audit them.
* finally, the config file allows distinguishing between read-only and * Finally, the config file allows distinguishing between read-only and
read-write access, not only at the repository level, but at the branch read-write access, not only at the repository level, but at the branch
level within repositories. level within repositories.

148
doc/wild.mkd Normal file
View file

@ -0,0 +1,148 @@
# "wild" repos (user created repos)
## 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
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.
See the section on "repo patterns" later for additional information on what
counts as a "wild" repo pattern and how it is matched.
## (admin) declaring wild repos in the conf file
Here's an example:
@prof = u1
@TAs = u2 u3
@students = u4 u5 u6
repo assignments/CREATOR/a[0-9][0-9]
C = @students
RW+ = CREATOR
RW = WRITERS @TAs
R = READERS @prof
Note the "C" permission. This is a standalone "C", which gives the named
users the right to *create a repo*. <font color="gray">This is not to be
confused with the "RWC" or its variants described elsewhere, which are about
*branches*, not *repos*.</font>
## #create (user) creating a specific repo
For now, ignore the special usernames READERS and WRITERS, and just create a
new repo, as user "u4" (a student):
$ git clone git@server:assignments/u4/a12
Initialized empty Git repository in /home/sitaram/a12/.git/
Initialized empty Git repository in /home/git/repositories/assignments/u4/a12.git/
warning: You appear to have cloned an empty repository.
Notice the *two* empty repo inits, and the order in which they occur ;-)
## a slightly different example
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.
repo assignments/a[0-9][0-9]
C = @students
RW+ = CREATOR
RW = WRITERS @TAs
R = READERS @prof
We haven't changed anything except the repo name pattern. This means that the
first student that creates, say, `assignments/a12` becomes the owner.
Mistakes (such as claiming a12 instead of a13) need to be rectified by an
admin logging on to the back end, though it's not too difficult.
You could also repace the C line like this:
C = @TAs
and have a TA create the repos in advance.
## repo patterns
### pattern versus normal repo
Due to projects like `gtk+`, the `+` character is now considered a valid
character for an *ordinary* repo. Therefore, a pattern like `foo/.+` does not
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].*`.
### line-anchored regexes
A regex like
repo assignments/S[0-9]+/A[0-9]+
would match `assignments/S02/A37`. It will not match `assignments/S02/ABC`,
or `assignments/S02/a37`, obviously.
But you may be surprised to find that it does not match even
`assignments/S02/A37/B99`. This is because internally, gitolite
*line-anchors* the given regex; so that regex actually becomes
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters.
Side-note: contrast with refexes
> Just for interest, note that this is in contrast to the refexes for the >
> normal "branch" permissions, as described in `doc/gitolite.conf.mkd` and
> elsewhere. These "refexes" are only anchored at the start; a pattern like
> `refs/heads/master` actually can match `refs/heads/master01/bar` as well,
> even 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.
## roles
The tokens READERS and WRITERS are called "role" names. The access rules that
the admin specifies say what permissions these roles have, but they don't say
what users are in these roles.
That needs to be done by the creator of the repo, using the `perms` command.
You can run `ssh git@host perms -h` for detailed help, but in brief, that
command lets you give and take away roles to users.
## adding other roles
If you want to have more than just the 2 default roles, say something like:
repo foo/..*
C = u1
RW refs/tags/ = TESTERS
- refs/tags/ = @all
RW+ = WRITERS
RW = INTERNS
R = READERS
RW+D = MANAGERS
You can add the new names to the ROLES hash in the [rc][] file. Be sure to
run the 2 commands mentioned there after you have added the roles.
file. The rc file documentation (`doc/gitolite.rc.mkd`) explains how.
#### #rolenamewarn **IMPORTANT WARNING ABOUT THIS FEATURE**
Please make sure that none of the role names conflict with any of the user
names or group names in the system. For example, if you have a user called
"foo" or a group called "@foo", make sure you do not include "foo" as a valid
role in the ROLES hash.
You can keep things sane by using UPPERCASE names for roles, while keeping all
your user and group names lowercase; then you don't have to worry about this
problem.
## listing wild repos
In order to see what repositories were created from a wildcard, use the 'info'
command. Try `ssh git@host info -h` to get help on the info command.
## deleting a wild repo
TBD