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

(doc) general cleanup of docs

Browse source
This commit is contained in:
Sitaram Chamarty 2012-04-17 06:43:13 +05:30
parent 95e6c2ae8b
commit 2c8e0dfd2f
33 changed files with 405 additions and 329 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
README.mkd
View file

@ -12,16 +12,15 @@ If you're reading this on the main gitolite page on github, several
branch, and is now the actively maintained and supported software. Do NOT
try to merge this with your old "master" branch!
2. Versions v2.x is on branch "g2". It will be supported for security issues
and serious bugs in core functionality, but not for anything less
2. Versions v2.x are on branch "g2". It will be supported for security
issues and serious bugs in core functionality, but not for anything less
critical. Versions v1.x are completely unsupported now.
If you're an existing (v1.x, v2.x) gitolite user please spend some time with
the documentation for the new version before upgrading. The [main page][h-mp]
leads to quick install as well as several other useful starting points. The
[table of contents][h-mt] is a much more meaningfully ordered/structured list
of links (instead of putting them in alphabetical order of the filename, like
in g2!)
leads to several useful starting points. The [table of contents][h-mt] is a
much more meaningfully ordered/structured list of links (instead of putting
them in alphabetical order of the filename, like in g2!)
[h-mp]: http://sitaramc.github.com/gitolite/
[h-mt]: http://sitaramc.github.com/gitolite/master-toc.html

24
doc/admin.mkd
View file

@ -2,11 +2,11 @@
## #server server-side administration
The following activities require command line access to the server
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][] repos into gitolite control
* Changing anything in the [rc][] file.
* Installing custom [hooks][], whether to all repos or just some repos.
* Moving [existing][] repos into gitolite control.
Please read the [WARNINGS][] page first.
@ -32,11 +32,11 @@ Here is an example of a simple conf/gitolite.conf file.
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
* 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.

8
doc/cust.mkd
View file

@ -17,12 +17,12 @@ even mirroring is not in core now!)
There are 5 basic types of non-core programs.
* *commands* can be run from the shell command line. Among those, the ones
* *Commands* can be run from the shell command line. Among those, the ones
listed in the COMMANDS hash of the rc file can also be run remotely.
* *hooks* are standard git hooks; see below.
* *sugar scripts* change the conf language for your convenience. The word
* *Hooks* are standard git hooks; see below.
* *Sugar scripts* change the conf language for your convenience. The word
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.
* **VREFs** are extensions to the access control check part of gitolite.

26
doc/deleg.mkd
View file

@ -38,21 +38,22 @@ And that's it.
Subconf is exactly like the include command in syntax:
subconf "foo/bar.conf"
subconf "foo.conf"
but while reading the included file, it sets a "subconf name" of "foo".
but while reading the included file (as well as anything included from it),
gitolite sets the "subconf name" to "foo".
When a subconf name is in effect, there are some restrictions on what repos
can be managed.
A "subconf" imposes 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:
For example, while the subconf name is "foo", as in the above example,
gitolite will only process "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
* A repo called "foo".
* A group called "@foo", as long as the group is defined in the main conf
file (i.e., *outside* "foo.conf").
* 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
@ -61,6 +62,9 @@ Here's an example. If the main conf file contains
then the subconf can only accept repo statements that refer to 'foo', '@foo',
'aa', 'bb', or any repo whose name starts with 'cc/'.
**Note**: the subconf name "master" is special; it is the default subconf in
effect for the main conf file and has no restrictions.
### how the "subconf name" is derived
For subconf lines that look just like include statements, i.e.,

12
doc/dev-notes.mkd
View file

@ -29,15 +29,15 @@ easily with gitolite. Each of them responds to `-h` so please run that for
more info.
* `gitolite access` to check access rights given repo, user, type of access
(R, W, ...) and refname (optional). Example use: src/commands/desc
(R, W, ...) and refname (optional). Example use: src/commands/desc.
* `gitolite creator` to get/check the creator of a repo. Example use:
src/commands/desc
src/commands/desc.
* `gitolite git-config` to check gitolite options or git config variables
directly from gitolite's "compiled" output, (i.e., without looking at the
actual `repo.git/config` file or using the `git config` command). Example
use: none yet
use: none yet.
* `gitolite query-rc` to check the value of an RC variable. Example use:
src/commands/desc.
@ -65,11 +65,11 @@ The rest is between you and 'man githooks' :-)
If you want to add additional `update` hook functionality, do this:
* write and test your update hook separately from gitolite
* Write and test your update hook separately from gitolite.
* now add the code to src/VREF. Let's say it is called "foo".
* Now add the code to src/VREF. Let's say it is called "foo".
* to call your new update hook to all accesses for all repos, add this to
* To call your new update hook to all accesses for all repos, add this to
the end of your conf file:
repo @all

22
doc/emergencies.mkd
View file

@ -46,19 +46,19 @@ just rewind) and push that. Here's how to do that:
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
* **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'
* **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
* **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`.
* **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
* **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.
@ -66,7 +66,7 @@ the answer, but here's a list of files you should blow away.
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
* **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`.
@ -103,12 +103,12 @@ the answer, but here's a list of files you should blow away.
* `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`
(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
(Case 2) This can also happen if you changed something like this
repo foo
...<some rules>...
@ -141,7 +141,7 @@ 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**
* **Client side software**
* putty/plink
* jgit/Eclipse
@ -151,7 +151,7 @@ lot more patience than I do, bless 'em!)
* ...probably some more I forgot; will update this list as I remember...
* did I mention putty/plink?
* **ssh**
* **Ssh**
The *superstar* of the "not a gitolite problem" category is actually ssh.
@ -162,7 +162,7 @@ lot more patience than I do, bless 'em!)
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**
* **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

18
doc/extras/glssh.mkd
View file

@ -31,18 +31,18 @@ from somewhere, or maybe buy the OReilly ssh book.
and give the server the public key. (I need not add that the "private"
key must be, well, kept *private*!)
* **generating a key pair on your workstation** is done by running the
* **Generating a key pair on your workstation** is done by running the
command `ssh-keygen -t rsa`. This produces two files in `~/.ssh`. One is
`id_rsa`; this is the **private** key -- ***never*** let it out of your
machine. The other is `id_rsa.pub`, which is the corresponding public
key. This public key is usually just one long line of text.
* on Windows machines with msysgit installed, you should do this from
* On Windows machines with msysgit installed, you should do this from
within a "git bash" window. The command will report the full path where
the files have been written; make a note of this, and use those files in
any of the description that follows
any of the description that follows.
* **adding your public key to the server**'s `~/.ssh/authorized_keys`
* **Adding your public key to the server**'s `~/.ssh/authorized_keys`
file is how ssh uses pubkeys to authenticate users. Let's say
sita@work.station is trying to log in as git@serv.er. What you have to do
is take the `~/.ssh/id_rsa.pub` file for user sita on work.station and
@ -62,12 +62,12 @@ from somewhere, or maybe buy the OReilly ssh book.
But in the gitolite case, it's different; we'll get to that in a minute.
* **troubleshooting pubkey authentication failures**: if you are unable to
* **Troubleshooting pubkey authentication failures**: if you are unable to
get ssh access to the server after doing all this, you'll have to look
in `/var/log/secure` or `/var/log/auth.log` or some such file on the
server to see what specific error `sshd` is complaining about.
* **restricting users to specific commands** is very important for gitolite.
* **Restricting users to specific commands** is very important for gitolite.
If you read `man sshd` and look for `authorized_keys file format`, you'll
see a lot of options you can add to the public key line, which restrict
the incoming user in various ways. In particular, note the `command=`
@ -89,9 +89,9 @@ from somewhere, or maybe buy the OReilly ssh book.
These are two different questions you ought to be having by now:
* how does it distinguish between me and someone else, since we're all
logging in as the same remote user "git"
* how does it restrict what I can do within a repository
* How does it distinguish between me and someone else, since we're all
logging in as the same remote user "git".
* How does it restrict what I can do within a repository.
#### restricting shell access/distinguishing one user from another

82
doc/extras/sts.mkd
View file

@ -33,16 +33,16 @@ and accessing gitolite.
* Your workstation is the **client**. Your userid on the client does not
matter, and it has no relation to your gitolite username.
* the server is called **server** and the "hosting user" is **git**. If
* The server is called **server** and the "hosting user" is **git**. If
this is an RPM/DEB install, the hosting user is probably called
"gitolite", however we will use "git" in this document.
#### taking stock -- relevant files and directories
* the client has a `~/.ssh` containing a few keypairs. It may also have a
* The client has a `~/.ssh` containing a few keypairs. It may also have a
`config` file.
* the client also has a clone of the "gitolite-admin" repo, which contains a
* The client also has a clone of the "gitolite-admin" repo, which contains a
bunch of `*.pub` files in `keydir`. We assume this clone is in `$HOME`;
if it is not, adjust instructions accordingly when needed.
@ -51,29 +51,29 @@ and accessing gitolite.
**authkeys** to save typing, and it always means the one on the server
(we're not interested in this file on the client side).
* the server also has a `~/.gitolite/keydir` which contains a bunch of
* The server also has a `~/.gitolite/keydir` which contains a bunch of
`*.pub` files.
#### normal gitolite key handling
Here's how normal gitolite key handling works:
* (on client) pub key changes like adding new ones, deleting old ones, etc.,
* (On client) pub key changes like adding new ones, deleting old ones, etc.,
are done in the `keydir` directory in the gitolite-admin repo clone. Then
the admin `git add`s and `git commit`s those changes, then `git push`es
them to the server.
* (on server) a successful push from the client makes git invoke the
* (On server) a successful push from the client makes git invoke the
post-update hook in the gitolite-admin repo. This hook is installed by
gitolite, and it does a bunch of things which are quite transparent to
the admin, but we'll describe briefly here:
* the pubkey files from this push are checked-out into
* The pubkey files from this push are checked-out into
`~/.gitolite/keydir` (and similarly the config files into
`~/.gitolite/conf`)
`~/.gitolite/conf`).
* the "compile" script then runs, which uses these files to populate
`~/.ssh/authorized_keys` on the server
* The "compile" script then runs, which uses these files to populate
`~/.ssh/authorized_keys` on the server.
The authkeys file may have other, (non-gitolite) keys also. Those
lines are preserved. Gitolite only touches lines that are found
@ -92,7 +92,7 @@ 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
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.
The following problem(s) indicate that your pubkey is bypassing gitolite and
@ -100,23 +100,23 @@ going straight to a shell. You should start with [appendix 2][sshkeys-lint]
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.
* running `git clone git@server:repositories/reponame` (note presence of
* Running `git clone git@server:repositories/reponame` (note presence of
`repositories/` in URL) works.
[A proper gitolite key will only let you `git clone git@server:reponame`
(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_BINDIR` environment variable not being
set, and the `hooks/update` failing in some way).
[If you run `git remote -v` you will find that your clone URL included the
`repositories/` described above!]
* conversely, using the correct syntax, `git clone git@server:reponame`
* Conversely, using the correct syntax, `git clone git@server:reponame`
(note absence of `repositories/` in the URL), gets you `fatal: 'reponame'
does not appear to be a git repository`, and yet you are sure 'reponame'
exists, you haven't mis-spelled it, etc.
@ -129,16 +129,16 @@ you there again. Especially the first bullet.
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
git@server info` do NOT ask for a password. If you do get asked for a
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
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
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
@ -172,12 +172,12 @@ don't have `ssh-copy-id`? This is broadly what that command does, if you want
to replicate it manually. The input is your pubkey, typically
`~/.ssh/id_rsa.pub` from your client/workstation.
* it copies it to the server as some file
* It copies it to the server as some file.
* it appends that file to `~/.ssh/authorized_keys` on the server
(creating it if it doesn't already exist)
* It appends that file to `~/.ssh/authorized_keys` on the server
(creating it if it doesn't already exist).
* it then makes sure that all these files/directories have go-w perms
* It then makes sure that all these files/directories have go-w perms
set (assuming user is "git"):
/home/git/.ssh/authorized_keys
@ -233,7 +233,7 @@ try, you are being asked for a password.
This is a quick checklist:
* make sure you're being asked for a password and not a pass*phrase*. Do
* Make sure you're being asked for a password and not a pass*phrase*. Do
not confuse or mistake a prompt saying `Enter passphrase for key
'/home/sitaram/.ssh/id_rsa':` for a password prompt from the remote
server!
@ -254,34 +254,34 @@ This is a quick checklist:
discussing one more potential trouble-spot with ssh-agent (see below),
further discussion of ssh-agent/keychain is out of scope of this document.
* ssh is very sensitive to permissions. An extremely conservative setup is
* Ssh is very sensitive to permissions. An extremely conservative setup is
given below, but be sure to do this on **both the client and the server**:
cd $HOME
chmod go-rwx .
chmod -R go-rwx .ssh
* actually, every component of the path to `~/.ssh/authorized_keys` all the
* Actually, every component of the path to `~/.ssh/authorized_keys` all the
way upto the root directory must be at least `chmod go-w`. So be sure to
check `/` and `/home` also.
* while you're doing this, make sure the owner and group info for each of
* While you're doing this, make sure the owner and group info for each of
these components are correct. `ls -ald ~ ~/.ssh ~/.ssh/authorized_keys`
will tell you what they are.
* you may also want to check `/etc/ssh/sshd_config` to see if the "git" user
* You may also want to check `/etc/ssh/sshd_config` to see if the "git" user
is allowed to login at all. For example, if that file contains an
`AllowUsers` config entry, then only users mentioned in that line are
allowed to log in!
* while you're in there, check that file does NOT have a setting for
* 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.
* if all that fails, log onto the server as root, `cd /var/log`, and look
* If all that fails, log onto the server as root, `cd /var/log`, and look
for a file called `auth.log` or `secure` or some such name. Look inside
this file for messages matching the approximate time of your last attempt
to login, to see if they tell you what is the problem.
@ -298,12 +298,12 @@ 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
`/tmp/foo` or something
* Get a copy of `~/.ssh/authorized_keys` from the server and put it in
`/tmp/foo` or something.
* cd to `~/.ssh`
* cd to `~/.ssh`.
* run `/path/to/sshkeys-lint *.pub < /tmp/foo`
* Run `/path/to/sshkeys-lint *.pub < /tmp/foo`.
Note that it is not trying to log in or anything -- it's just comparing
fingerprints as computed by `ssh-keygen -l`.
@ -314,12 +314,12 @@ the server, you're done with this step.
Otherwise you have to rename some keypairs and try again to get the effect you
need. Be careful:
* do not just rename the ".pub" file; you will have to rename the
* Do not just rename the ".pub" file; you will have to rename the
corresponding private key also (the one with the same basename but without
an extension)
an extension).
* if you're running ssh-agent, you may have to delete (using `ssh-add -D`)
and re-add identities for it to pick up the renamed ones correctly
* If you're running ssh-agent, you may have to delete (using `ssh-add -D`)
and re-add identities for it to pick up the renamed ones correctly.
#### typical cause(s)
@ -339,7 +339,7 @@ you're using ssh-agent, otherwise these new keys may not work.
### #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:
ssh -vvv user@host pwd 2> >(grep -i offer)
@ -413,11 +413,11 @@ the server. (This is by design. Don't argue...)
This means that, you get 2 kinds of errors if you bypass gitolite
* when you use `git@server:reponame` with a key that bypasses gitolite
* When you use `git@server:reponame` with a key that bypasses gitolite
(i.e., gets you a shell), this prefixing does not happen, and so the repo
is not found. Neither a clone/fetch nor a push will work.
* conversely, consider `git@server:repositories/reponame.git`. The clone
* Conversely, consider `git@server:repositories/reponame.git`. The clone
operation will work -- you're using the full Unix path, (assuming default
`$REPO_BASE` setting), and so the shell finds the repo where you said it
would be. However, when you push, gitolite's **update hook** kicks in,

3
doc/files.mkd
View file

@ -10,8 +10,7 @@ Let's say you start from a totally clean slate:
$ 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).
You run `git clone git://github.com/sitaramc/gitolite`.
Now you have

14
doc/g2incompat.mkd
View file

@ -56,23 +56,23 @@ functionality, and invoke *that* from the rc file instead.
There are several changes with regard to mirroring:
* there is no 'post-receive' hook to be installed. Mirroring is handled by
* There is no 'post-receive' hook to be installed. Mirroring is handled by
g3's [triggers][] mechanism. Gitolite triggers are enabled by adding (or
uncommenting, in this case) appropriate lines in the rc file.
* the `GL_HOSTNAME` variable is now `HOSTNAME`. (Note that the rc file
* The `GL_HOSTNAME` variable is now `HOSTNAME`. (Note that the rc file
syntax itself has changed quite a bit; to be accurate, HOSTNAME is not a
variable but a hash key with an associated value).
* the `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
* The `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
longer need to set it to anything for mirroring to work.
* the `gl-tool` program does not exist anymore. Adding keys for peer
* The `gl-tool` program does not exist anymore. Adding keys for peer
servers is done just like adding user keys, except that the pubkey file
name must start with `server-`. For example, to add a peer host called
frodo, you will acquire its pubkey and add it as `server-frodo.pub`.
* the config variables are quite different now. The main ones now look like
* The config variables are quite different now. The main ones now look like
this:
option mirror.master = sam
@ -86,7 +86,7 @@ There are several changes with regard to mirroring:
option mirror.redirectOK = all
* there are no more mirroring "keys", (lists of servers named in config keys
* There are no more mirroring "keys", (lists of servers named in config keys
like 'gitolite.mirror.nightly', etc). You can certainly add lines like
option mirror.nightly = merry pippin
@ -95,7 +95,7 @@ There are several changes with regard to mirroring:
`gitolite git-config` to query this variable, grab the list of repos, and
run `gitolite mirror` on each of them.
* the external command to resync mirrors is 'mirror', run just like any
* The external command to resync mirrors is 'mirror', run just like any
other [command][commands]. In particular, you can run `gitolite mirror
-h` to get help. It cannot be run from a slave to ask a master to push
(unlike in the old system) but what's more convenient is that any user who

12
doc/g2migr.mkd
View file

@ -17,11 +17,11 @@ differences are in the rc file, mirroring, "NAME/" rules, and delegation.
> ----
> **presetting the rc file**
> **Presetting the rc file**
> Some rc settings in the older gitolite are such that you cannot directly
> run `gitolite setup` when you're ready to migrate. Doing that will
> **clobber** something important. See [presetting the rc file][rc-preset]
> run `gitolite setup` when you're ready to migrate. **Doing that will
> clobber something important**. See [presetting the rc file][rc-preset]
> for details.
> ----
@ -48,7 +48,7 @@ Some of them have links where there is more detail than I want to put here.
* [subconf][g2i-subconf]: if you're using [delegation][deleg], there is no
implicit "subconf" at the end; you'll have to add it in.
* there are several important differences in mirroring. You can start from
* There are several important differences in mirroring. You can start from
scratch by reading the new [mirroring][mirroring] doc or
[migrate][g2i-mirroring] (carefully!).
@ -236,8 +236,8 @@ put that contain the words "see docs":
## #rc-preset presetting the rc file
Some rc settings in the older gitolite are such that you cannot directly run
`gitolite setup` when you're ready to migrate. Doing that will **clobber**
something important. You have to create a default rc file, edit it
`gitolite setup` when you're ready to migrate. **Doing that will clobber
something important**. You have to create a default rc file, edit it
appropriately, and *then* run `gitolite setup`.
The most serious example of this is `GL_NO_SETUP_AUTHKEYS`, which tells the

9
doc/gsmigr.mkd
View file

@ -44,10 +44,10 @@ Here are the steps on the server:
Now, log off the server and get back to the client. All subsequent
instructions are to be read as "on gitolite admin's workstation".
* **clone** the new gitolite-admin repo to your workstation. (You already
* **Clone** the new gitolite-admin repo to your workstation. (You already
have a clone of the gitosis-admin repo so now you have both).
* **convert** your gitosis config file and append it to your gitolite config
* **Convert** your gitosis config file and append it to your gitolite config
file. Substitute the path for your gitosis-admin clone in `$GSAC` below,
and similarly the path for your gito**lite**-admin clone in `$GLAC`. (The
convert-gitosis-conf program is a standalone program that you can bring
@ -63,7 +63,7 @@ instructions are to be read as "on gitolite admin's workstation".
* Remove the entry for the 'gitosis-admin' repo. You do not need it here
and it may cause confusion.
* **copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC)
* **Copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC)
cp $GSAC/keydir/* $GLAC/keydir
@ -122,5 +122,4 @@ instructions are to be read as "on gitolite admin's workstation".
"sitaram@laptop.pub" and "sitaram@desktop.pub" or whatever. *Please check
the files to make sure this worked properly*
* Check all your changes to your gitolite-admin clone, commit, and push
* Check all your changes to your gitolite-admin clone, commit, and push.

44
doc/http.mkd
View file

@ -11,34 +11,17 @@ that is the same or even relevant -- that is from 2006 and is quite different
* Please read [authentication versus authorisation][auth] first, and make
sure you understand what is gitolite's responsibility and what isn't.
* The 'gitolite' command (for example, 'gitolite compile', 'gitolite
query-rc', and so on) *can* be run on the server, but it's not
straightforward. Assuming you installed using the exact same values as in
this document:
* get a shell by using, say, `su -s /bin/bash - apache`
* run `export HOME=$HOME/gitolite-home`
* run `export PATH=$PATH:$HOME/bin`
Now you can run `gitolite <subcommand>`
* I have tested only on stock Fedora 16; YDMV
* I have tested this only on stock Fedora 16; YDMV.
* As before, I have not tried making repos available to both ssh *and* http
mode clients but it ought to work. If you managed it, I'd appreciate a
doc patch describing how you did it.
## additional requirements
* requires `GIT_PROJECT_ROOT` (see "man git-http-backend" for what this is)
set explicitly (i.e., it is no longer optional). Please set it to some
place outside apache's `DOCUMENT_ROOT`.
## assumptions:
* apache 2.x and git installed.
* httpd runs under the "apache" userid; adjust instructions below if not.
* similarly for "/var/www" and other file names/locations.
* Apache 2.x and git installed.
* Httpd runs under the "apache" userid; adjust instructions below if not.
* Similarly for "/var/www" and other file names/locations.
## instructions
@ -51,8 +34,14 @@ install gitolite in smart http mode.
Make a copy of the script, go through it carefully, (possibly removing lines
that delete files etc.), change values per your system, and only then run it.
<font color="gray">Note that the `GIT_PROJECT_ROOT` variable (see "man
git-http-backend") is no longer optional. Make sure you set it to some place
outside apache's `DOCUMENT_ROOT`.</font>
## usage
### client side
Git URLs look like `http://user:password@server/git/reponame.git`.
The custom commands, like "info", "expand" should be handled as follows. The
@ -68,3 +57,16 @@ the arguments, with `+` representing a space. Here are some examples:
With a few nice shell aliases, you won't even notice the horrible convolutions
here ;-) See t/smart-http for a couple of useful ones.
### server side
The 'gitolite' command (for example, 'gitolite compile', 'gitolite query-rc',
and so on) *can* be run on the server, but it's not straightforward. Assuming
you installed exactly as given in this document, you should
* get a shell by using, say, `su -s /bin/bash - apache`
* run `export HOME=$HOME/gitolite-home`
* run `export PATH=$PATH:$HOME/bin`
and *then* you can run `gitolite <subcommand>`

9
doc/index.mkd
View file

@ -19,6 +19,7 @@ For users of gitolite v2.x (call it "g2" for convenience),
## #ql quick links
* [Trying][trying] out gitolite.
* 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**.
@ -37,12 +38,12 @@ most people see:
* Use a single unix user ("real" user) on the server.
* Provide access to many gitolite users:
* they are not "real" users
* they do not get shell access
* they are not "real" users,
* they do not get shell access.
* 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,
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
installed.
* Authentication is most commonly done using sshd, but you can also use

51
doc/install.mkd
View file

@ -42,11 +42,12 @@ Notes:
### server
* any Unix system with a posix compatible "sh".
* git version 1.6.6 or later
* perl 5.8.8 or later
* openssh (almost any version). Optional if you're using [smart http][http]
* a dedicated Unix userid to be the hosting user, usually "git" but it can
* Any Unix system with a posix compatible "sh".
* Git version 1.6.6 or later.
* Perl 5.8.8 or later.
* Openssh (almost any version). Optional if you're using [smart
http][http].
* A dedicated Unix userid to be the hosting user, usually "git" but it can
be any user, even your own normal one. (If you're using an RPM/DEB the
install probably created one called "gitolite").
@ -55,17 +56,13 @@ side.
### client
* openssh client
* git 1.6.6 or later. Almost any git client will work, as long as it knows
* 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.
git clone git://github.com/sitaramc/gitolite
## the actual install
@ -87,7 +84,7 @@ 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
git clone git://github.com/sitaramc/gitolite
you can run the 'install' command in 3 different ways:
@ -168,35 +165,35 @@ will normally touch in normal repos is the `update` hook.
1. Carefully wipe out the old gitolite
* the **code**
* The **code**
* delete or move away all the old gitolite scripts. Check the path
* Delete or move away all the old gitolite scripts. Check the path
to the gl-auth-command in `~/.ssh/authorized_keys` if you forgot
where you put them.
* delete or move away the two directories named in the two variables
`GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`
* Delete or move away the two directories named in the two variables
`GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`.
* the **rc file**
* The **rc file**
* rename `~/.gitolite.rc` to something else
* Rename `~/.gitolite.rc` to something else.
* the **admin repo**
* The **admin repo**
* clone `~/repositories/gitolite-admin.git` to someplace safe
* then delete `~/repositories/gitolite-admin.git`
(make sure you do not delete any other repos!)
(Make sure you do not delete any other repos!)
* the **admin directory**
* The **admin directory**.
* if you need to preserve logs, move the ~/.gitolite/logs` directory
somewhere else
* If you need to preserve logs, move the ~/.gitolite/logs` directory
somewhere else.
* if you added any custom hooks and wish to preserve them, move the
~/.gitolite/hooks` directory somewhere else
* If you added any custom hooks and wish to preserve them, move the
~/.gitolite/hooks` directory somewhere else.
* delete `~/.gitolite`
* Delete `~/.gitolite`.
2. Read about [presetting][rc-preset] the rc file; if you're using any
variables listed as requiring preset, follow those instructions to create

40
doc/mirroring.mkd
View file

@ -17,19 +17,19 @@ world they are at best read-only.
Gitolite extends this simple notion in the following ways:
* different masters and sets of slaves for different repos
* Different masters and sets of slaves for different repos
This lets you do things like
This lets you do things like:
* use the server closest to *most* of its developers as the master for
that repo
* not mirror a repo at all to some servers
* have repos that are purely local to a server (not mirrored at all)
* negotiate mirroring with servers that are not even under your control
* push to a slave on demand or via cron (helps deal with bandwidth or
* Use the server closest to *most* of its developers as the master for
that repo.
* Not mirror a repo at all to some servers.
* Have repos that are purely local to a server (not mirrored at all).
* Negotiate mirroring with servers that are not even under your control.
* Push to a slave on demand or via cron (helps deal with bandwidth or
connectivity constraints).
* pushes to a slave can be transparently forwarded to the real master
* Pushes to a slave can be transparently forwarded to the real master.
Your developers need not worry about where a repo's master is -- they just
write to their local mirror for *all* repos, even if their local mirror is
@ -37,16 +37,16 @@ Gitolite extends this simple notion in the following ways:
## caveats
* mirroring will never *create* a repo on a slave; it has to exist and be
* Mirroring will never *create* a repo on a slave; it has to exist and be
prepared to receive updates from the master. (For example, [wild][] repos
must be created on the slave as well, otherwise they will not propagate).
* mirroring is only for git repos. Ancillary files like gl-creator and
* Mirroring is only for git repos. Ancillary files like gl-creator and
gl-perms in the repo directory are not mirrored; you must do that
separately. Files in the admin directory (like log files) are also not
mirrored.
* if you ever do a [bypass push][bypass], mirroring will not work.
* If you ever do a [bypass push][bypass], mirroring will not work.
Mirroring checks also will not work -- for example, you can push to a
slave, which is not usually a good idea. So don't bypass gitolite if the
repo is mirrored!
@ -60,24 +60,24 @@ file settings and syntax.
On **each** server:
* install gitolite normally. Make clones of the 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.
* give the 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'.
* 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
public key to a common area and name it after the host, but with 'server-'
prefixed. So the pubkey for server 'mars' would be stored as
'server-mars.pub'.
* copy all keys to all the admin repo clones on your workstation and and add
* Copy all keys to all the admin repo clones on your workstation and and add
them as usual. This is an `O(N^2)` operation ;-)
You may have guessed that the prefix 'server-' is special, and
distinguishes a human user from a mirroring peer.
* create "host" aliases to refer to all other machines. See [here][ssh-ha]
* Create "host" aliases to refer to all other machines. See [here][ssh-ha]
for what/how.
The host alias for a host (in all other machines' `~/.ssh/config` files)
@ -88,7 +88,7 @@ On **each** server:
Normally you should be able to build one common file and append it to all
the servers' `~/.ssh/config` files.
* the following **MUST** work for **each pair** of servers that must talk to
* The following **MUST** work for **each pair** of servers that must talk to
each other:
# on server mars
@ -101,7 +101,7 @@ On **each** server:
Check this command from *everywhere to everywhere else*, and make sure you
get expected results. **Do NOT proceed otherwise.**
* setup the gitolite.conf file on all the servers. If the slaves are to be
* Setup the gitolite.conf file on all the servers. If the slaves are to be
exact copies of the master, you need to do the complete configuration only
on the master; the slaves can have just this:
@ -114,7 +114,7 @@ On **each** server:
because on the first push to the master it will update all the slaves
anyway.
* when that is all done and tested, **enable mirroring** by going through
* When that is all done and tested, **enable mirroring** by going through
the rc file and uncommenting all the lines mentioning `Mirroring`.
### conf file settings and syntax

16
doc/non-core.mkd
View file

@ -29,11 +29,11 @@ Here's a list of remote commands that are shipped:
The following "sugar" programs are available:
* continuation-lines -- allow the use of C-style backslash escaped
* Continuation-lines -- allow the use of C-style backslash escaped
continuation lines in the conf file. I don't like it but some people do,
and now I can support them without bulking up the "core" conf parser!
* keysubdirs-as-groups -- someone wanted the sub-directory name (of
* Keysubdirs-as-groups -- someone wanted the sub-directory name (of
"keydir/") in which the pubkey was placed to be a group to which the user
automatically belonged. A very unusual requirement, and one which would
*never* have seen the light of day in g2, but in g3 it's easy, and doesn't
@ -46,9 +46,9 @@ The following "sugar" programs are available:
The `PRE_GIT` triggers are:
* partial-copy -- this has its own section later in this page
* partial-copy -- this has its own section later in this page.
* renice -- this renices the entire job to whatever value you specify
* renice -- this renices the entire job to whatever value you specify.
The `POST_GIT` triggers are:
@ -79,7 +79,7 @@ The `POST_COMPILE` triggers are:
The `POST_CREATE` triggers are:
* the last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for
* The last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for
obvious reasons.
## VREFs
@ -124,10 +124,10 @@ And that should be it. **Please test it and let me know if it doesn't work!**
WARNINGS:
* if you change the config to disallow something that used to be allowed,
* If you change the config to disallow something that used to be allowed,
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.
* not tested with smart http; probably 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.

4
doc/progit.mkd
View file

@ -18,13 +18,11 @@ Gitolite is somewhat unusual as far as "server" software goes -- access is via s
To begin, create a user called `git` on your server and login to this user. Copy your ssh pubkey (a file called `~/.ssh/id_rsa.pub` if you did a plain `ssh-keygen` with all the defaults) from your workstation, renaming it to `YourName.pub`. Then run these commands:
git clone -b g3 git://github.com/sitaramc/gitolite
git clone git://github.com/sitaramc/gitolite
gitolite/install -ln
gitolite setup -pk $HOME/YourName.pub
# for example, I would run 'gitolite setup -pk $HOME/sitaram.pub'
(Note: the "-b g3" will not be needed once gitolite v3 becomes the "master" version.)
Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation. You administer your gitolite setup by making changes to this repository and pushing. See adding [users][] and [repos][] to start with.

14
doc/qi.mkd
View file

@ -5,7 +5,7 @@
On the server:
# get the software
git clone -b g3 git://github.com/sitaramc/gitolite
git clone git://github.com/sitaramc/gitolite
# install it
gitolite/install -ln
@ -20,18 +20,18 @@ On your workstation:
## ASSUMPTIONS
* this is a fresh install, not a migration from the old gitolite (v1.x,
* This is a fresh install, not a migration from the old gitolite (v1.x,
v2.x).
* on the server, your `$PATH` contains `$HOME/bin`. If you don't like that,
* 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
* 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
* 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

26
doc/rare.mkd
View file

@ -4,21 +4,21 @@
On the server:
* move the repos to `$HOME/repositories`.
* Move the repos to `$HOME/repositories`.
* make sure that:
* Make sure that:
* they are all *bare* repos
* all the repo names end in ".git"
* all the files and directories are owned and writable by the gitolite
hosting user (especially true if you copied them as root)
* They are all *bare* repos.
* All the repo names end in ".git".
* All the files and directories are owned and writable by the gitolite
hosting user (especially true if you copied them as root).
* run `gitolite setup`. **If you forget this step, you can also forget
* Run `gitolite setup`. **If you forget this step, you can also forget
about write access control!**
Back on your workstation:
* [add them][repos] to conf/gitolite.conf in your clone of the admin repo,
* [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
@ -42,11 +42,11 @@ servers is this (untested but should work; feedback appreciated):
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.
Make sure the files end up with the 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
5. Run `gitolite setup`.
6. 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`.

2
doc/rc.mkd
View file

@ -20,7 +20,7 @@ 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`)
* hashes (like `ROLES`, `COMMANDS`)

6
doc/refex.mkd
View file

@ -5,12 +5,12 @@ A refex is a word I made up to mean "a regex that matches a ref". If you know
In addition:
* if no refex is supplied, it defaults to `refs/.*`, for example in a rule
* If no refex is supplied, it defaults to `refs/.*`, for example in a rule
like this:
RW = alice
* a refex not starting with `refs/` is assumed to start with `refs/heads/`.
* 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
@ -20,7 +20,7 @@ In addition:
RW refs/tags/v[0-9] = bob
* 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
end is assumed). So a refex of `master` will match all these:

4
doc/repos.mkd
View file

@ -52,5 +52,5 @@ 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.
* 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.

32
doc/rules.mkd
View file

@ -58,35 +58,35 @@ example will pass the pre-git check.
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].
* the rules pertaining to this repo *and* this user (or to a group to which
they belong, respectively) are kept; the rest are ignored
* The rules pertaining to this repo *and* this user (or to a group to which
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:
* if the ref does not match the [refex][], the rule is skipped
* if it's a deny rule (the permissions field is a `-`), access is
**rejected** and the matching stops
* if the permission field matches the specific [type of
* If the ref does not match the [refex][], the rule is skipped.
* If it's a deny rule (the permissions field is a `-`), access is
**rejected** and the matching stops.
* If the permission field matches the specific [type of
write][write-types] operation, access is **allowed** and the matching
stops
stops.
* if no rule ends with a decision, ("fallthru"), access is **rejected**.
* If no rule ends with a decision, ("fallthru"), access is **rejected**.
Now you need to understand how [refex][] matching happens and how the
permissions match the various [types of write operations][write-types].
Using these, you can see, in our example, that:
* everyone, even wally, can read the repo.
* dilbert can push, rewind, or delete any ref.
* alice can push, rewind, or delete any ref whose name starts with 'dev';
* Everyone, even wally, can read the repo.
* Dilbert can push, rewind, or delete any ref.
* Alice can push, rewind, or delete any ref whose name starts with 'dev';
see [refex][] for details.
* alice can also push (but not rewind or delete) any ref whose name starts
* Alice can also push (but not rewind or delete) any ref whose name starts
with 'temp/'. This applies to bob also.
* if it weren't for line 3, the previous statement would apply to wally
* If it weren't for line 3, the previous statement would apply to wally
also.
Interestingly, wally can get past the pre-git check because gitolite ignores
@ -94,7 +94,7 @@ 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
[deny at pre-git][deny-rules].
### #perms summary of permissions
### #permsum summary of permissions
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

6
doc/setup.mkd
View file

@ -31,13 +31,13 @@ server. That won't work.
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.
* 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].
* To replace a [lost admin key][lost-key].
* to setup gitolite for http mode (run 'gitolite setup -h' for more info)
* To setup gitolite for http mode (run 'gitolite setup -h' for more info).
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!

8
doc/special.mkd
View file

@ -34,13 +34,13 @@ A user "alice" (if she's in the userlist) can then push any branches inside
(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
Compared to using arbitrary branch names on the same server, this:
* reduces namespace pollution by corralling all these ad hoc branches into
* Reduces namespace pollution by corralling all these ad hoc branches into
the "personal/" namespace.
* reduces branch name collision by giving each developer her own
* 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
* Removes the need to think about access control, because a user can push
only to his own sub-hierarchy.
## delegating access control responsibilities

6
doc/sskm.mkd
View file

@ -223,12 +223,12 @@ Listing the keys shows that that new key is now marked active again:
These are the things that can break if you allows your users to use this command:
* if you, as the gitolite admin, are in the habit of force-pushing changes
* If you, as the gitolite admin, are in the habit of force-pushing changes
to the admin repo instead of doing a `git pull` (or, even better, a `git
pull --rebase`) then you had better not enable this command. Your users
will eventually come after you with pitchforks ;-)
* there is no way to distinguish `foo/alice.pub` from `bar/alice.pub` using
* There is no way to distinguish `foo/alice.pub` from `bar/alice.pub` using
this command. You can distinguish `foo/alice.pub` from
`bar/alice@home.pub`, but that's not because of the foo and bar, it's
because the two files have different keyids.
@ -236,7 +236,7 @@ These are the things that can break if you allows your users to use this command
In other words, sskm only works with the older style, not with the
"subdirectory" style of [multi-key][] management.
* keys placed in specific folders (for whatever reasons), will probably not
* Keys placed in specific folders (for whatever reasons), will probably not
stay in those folders if this command is used. Even a key delete, followed
by undoing the delete, will cause the key to effectively move to the root
of the key store (i.e., the `keydir` directory in the gitolite-admin repo).

25
doc/testing.mkd
View file

@ -7,9 +7,11 @@ so be sure to use a throwaway userid**.</font>
git clone git://github.com/sitaramc/gitolite
cd gitolite
git checkout -f g3
prove
(Make sure sshd allows incoming ssh to this userid at least from localhost.
Out of scope for this document: sshd config, 'AllowUsers', etc...)
Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
Take a look at some of the scripts and you will see what it looks like. It
has a few quirks and nuances; if you really care, email me.
@ -23,3 +25,24 @@ would otherwise take.
If you think that defeats the purpose of the testing, you haven't read
[this][auth] yet.
## #trying trying out gitolite
It's easy to take gitolite for a trial run, in ssh mode, and play with all of
its features (except mirroring).
Create a **throw-away userid**, log in to it, then do what the "testing
gitolite" section above says, except instead of running `prove`, you run
`prove t/ssh*`.
When this is done, you get a gitolite installation with 7 gitolite users
("admin", and "u1" through "u6").
Don't forget that the client and the server are all on the same user on the
same machine; we're *simulating* 7 gitolite users using ssh keys! (How?
Maybe `~/.ssh/config` will give you a hint).
URLs look like `user:repo`, so for example you can clone the admin repo by
`git clone admin:gitolite-admin`. Remote commands look like `ssh u1 info`.
So start by cloning the admin repo, and try out whatever you want!

6
doc/user.mkd
View file

@ -3,10 +3,6 @@
...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.
----
[[TOC]]
@ -42,7 +38,7 @@ 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.
as gitolite is concerned) is automatically recorded by gitolite.
## other commands

42
doc/vref.mkd
View file

@ -82,14 +82,14 @@ exit.
## how it works -- details
* the VREF code is only called if there are any VREF rules for the user,
* The VREF code is only called if there are any VREF rules for the user,
which means when the lead developer pushes, the VREF is not called at all.
Side note: this is enormously more efficient than adding additional
`update` hooks, which will get executed whether they are needed or not,
for every repo and every user!
* when dev2 or dev3 push, gitolite first checks the real ref
* When dev2 or dev3 push, gitolite first checks the real ref
(`ref/heads/master` or whatever). After this it looks at VREF rules, and
calls an external program for every one it finds. Specifically, in a line
like
@ -102,29 +102,29 @@ exit.
The program is passed **nine arguments** in this case (see next section
for details).
* the script can print anything it wants to STDOUT; the first word in each
* The script can print anything it wants to STDOUT; the first word in each
such line will be treated as a virtual ref to be matched against all the
rules, while the rest, if any, is a message to be added to the standard
"...DENIED..." message that gitolite prints if that refex matches.
Usually it only makes sense to either
* print nothing -- if you don't want the rule that triggered it to match
* Print nothing -- if you don't want the rule that triggered it to match
(ie., whatever condition being tested was not violated; like if the
count of changed files did not exceed 9, in our earlier example)
* print the refex itself (plus an optional message), so that it matches
the line which invoked it
count of changed files did not exceed 9, in our earlier example).
* Print the refex itself (plus an optional message), so that it matches
the line which invoked it.
### arguments passed to the vref code
* arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
to the update hook (see 'man githooks')
* Arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
to the update hook (see 'man githooks').
This, combined with the fact that non-zero exits are detected, mean that
you can simply use an existing update.secondary as a new VREF as-is, no
changes needed.
* arguments **4 and 5**: the 'oldtree' and 'newtree' SHAs. These are the
* Arguments **4 and 5**: the 'oldtree' and 'newtree' SHAs. These are the
same as the oldsha and newsha values, except if one of them is all-0.
(indicating a ref creation or deletion). In that case the corresponding
'tree' SHA is set (by gitolite, as a courtesy) to the special SHA
@ -134,15 +134,15 @@ exit.
(None of these shenanigans would have been needed if `git diff $oldsha
$newsha` would not error out when passed an all-0 SHA.)
* argument **6**: the attempted access flag. Typically `W` or `+`, but
* Argument **6**: the attempted access flag. Typically `W` or `+`, but
could also be `C`, `D`, or any of these 4 followed by `M`. If you have to
ask what they mean, you haven't read enough gitolite documentation to be
able to make virtual refs work.
* argument **7**: is the entire refex; in our example
* Argument **7**: is the entire refex; in our example
`VREF/COUNT/3/NEWFILES`.
* arguments **8 onward**: are the split out (by `/`) portions of the refex,
* Arguments **8 onward**: are the split out (by `/`) portions of the refex,
excluding the first two components. In our example they would be `3`
followed by `NEWFILES`.
@ -288,14 +288,14 @@ quite different.
Here are some more ideas:
* number of commits (`git rev-list --count $old $new`)
* number of binary files in commit (currently I only know to count
occurrences of ` Bin ` in the output of `git diff --stat`
* number of *new* binary files (count ` Bin 0 ->` in `git diff --stat`
output)
* time of day/day of week (see example snippet somewhere above)
* IP address
* phase of the moon
* Number of commits (`git rev-list --count $old $new`).
* Number of binary files in commit (currently I only know to count
occurrences of ` Bin ` in the output of `git diff --stat`.
* Number of *new* binary files (count ` Bin 0 ->` in `git diff --stat`
output).
* Time of day/day of week (see example snippet somewhere above).
* IP address.
* Phase of the moon.
Note that pretty much anything that involves `$oldsha..$newsha` will have to
deal with the issue that when you push a new tag or branch, the "old" part

124
doc/why.mkd
View file

@ -1,47 +1,97 @@
# why might you need gitolite
Gitolite is separate from git, and needs to be installed and configured. So...
why do we bother?
[[TOC]]
----
## basic use case
Gitolite is useful in any server that is going to host multiple git
repositories, each with many developers, where some sort of access control is
required.
repositories, each with many developers, where "anyone can do anything to any
repo" is not a good idea. Here're two examples to illustrate.
In theory, this can be done with plain old Unix permissions: each user is a
member of one or more groups, each group "owns" one or more repositories, and
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
allow/disallow users access to repos.
Example 1, 3 repos, 3 developers with different levels of access to each repo:
But there are several disadvantages here:
repo foo
RW+ = alice
R = bob
* Every user needs a userid and password on the server. This is usually a
killer, especially in tightly controlled environments.
* Adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with.
* *Viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these
manually.
* Auditing historical permissions or permission changes is pretty much
impossible without extraneous tools.
* Errors or omissions in setting the permissions exactly can cause problems
of either kind: false accepts or false rejects.
* Without going into ACLs it is not possible to give some people read-only
access while some others have read-write access to a repo (unless you make
it world-readable). Group access just doesn't have enough granularity.
* It is absolutely impossible to restrict pushing by branch name or tag
name.
repo bar
RW+ = bob
R = alice
Gitolite does away with all this:
repo baz
RW+ = carol
R = alice bob
* It uses ssh magic to remove the need to give actual unix userids to
developers.
* It uses a simple but powerful config file format to specify access rights.
* Access control changes are affected by modifying this file, adding or
removing user's public keys, and "compiling" the configuration.
* This also makes auditing trivial -- all the data is in one place, and
changes to the configuration are also logged, so you can audit them.
* Finally, the config file allows distinguishing between read-only and
read-write access, not only at the repository level, but at the branch
level within repositories.
Example 2, one repo, but different levels of access to different branches and
tags for different developers:
repo foo
RW+ master = alice
RW+ dev/ = bob
RW refs/heads/tags/v[0-9] = ashok
## #alt alternatives
### unix permissions and ACLs
If you're a masochist, you could probably do example 1 with Unix permissions
and facls. But you can't do example 2 -- git is not designed to allow that!
Here are some other disadvantages of the Unix ACL method:
* Every user needs a userid and password on the server.
* Changing access rights involves complex `usermod -G ...` mumblings
(I.e., the "pain" mentioned above is not a one-time pain!)
* *Viewing* the current set of permissions requires running multiple
commands to list directories and their permissions/ownerships, users and
their group memberships, and then correlating all these manually.
* Auditing historical permissions or permission changes is impossible.
### #gcr Gerrit Code Review
The best real alternative to gitolite is Gerrit Code Review. If code review
is an essential part of your workflow, you should use Gerrit.
Here're some high level differences between gitolite and Gerrit:
**Size**: 3000+ lines of perl versus of 56,000+ lines of Java
**Architecture**: Gitolite sits on top of "standard" git and openssh, which
are assumed to already be installed. Gerrit includes its own git stack (jgit)
and sshd (Apache Mina). In Java tradition, they all come bundled together.
(Corollary: As far as I know jgit does not support the same hooks that 'man
githooks' talks about).
Gitolite uses a plain text config file; gerrit uses a database.
**User view**: Gitolite is invisible to users except when access is denied. I
think Gerrit is much more visible to devs.
On a related note, gitolite does not do anything special with signed or
annotated tags, nor does it check author/committer identity. However, it is
trivial to add your own code to do either (or if someone contributes it, to
just "enable" what ships with gitolite in a disabled state).
### gitorious
Anecdotally, gitorious is very hard to install. Comparison with gitolite may
be useless because I believe it doesn't have branch/tag level access control.
However, I can't confirm or deny this because I can't find any documentation
on the website.
In addition, the main website hides the source code very well, so you already
have a challenge! [The only link I could find was tucked away at the bottom
of the About page, in the License section].
### gitlab
Gitlab is built on top of gitolite, but I don't know more than that as yet.
Patches welcome.
### others
Please send in patches to this doc if you know of other open source git
hosting solutions that do access control.

20
doc/wild.mkd
View file

@ -90,9 +90,11 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters.
Side-note: contrast with refexes
> ----
> Just for interest, note that this is in contrast to the refexes for the >
> *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,
@ -100,11 +102,13 @@ Side-note: contrast with refexes
> 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.
The tokens READERS and WRITERS are called "role" names. The access rules in
the conf file decide what permissions these roles have, but they don't say
what users are in each of 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
@ -146,4 +150,8 @@ command. Try `ssh git@host info -h` to get help on the info command.
## deleting a wild repo
TBD
Run the whimsically named "D" command -- try `ssh git@host D -h` for more info
on how to delete a wild repo. (Yes the command is "D"; it's meant to be a
counterpart to the "C" permission that allowed you to create the repo in the
first place). Of course this only works if your admin has enabled the command
(gitolite ships with the command disabled for remote use).

8
doc/write-types.mkd
View file

@ -11,14 +11,14 @@ The most common are:
Sometimes you want to allow people to push, but not *create* a ref. Or
rewind, but not *delete* a ref. The `C` and `D` qualifiers help here.
* when a rule specifies `RWC` or `RW+C`, then *rules that do NOT have the C
qualifier will no longer permit **creating** a ref*
* When a rule specifies `RWC` or `RW+C`, then *rules that do NOT have the C
qualifier will no longer permit **creating** a ref*.
<font color="gray">Please do not confuse this with the standalone `C`
permission that allows someone to [create][] a **repo**</font>
* when a rule specifies `RWD` or `RW+D`, then *rules that do NOT have the C
qualifier will no longer permit **deleting** a ref*
* When a rule specifies `RWD` or `RW+D`, then *rules that do NOT have the C
qualifier will no longer permit **deleting** a ref*.
Note: These two can be combined, so you can have `RWCD` and `RW+CD` as well.