From 536e3198bf6a127a41aafdb79c5419da1d18b401 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Wed, 14 Oct 2009 14:09:34 +0530 Subject: [PATCH] doc fixes... - README: add a "what" section first, plus a few minor fixes - doc/5: - remove reference to obsolete ml branch URL; point it to the right place with the right section name - change text to reflect the fact that p-t-a is now the default! --- README.mkd | 33 ++++++++++++++++++++++++--------- doc/5-delegation.mkd | 39 ++++++++++++++++++++------------------- 2 files changed, 44 insertions(+), 28 deletions(-) diff --git a/README.mkd b/README.mkd index 7cbbaf3..81075cb 100644 --- a/README.mkd +++ b/README.mkd @@ -15,13 +15,28 @@ specifying who can and cannot *rewind* a given branch. In this document: + * what * why - * what's extra + * extra features * security * contact and license ---- +### what + +Gitolite allows a server to host many git repositories and provide access to +many developers, without having to give them real userids on the server. The +essential magic in doing this is ssh's pubkey access and the `authorized_keys` +file, and the inspiration was an older program called gitosis. + +Gitolite can restrict who can read from (clone/fetch) or write to (push) a +repository. It can also restrict who can push to what branch or tag, which is +very important in a corporate environment. Gitolite can be installed without +requiring root permissions, and with no additional software than git itself +and perl. It also has several other neat features described below and +elsewhere in the `doc/` directory. + ### why I have been using gitosis for a while, and have learnt a lot from it. But in @@ -33,15 +48,15 @@ a typical $DAYJOB setting, there are some issues: to help remotely, we never did manage to install it eventually) * you don't have root access, or the ability to add users (this is also true for people who have just one userid on a hosting provider) - * the most requested feature (see "what's new?") had to be written anyway + * the most requested feature (see below) had to be written anyway All of this pointed to a rewrite. In perl, naturally :-) -### what's extra +### extra features -**Per-branch permissions**. You will not believe how often I am asked this at -$DAYJOB. This is almost the single reason I started *thinking* about rolling -my own gitosis in the first place. +The most important feature I needed was **per-branch permissions**. This is +pretty much mandatory in a corporate environment, and is almost the single +reason I started *thinking* about rolling my own gitosis in the first place. It's not just "read-only" versus "read-write". Rewinding a branch (aka "non fast forward push") is potentially dangerous, but sometimes needed. So is @@ -53,8 +68,8 @@ Here're **some more features**. All of them are documented in detail somewhere in the `doc/` subdirectory. * simpler, yet far more powerful, config file syntax, including specifying - gitweb/daemon access. You'll need this power if you manage lots of users - + repos + combinations of access + gitweb/daemon access. You'll need this power if you manage lots of + users+repos+combinations of access * 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 @@ -62,7 +77,7 @@ somewhere in the `doc/` subdirectory. a synonym for "annotate" :-)] * "personal namespace" prefix for each dev * migration guide and simple converter for gitosis conf file - * "exclude" (or "deny" rights in the config file) -- this is the "rebel" + * "exclude" (or "deny") rights in the config file -- this is the "rebel" branch in the repository, and always will be ;-) ### security diff --git a/doc/5-delegation.mkd b/doc/5-delegation.mkd index 9924dc3..863268f 100644 --- a/doc/5-delegation.mkd +++ b/doc/5-delegation.mkd @@ -5,14 +5,14 @@ ### 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 under "simpler, more -powerful syntax" [here][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 +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. -[ml]: http://github.com/sitaramc/gitolite/blob/ml/update.mkd +[ml]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd 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 @@ -81,23 +81,24 @@ 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". +Fixing that requires using "push-to-admin", which is the default (and only) +method to make config changes in gitosis. -The page on [push-to-admin][ptd] explains clearly how to set it up. Unlike -gitosis, I refuse to make it 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 is too steep to make it *required*. +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*. -[ptd]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-push-to-admin.mkd +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, having setup push-to-admin, you 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 ;-) +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 - # you probably added these two lines while setting up push-to-admin + # these 2 lines were probably present already repo gitolite-admin RW+ = sitaram # now add these 3 lines @@ -111,10 +112,10 @@ of malware ;-) @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* in the `gitolite-admin` repo with the same name. If you +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 -that repo group.** +that repo group. In other words, we use gitolite's per-branch permissions to "enforce" the separation between the delegated configs!