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

doc/src: major doc/help text revamp

Browse source 
also removed some dead code from compile (pre PTA days)
This commit is contained in:
Sitaram Chamarty 2009-10-30 21:25:06 +05:30
parent 5108aedd48
commit 92d5062ad0
11 changed files with 82 additions and 348 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.mkd
View file

@ -1,10 +1,8 @@
# gitolite
> [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
> please read if upgrading gitolite]
> [Update 2009-10-10: apart from all the nifty new features, there's now an
> "easy install" script in the src directory. Please see the INSTALL
> [Update 2009-10-28: apart from all the nifty new features, there's now an
> "easy install" script in the src directory. This script can be used to
> install as well as upgrade a gitolite install. Please see the INSTALL
> document in the doc directory for details]
----
@ -64,8 +62,10 @@ deleting a branch (which is really just an extreme form of rewind). I needed
something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
Here're **some more features**. All of them are documented in detail
somewhere in the `doc/` subdirectory.
Here're **some more features**. All of them, and more, are documented in
detail [here][gsdiff].
[gsdiff]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#diff
* simpler, yet far more powerful, config file syntax, including specifying
gitweb/daemon access. You'll need this power if you manage lots of
@ -73,6 +73,8 @@ somewhere in the `doc/` subdirectory.
* config file syntax gets checked upfront, and much more thoroughly
* if your requirements are still too complex, you can split up the config
file and delegate authority over parts of it
* easier to specify gitweb/daemon access, and easier to link gitweb
authorisation with gitolite
* more comprehensive logging [aka: management does not think "blame" is just
a synonym for "annotate" :-)]
* "personal namespace" prefix for each dev
@ -85,8 +87,8 @@ somewhere in the `doc/` subdirectory.
Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one. The code is
very small and easily reviewable -- the 2 programs that actually control
access when a user logs in total about 200 lines of code (about
80 lines according to "sloccount").
access when a user logs in total about 220 lines of code (about 90 lines
according to "sloccount").
For the first person to find a security hole in it, defined as allowing a
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,

7
conf/example.gitolite.rc
View file

@ -57,12 +57,7 @@ $GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y-%m.log";
# --------------------------------------
# Please DO NOT change the following paths unless you really know what you're
# doing. It'll work for now but it's officially deprecated to have them
# elsewhere from now on, and may break some future features.
# Anyway, the conf files and keydirs don't grow constantly, (like the logs and
# the repositories do), so I don't think this is a major problem for anyone.
# Please DO NOT change these three paths
$GL_CONF="$GL_ADMINDIR/conf/gitolite.conf";
$GL_KEYDIR="$GL_ADMINDIR/keydir";

37
doc/0-INSTALL.mkd
View file

@ -1,9 +1,12 @@
# installing gitolite
This document tells you how to install gitolite. After the install is done,
you may want to see the "admin" document for adding users, repos, etc.
you may want to see the [admin document][admin] for adding users, repos, etc.
There's an easy install script for Linux, and for other Unixes there's a
[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
There's an easy install script that requires bash (**strongly** recommended),
but if you have no bash or you're on one of the legacy Unixes there's a
slightly more manual process. Both are explained here.
In this document:
@ -25,12 +28,12 @@ case. **This script is meant to be run on your workstation, not on the
server!** It will take care of all the server side work, *and* get you
"push-to-admin" too :-) In short, it does **everything**!
Assumptions:
Assumptions/pre-requisites:
* you have a server to host gitolite
* git is installed on that server (and so is perl)
* you have a userid on that server
* you have ssh-pubkey (password-less) login to that userid
* you have ssh-pubkey (**password-less**) login to that userid
* (if you have only password access, run `ssh-keygen -t rsa` to create a
new keypair if needed, then run `ssh-copy-id user@host`)
* you have a clone or an archive of gitolite somewhere on your workstation
@ -64,26 +67,24 @@ actually doing, I suggest you skip the `-q`.
#### disadvantages
* has been tested only with Linux
* need a recent bash
### manual install
If for some reason you cannot use the easy-install method, (for example,
you're on a non-Linux machine), it's not very complicated. Just open the file
`src/00-easy-install.sh` in a nice, syntax coloring, text editor, and follow
the instructions marked "MANUAL" :-)
If you don't have bash, it's not very complicated to do it manually. Just
open the file `src/00-easy-install.sh` in a nice, syntax coloring, text
editor, and follow the instructions marked "MANUAL" :-)
### other notes
* If you edit `~/.gitolite.rc` and change any paths, be sure to keep the
perl syntax -- you *don't* have to know perl to do so, it's fairly easy to
guess in this limited case
* the config file is (by default) at `~/.gitolite/conf/gitolite.conf`,
though you can change its location in the "rc" file. Edit the file as you
wish. The comments in the example file (`conf/example.conf`) ought to be
clear enough but let me know if not
* if you run `src/00-easy-install.sh` without the `-q` option, you will be
given a chance to edit `~/.gitolite.rc`. You can change any options (such
as paths, for instance), but be sure to keep the perl syntax -- you
*don't* have to know perl to do so, it's fairly easy to guess in this
limited case.
### next steps
See the "admin" document for how to add users, etc.
The last message produced by the easy install script should tell you how to
add users, repos, etc., and you will find more details in the [admin][admin]
document.

107
doc/0-UPGRADE.mkd
View file

@ -1,107 +0,0 @@
# upgrading gitolite atomically
Upgrading is done **manually, on the server** (except the last step, which is
on your admin repo clone), even if you installed it using the easy install
script on the client. First, it's not as difficult as an install so you don't
really need a script. Second, you may have customised the "rc" file
(`~/.gitolite.rc` on the server) and I'm reluctant to mess with that in an
automated way.
### general upgrade notes
If you follow the steps below, you can make the upgrade "atomic", so you don't
have to do it at a "quiet" time or something.
1. copy a tar file containing the new version to the server, untar it to some
temp directory and `cd` to it
2. *prepare* the new version of `~/.gitolite.rc`. It **must** have **all**
the variables defined in `conf/example.gitolite.rc` (the "new" rc file),
because the new versions of the programs will be depending on seeing these
variables.
However, it must also retain any customisations you made to the **old**
variables.
So this is what you do:
* make a copy of `conf/example.gitolite.rc` as `~/glrc.new`
* if your current `~/.gitolite.rc` had any customisations (where you
changed the defaults in some way), edit `~/glrc.new` and make those
same changes there
3. upgrade the rc file first
cp ~/glrc.new ~/.gitolite.rc
4. upgrade the software
src/install.pl
5. compile the config once again, in case the *internal* format of the
compiled config file (`$GL_CONF_COMPILED`) has changed.
To do this, you have to do a "git push" on the client side. That might
require a dummy change (maybe add a blank line somewhere) because
otherwise the push will not happen.
And you're done.
### upgrade notes for specific versions
If any extra steps beyond the generic ones above are needed, they will be
listed here, newest first.
#### upgrading from 410c9ba
Between 410c9ba and this version, gitolite managed to make "push to admin" the
default for new installs, but in a much more painless way. If you're
upgrading, you're not forced to use "push to admin", but I'd suggest you:
* make sure you have password-less (pubkey) login to a command line on your
server
* save your `~/.gitolite.rc`, `keydir/*.pub` and your `conf/gitolite.conf`
files from the server, bring them to your workstation
* then run `src/00-easy-install.sh` on the workstation, as if it were a
fresh install
* when the editor pops up to edit the rc file, delete all the lines in
it and copy them from the saved `~/.gitolite.rc`
* at the end of the script, after the gitolite-admin repo has been
cloned successfully, copy the saved `conf/gitolite.conf` and
`keydir/*.pub` to the clone, then add, commit, and push
Gitolite also learnt to delegate parts of the config to other users. See
`doc/5-delegation.mkd` for details.
#### upgrading from 8217ef9
Between 8217ef9 and this version, gitolite learnt to handle gitweb/daemon
access. As a result, the rc file acquired a new variable, `$PROJECTS_LIST`,
which you have to set to whatever your gitweb installation requires.
#### upgrading from 86faae4
Between 86faae4 and this version, gitolite had a *major* change in the
*internal* format of the compiled config file. Please do not omit step 5 in
the generic instructions above.
#### upgrading from 5758f69
Between 5758f69 and this version, gitolite learnt to allow "groupnames" for
repos as well. The `conf/example.conf` has been recommented to explain the
syntax but it's really a no-brainer: what you could previously do only for
usernames, you can now do for reponames also.
#### upgrading from abb4580
Two new features (personal branches, and customisable logfile names/locations)
have been added between abb4580 and this version.
* if you want to enable the personal branches feature, choose one of the
alternative values given for `$PERSONAL` or change it to something you
like; by default it is empty, which disables the feature
* if you want the log files named or grouped differently, choose one of the
alternative values for `$GL_LOGT`. **Note** that if you choose to put
them in some other directory than the default, you **must** create that
directory (`mkdir`) yourself; gitolite will not do that for you

16
doc/1-migrate.mkd
View file

@ -36,8 +36,11 @@ Here's how we migrated my work repos:
Now, log off the server and get back to the client:
1. follow instructions to install gitolite; see install document. Make sure
that you **don't** change the default path for `$REPO_BASE`!
[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
1. follow instructions to install gitolite; see the [install document][inst].
Make sure that you **don't** change the default path for `$REPO_BASE` if
you edit the config file!
2. **convert** your gitosis config file. Substitute the path for your
gitosis-admin clone in `$GSAC` below, and similarly the path for your
@ -51,10 +54,11 @@ Now, log off the server and get back to the client:
cp $GSAC/keydir/* $GLAC/keydir
4. **Important: expand any multi-key files you may have**. See the "faq,
tips, etc" document in the doc directory for an explanation of what
multi-keys are, how gitosis does them and how gitolite does it
differently.
4. **Important: expand any multi-key files you may have**. [Here][mk]'s an
explanation of what multi-keys are, how gitosis does them and how gitolite
does it differently.
[mk]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#multikeys
You can split the keys manually, or use the following code (just
copy-paste it into your xterm after "cd"-ing to your gitolite-admin repo

13
doc/2-admin.mkd
View file

@ -14,9 +14,9 @@ Please read on to see how to do this correctly.
#### adding users and repos
* ask each user who will get access to send you a public key. See other
sources (for example
[here](http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key))
for how to do this
sources (for example [here][genpub]) for how to do this
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
* rename each public key according to the user's name, with a `.pub`
extension, like `sitaram.pub` or `john-smith.pub`. You can also use
@ -40,8 +40,11 @@ so here goes.
There's **no special syntax** for this -- just give read permission to a user
called `gitweb` or `daemon`! (This also means you can't have a normal user
with either of those two names, but I doubt that's a problem!). See the "faq,
tips, etc" document for easy ways to specify access for multiple repositories.
with either of those two names, but I doubt that's a problem!). See the [faq,
tips, etc][ss] document for easy ways to specify access for multiple
repositories.
[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd
Note that this does **not** install or configure gitweb/daemon -- that is a
one-time setup you must do separately. All this does is:

6
doc/3-faq-tips-etc.mkd
View file

@ -101,6 +101,8 @@ Apart from the big ones listed in the top level README, and subjective ones
like "better config file format", there are some small, but significant and
concrete, differences from gitosis.
<a name="simpler_syntax"></a>
#### simpler syntax
The basic syntax is simpler and cleaner but it goes beyond that: **you can
@ -192,6 +194,8 @@ access control for their own pieces. See
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
for details.
<a name="gwd"></a>
#### easier to specify gitweb/daemon access
Which of your repos should be accessible via plain HTTP or the `git://`
@ -308,6 +312,8 @@ The other parts of the log line are the name of the repo, the refname being
updated, the user updating it, and the refex pattern (from the config file)
that matched, in case you need to debug the config file itself.
<a name="multikeys"></a>
#### one user, many keys
I have a laptop and a desktop I need to access the server from. I have

105
doc/4-push-to-admin.mkd
View file

@ -1,105 +0,0 @@
# "push to admin" in gitolite
**WARNING: THIS DOCUMENT IS OBSOLETE. DO NOT USE. IT IS RETAINED ONLY FOR
HISTORICAL PURPOSES**. Gitolite now does "push-to-admin" by default, and does
it very easily and simply by front-loading the ssh problem. See the install
doc for details.
----
Gitosis's default mode of admin is by cloning and pushing the `gitosis-admin`
repo. I call this "push to admin". It's a very cool/cute feature, and I
loved it at first.
But it's a ***support nightmare***. Half the gitosis angst on `#git` is
because of this feature. Gitolite does not use or endorse this method for
people new to git, or ssh or (worse) both.
However, ***if*** you know git and ssh really, *really*, well and you know
what you're doing, this is a pretty nice thing to have -- does make life
easier, I admit. So, here is how to make PTA (hey nice acronym, just missing
an "I") work on gitolite as well.
Note:
* unlike the rest of gitolite, I can't help you with this unless you
convince me very quickly it's not a layer 8 problem :-)
* here's a test to see if you should use this feature: after reading this
document, think about how you would switch back and forth between the
normal method and push-to-admin. If you can't immediately see what you
would need to do, please don't use it :-)
The instructions are presented as shell commands; they should be fairly
obvious. All paths are from the default `~/.gitolite.rc`; if you changed any,
make the same changes below.
----
> **WARNING**: the "compilation" runs via a `post-update` hook. Which, by
> definition, runs *after* the push has successfully completed. As a
> result, a *compilation error* will be visible to the admin doing the `git
> push` but will not otherwise look like an error to client-side git (in
> terms of return codes, scripting, etc., or even the "git gui" if you
> happen to use that for pushing). So be sure to watch out for compile
> error messages on push when you do this.
----
#### server side setup
1. First, on the server, log on to the `git` userid, add a new repo called
`gitolite-admin` to the config file, give yourself `RW` or `RW+` rights to it,
and "compile":
cd ~/.gitolite
vim conf/gitolite.conf # add gitolite-admin repo, etc
src/gl-compile-conf
2. Now, if you look at the "compile" script, it has an *automatic* local commit
inside, just for safety, which kicks in every time you compile. This only
works if it finds a ".git" directory, and it was designed as an "automatic
backup/safety net" type of thing, in case I accidentally deleted the whole
config file or something.
We need to disable this, because now we have a *better* repo, one that is
manually pushed, and presumably has proper commit messages!
mv .git .disable.git # yeah it's a hack, sue me
3. Now the compile command created an empty, bare, "gitolite-admin" repo, so we
seed it with the current contents of the config and keys. (A note on the
`GIT_WORK_TREE` variable: I avoid setting these variables in the normal way
because I always forget to unset them later, and then when I `cd` to other
repos they play havoc with my git commands, so this is how I do it)
cd ~/repositories/gitolite-admin.git
GIT_WORK_TREE=$HOME/.gitolite git add conf/gitolite.conf keydir
GIT_WORK_TREE=$HOME/.gitolite git commit -am start
4. Now we have to setup the post-update hook for push-to-admin to work. The hook
should (1) make a forced checkout in the "live" config directory (which is
`~/.gitolite`), and (2) run the compile script.
`src/pta-hook.sh` has the code you need; just copy it to the right place with
the right name, change the first line if needed, and make it executable:
# (assuming pwd is still ~/repositories/gitolite-admin.git)
cp ~/.gitolite/src/pta-hook.sh hooks/post-update
# if you changed $GL_ADMINDIR in ~/.gitolite.conf, then edit the hooks
# and change the first line:
vim hooks/post-update
chmod +x hooks/post-update
----
#### client side setup
1. Now get to your workstation, and
git clone git@server:gitolite-admin.git
That's it, we're done. You're in gitosis land as far as this is concerned
now. So knock yourself out. Or lock yourself out... :-)

98
doc/5-delegation.mkd
View file

@ -5,14 +5,13 @@
### lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos,
exploiting commonalities wherever possible. (The example in the section
"simpler syntax" in [this page][ml] should give you an idea). As you can see,
it lets you specify bits and pieces of the access control separately -- i.e.,
*all* the access specs for a certain repo need not be together; they can be
scattered, which makes it easier to manage the sort of slice and dice needed
in that example.
exploiting commonalities wherever possible. (The example in [this
section][ss] should give you an idea). As you can see, it lets you specify
bits and pieces of the access control separately -- i.e., *all* the access
specs for a certain repo need not be together; they can be scattered, which
makes it easier to manage the sort of slice and dice needed in that example.
[ml]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd
[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#simpler_syntax
But eventually the config file will become too big. If you let only one
person have control, he could become a bottleneck. If you give it to multiple
@ -30,14 +29,16 @@ Delegation offers a way to do all that. Note that delegated admins cannot
create or remove users, not can they define new repos. They can only define
access control rules for a set of repos they have been given authority for.
### splitting up the config file into fragments
----
It's easier to show how it all works with an example instead of long
descriptions.
### splitting up the set of repos into groups
To start with, recall that gitolite allows you to specify **groups** (of users
or repos, same syntax). So the basic idea is that the main config file
(`~/.gitolite/conf/gitolite.conf` by default) will specify some repo groups:
(`conf/gitolite.conf` in your admin repo clone) will specify some repo groups:
# group your projects/repos however you want
@webbrowser_repos = firefox lynx
@ -47,71 +48,25 @@ or repos, same syntax). So the basic idea is that the main config file
# any other config as usual, including access control lines for any of the
# above projects or groups
Now just create these files (assuming default `$GL_ADMINDIR` location):
### delegating ownership of groups of repos
~/.gitolite/conf/fragments/webbrowser_repos.conf
~/.gitolite/conf/fragments/webserver_repos.conf
~/.gitolite/conf/fragments/malware_repos.conf
Within each of those files put in whatever access control rules you want for
the repos that are members of that group. Notice that the basenames of the
files must be exactly the same as the name of the corresponding repo group in
the main config file.
For instance, `~/.gitolite/conf/fragments/webbrowser_repos.conf` would only
contain access control for firefox and lynx. If it referenced any other repo
(say "storm") those lines would be ignored (and a warning message generated).
When you run the compile script (`src/gl-compile-conf`), the **net effect is
as if you appended the contents of all the "fragment" files, in alphabetical
order, to the bottom of the main file**.
(Except of course, while processing a fragment, it will ignore attempts to set
permissions for repos that are not members of the same-named "repo group").
And that's basically it, in the simplest usage.
["But WAIT, there's MORE!"][bwtm]
[bwtm]: http://en.wikipedia.org/wiki/Ed_Valenti#But_Wait.21_There.27s_More
### delegating ownership of fragments
Splitting up the file does help, but there's also that little security issue
-- anyone can make any change to any "fragment", unless you (once again) go
back to Unix permissions to keep them separate.
Fixing that requires using "push-to-admin", which is the default (and only)
method to make config changes in gitosis.
For a long time, I refused to make "push to admin" the default because it's a
support nightmare. Don't get me wrong -- it's a great feature, and I use it
myself, but the learning curve was too steep to make it *required*.
But eventually I figured out a way to front-load the darn ssh problem that
everyone on #git seemed to run up against, created a nice "easy install"
script, and made "push to admin" the default.
So now, you just add these lines to the main config file, assuming Alice is in
charge of all web browser development projects, Bob takes care of web servers,
and Mallory, as [tradition][abe] dictates, is in charge of malware ;-)
Once the repos are grouped, give each person charge of one or more groups.
For example, Alice may be in charge of all web browser development projects,
Bob takes care of web servers, and Mallory, as [tradition][abe] dictates, is
in charge of malware ;-)
[abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
# these 2 lines were probably present already
You do this by adding branches to the `gitolite-admin` repo:
# the admin repo access was probably like this to start with:
repo gitolite-admin
RW+ = sitaram
# now add these 3 lines
# now add these lines to the config for the admin repo
RW webbrowser_repos = alice
RW webserver_repos = bob
RW malware_repos = mallory
# you need these lines too -- they define what repos alice/bob/mallory are
# allowed to control
@webbrowser_repos = firefox lynx
@webserver_repos = apache nginx
@malware_repos = conficker storm
As you can see, **for each repo group** you want to delegate authority over,
there's a **branch with the same name** in the `gitolite-admin` repo. If you
have write access to that branch, you are allowed to define rules for repos in
@ -136,14 +91,7 @@ Here's how to use this in practice:
* Alice then commits and pushes this branch to the `gitolite-admin` repo
Naturally, a successful push invokes the post-update hook that you installed
(while setting up [push-to-admin][ptd]). Here's what it does:
* for each branch, say `br`, of the `gitolite-admin` repo, it checks if
there is a file called `conf/fragments/br.conf`
* if there is, it extracts it and copies it with the exact same name and
path, into the `$GL_ADMINDIR` directory (`~/.gitolite` by default)
After that, it runs the compile script, and things work the same as described
in the previous section.
Naturally, a successful push invokes the post-update hook that the admin repo
has, which eventually runs the compile script. The **net effect** is as if
you appended the contents of all the "fragment" files, in alphabetical order,
to the bottom of the main file.

4
src/00-easy-install.sh
View file

@ -283,6 +283,10 @@ then
then
[[ $quiet == -q ]] || ${VISUAL:-${EDITOR:-vi}} $tmpgli/.gitolite.rc
else
# MANUAL: if you're upgrading, read the instructions below and
# manually make sure your final ~/.gitolite.rc has both your existing
# customisations as well as any new variables that the new version of
# gitolite has introduced
prompt "" \
" looks like you're upgrading, and there are some new rc variables
that this version is expecting that your old rc file doesn't have.

17
src/gl-compile-conf
View file

@ -434,20 +434,3 @@ close $newkeys_fh or die "$ATTN close newkeys failed: $!\n";
system("cat $ENV{HOME}/.ssh/authorized_keys > $ENV{HOME}/.ssh/old_authkeys");
system("cat $ENV{HOME}/.ssh/new_authkeys > $ENV{HOME}/.ssh/authorized_keys");
system("rm $ENV{HOME}/.ssh/new_authkeys");
# if the gl admin directory (~/.gitolite) is itself a git repo, do an
# autocheckin. nothing fancy; this is a "just in case" type of thing.
wrap_chdir($GL_ADMINDIR);
if (-d ".git")
{
system("git add -A conf keydir"); # stage all operational data
# and if there are any
if (system("git diff --cached --quiet") )
{
open my $commit_ph, "|-", "git commit -F -"
or die "$ATTN open commit failed: $!\n";
print $commit_ph "keydir changed\n\n";
print $commit_ph `git diff --cached --name-status`;
close $commit_ph or die "$ATTN close commit failed: $!\n";
}
}