doc/src: major doc/help text revamp
also removed some dead code from compile (pre PTA days)
This commit is contained in:
parent
5108aedd48
commit
92d5062ad0
20
README.mkd
20
README.mkd
|
@ -1,10 +1,8 @@
|
||||||
# gitolite
|
# gitolite
|
||||||
|
|
||||||
> [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
|
> [Update 2009-10-28: apart from all the nifty new features, there's now an
|
||||||
> please read if upgrading gitolite]
|
> "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
|
||||||
> [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
|
|
||||||
> document in the doc directory for details]
|
> 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
|
something in between allowing anyone to do it (the default) and disabling it
|
||||||
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
|
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
|
||||||
|
|
||||||
Here're **some more features**. All of them are documented in detail
|
Here're **some more features**. All of them, and more, are documented in
|
||||||
somewhere in the `doc/` subdirectory.
|
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
|
* simpler, yet far more powerful, config file syntax, including specifying
|
||||||
gitweb/daemon access. You'll need this power if you manage lots of
|
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
|
* config file syntax gets checked upfront, and much more thoroughly
|
||||||
* if your requirements are still too complex, you can split up the config
|
* if your requirements are still too complex, you can split up the config
|
||||||
file and delegate authority over parts of it
|
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
|
* more comprehensive logging [aka: management does not think "blame" is just
|
||||||
a synonym for "annotate" :-)]
|
a synonym for "annotate" :-)]
|
||||||
* "personal namespace" prefix for each dev
|
* "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
|
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
|
consider this a "security" program, albeit a very modest one. The code is
|
||||||
very small and easily reviewable -- the 2 programs that actually control
|
very small and easily reviewable -- the 2 programs that actually control
|
||||||
access when a user logs in total about 200 lines of code (about
|
access when a user logs in total about 220 lines of code (about 90 lines
|
||||||
80 lines according to "sloccount").
|
according to "sloccount").
|
||||||
|
|
||||||
For the first person to find a security hole in it, defined as allowing a
|
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,
|
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
|
||||||
|
|
|
@ -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
|
# Please DO NOT change these three paths
|
||||||
# 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.
|
|
||||||
|
|
||||||
$GL_CONF="$GL_ADMINDIR/conf/gitolite.conf";
|
$GL_CONF="$GL_ADMINDIR/conf/gitolite.conf";
|
||||||
$GL_KEYDIR="$GL_ADMINDIR/keydir";
|
$GL_KEYDIR="$GL_ADMINDIR/keydir";
|
||||||
|
|
|
@ -1,9 +1,12 @@
|
||||||
# installing gitolite
|
# installing gitolite
|
||||||
|
|
||||||
This document tells you how to install gitolite. After the install is done,
|
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.
|
slightly more manual process. Both are explained here.
|
||||||
|
|
||||||
In this document:
|
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
|
server!** It will take care of all the server side work, *and* get you
|
||||||
"push-to-admin" too :-) In short, it does **everything**!
|
"push-to-admin" too :-) In short, it does **everything**!
|
||||||
|
|
||||||
Assumptions:
|
Assumptions/pre-requisites:
|
||||||
|
|
||||||
* you have a server to host gitolite
|
* you have a server to host gitolite
|
||||||
* git is installed on that server (and so is perl)
|
* git is installed on that server (and so is perl)
|
||||||
* you have a userid on that server
|
* 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
|
* (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`)
|
new keypair if needed, then run `ssh-copy-id user@host`)
|
||||||
* you have a clone or an archive of gitolite somewhere on your workstation
|
* 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
|
#### disadvantages
|
||||||
|
|
||||||
* has been tested only with Linux
|
* need a recent bash
|
||||||
|
|
||||||
### manual install
|
### manual install
|
||||||
|
|
||||||
If for some reason you cannot use the easy-install method, (for example,
|
If you don't have bash, it's not very complicated to do it manually. Just
|
||||||
you're on a non-Linux machine), it's not very complicated. Just open the file
|
open the file `src/00-easy-install.sh` in a nice, syntax coloring, text
|
||||||
`src/00-easy-install.sh` in a nice, syntax coloring, text editor, and follow
|
editor, and follow the instructions marked "MANUAL" :-)
|
||||||
the instructions marked "MANUAL" :-)
|
|
||||||
|
|
||||||
### other notes
|
### other notes
|
||||||
|
|
||||||
* If you edit `~/.gitolite.rc` and change any paths, be sure to keep the
|
* if you run `src/00-easy-install.sh` without the `-q` option, you will be
|
||||||
perl syntax -- you *don't* have to know perl to do so, it's fairly easy to
|
given a chance to edit `~/.gitolite.rc`. You can change any options (such
|
||||||
guess in this limited case
|
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
|
||||||
* the config file is (by default) at `~/.gitolite/conf/gitolite.conf`,
|
limited case.
|
||||||
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
|
|
||||||
|
|
||||||
### next steps
|
### 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.
|
||||||
|
|
|
@ -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
|
|
|
@ -36,8 +36,11 @@ Here's how we migrated my work repos:
|
||||||
|
|
||||||
Now, log off the server and get back to the client:
|
Now, log off the server and get back to the client:
|
||||||
|
|
||||||
1. follow instructions to install gitolite; see install document. Make sure
|
[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
|
||||||
that you **don't** change the default path for `$REPO_BASE`!
|
|
||||||
|
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
|
2. **convert** your gitosis config file. Substitute the path for your
|
||||||
gitosis-admin clone in `$GSAC` below, and similarly 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
|
cp $GSAC/keydir/* $GLAC/keydir
|
||||||
|
|
||||||
4. **Important: expand any multi-key files you may have**. See the "faq,
|
4. **Important: expand any multi-key files you may have**. [Here][mk]'s an
|
||||||
tips, etc" document in the doc directory for an explanation of what
|
explanation of what multi-keys are, how gitosis does them and how gitolite
|
||||||
multi-keys are, how gitosis does them and how gitolite does it
|
does it differently.
|
||||||
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
|
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
|
copy-paste it into your xterm after "cd"-ing to your gitolite-admin repo
|
||||||
|
|
|
@ -14,9 +14,9 @@ Please read on to see how to do this correctly.
|
||||||
#### adding users and repos
|
#### adding users and repos
|
||||||
|
|
||||||
* ask each user who will get access to send you a public key. See other
|
* ask each user who will get access to send you a public key. See other
|
||||||
sources (for example
|
sources (for example [here][genpub]) for how to do this
|
||||||
[here](http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key))
|
|
||||||
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`
|
* 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
|
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
|
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
|
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,
|
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.
|
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
|
Note that this does **not** install or configure gitweb/daemon -- that is a
|
||||||
one-time setup you must do separately. All this does is:
|
one-time setup you must do separately. All this does is:
|
||||||
|
|
|
@ -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
|
like "better config file format", there are some small, but significant and
|
||||||
concrete, differences from gitosis.
|
concrete, differences from gitosis.
|
||||||
|
|
||||||
|
<a name="simpler_syntax"></a>
|
||||||
|
|
||||||
#### simpler syntax
|
#### simpler syntax
|
||||||
|
|
||||||
The basic syntax is simpler and cleaner but it goes beyond that: **you can
|
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)
|
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
|
<a name="gwd"></a>
|
||||||
|
|
||||||
#### easier to specify gitweb/daemon access
|
#### easier to specify gitweb/daemon access
|
||||||
|
|
||||||
Which of your repos should be accessible via plain HTTP or the `git://`
|
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)
|
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.
|
that matched, in case you need to debug the config file itself.
|
||||||
|
|
||||||
|
<a name="multikeys"></a>
|
||||||
|
|
||||||
#### one user, many keys
|
#### one user, many keys
|
||||||
|
|
||||||
I have a laptop and a desktop I need to access the server from. I have
|
I have a laptop and a desktop I need to access the server from. I have
|
||||||
|
|
|
@ -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... :-)
|
|
|
@ -5,14 +5,13 @@
|
||||||
### lots of repos, lots of users
|
### lots of repos, lots of users
|
||||||
|
|
||||||
Gitolite tries to make it easy to manage access to lots of users and repos,
|
Gitolite tries to make it easy to manage access to lots of users and repos,
|
||||||
exploiting commonalities wherever possible. (The example in the section
|
exploiting commonalities wherever possible. (The example in [this
|
||||||
"simpler syntax" in [this page][ml] should give you an idea). As you can see,
|
section][ss] should give you an idea). As you can see, it lets you specify
|
||||||
it lets you specify bits and pieces of the access control separately -- i.e.,
|
bits and pieces of the access control separately -- i.e., *all* the access
|
||||||
*all* the access specs for a certain repo need not be together; they can be
|
specs for a certain repo need not be together; they can be scattered, which
|
||||||
scattered, which makes it easier to manage the sort of slice and dice needed
|
makes it easier to manage the sort of slice and dice needed in that example.
|
||||||
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
|
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
|
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
|
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.
|
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
|
It's easier to show how it all works with an example instead of long
|
||||||
descriptions.
|
descriptions.
|
||||||
|
|
||||||
|
### splitting up the set of repos into groups
|
||||||
|
|
||||||
To start with, recall that gitolite allows you to specify **groups** (of users
|
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
|
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
|
# group your projects/repos however you want
|
||||||
@webbrowser_repos = firefox lynx
|
@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
|
# any other config as usual, including access control lines for any of the
|
||||||
# above projects or groups
|
# 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
|
Once the repos are grouped, give each person charge of one or more groups.
|
||||||
~/.gitolite/conf/fragments/webserver_repos.conf
|
For example, Alice may be in charge of all web browser development projects,
|
||||||
~/.gitolite/conf/fragments/malware_repos.conf
|
Bob takes care of web servers, and Mallory, as [tradition][abe] dictates, is
|
||||||
|
in charge of malware ;-)
|
||||||
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 ;-)
|
|
||||||
|
|
||||||
[abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
|
[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
|
repo gitolite-admin
|
||||||
RW+ = sitaram
|
RW+ = sitaram
|
||||||
# now add these 3 lines
|
# now add these lines to the config for the admin repo
|
||||||
RW webbrowser_repos = alice
|
RW webbrowser_repos = alice
|
||||||
RW webserver_repos = bob
|
RW webserver_repos = bob
|
||||||
RW malware_repos = mallory
|
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,
|
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
|
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
|
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
|
* Alice then commits and pushes this branch to the `gitolite-admin` repo
|
||||||
|
|
||||||
Naturally, a successful push invokes the post-update hook that you installed
|
Naturally, a successful push invokes the post-update hook that the admin repo
|
||||||
(while setting up [push-to-admin][ptd]). Here's what it does:
|
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,
|
||||||
* for each branch, say `br`, of the `gitolite-admin` repo, it checks if
|
to the bottom of the main file.
|
||||||
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.
|
|
||||||
|
|
|
@ -283,6 +283,10 @@ then
|
||||||
then
|
then
|
||||||
[[ $quiet == -q ]] || ${VISUAL:-${EDITOR:-vi}} $tmpgli/.gitolite.rc
|
[[ $quiet == -q ]] || ${VISUAL:-${EDITOR:-vi}} $tmpgli/.gitolite.rc
|
||||||
else
|
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 "" \
|
prompt "" \
|
||||||
" looks like you're upgrading, and there are some new rc variables
|
" 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.
|
that this version is expecting that your old rc file doesn't have.
|
||||||
|
|
|
@ -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/authorized_keys > $ENV{HOME}/.ssh/old_authkeys");
|
||||||
system("cat $ENV{HOME}/.ssh/new_authkeys > $ENV{HOME}/.ssh/authorized_keys");
|
system("cat $ENV{HOME}/.ssh/new_authkeys > $ENV{HOME}/.ssh/authorized_keys");
|
||||||
system("rm $ENV{HOME}/.ssh/new_authkeys");
|
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";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
Loading…
Reference in a new issue