Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

progit chapter changes to be closer to submitted version

  • Loading branch information...
commit d39a172077b4dedef6e4ab78b25a3d97f28fee46 1 parent ac35140
Sitaram Chamarty authored October 13, 2012

Showing 1 changed file with 13 additions and 24 deletions. Show diff stats Hide diff stats

  1. 37  progit.mkd
37  progit.mkd
Source Rendered
... ...
@@ -1,10 +1,13 @@
1  
-# (expanded version of the gitolite chapter in the progit book)
  1
+# (master copy/latest version of the gitolite chapter in the progit book)
2 2
 
3 3
 ## Gitolite ##
4 4
 
5  
-[Update 2012-04-10]: This page has been completely rewritten for gitolite version 3, informally called "g3".  G3 is a *total* rewrite of gitolite to push a lot more features away from "core", give the core a bunch of extension mechanisms, and finally have much better shell and perl APIs to bring all this together.
  5
+This section serves as a quick introduction to gitolite, and provides basic installation and setup instructions.  It cannot, however, replace the enormous amount of [documentation][gltoc] that gitolite comes with.
6 6
 
7  
-Git has become very popular in corporate environments, which tend to have some additional requirements in terms of access control.  Gitolite was originally created to help with those requirements, but it turns out that it's equally useful in the open source world: the Fedora Project controls access to their package management repositories (over 10,000 of them!) using gitolite, and this is probably the largest gitolite installation anywhere too.  KDE, and kernel.org, are other very high-profile users of gitolite.
  7
+[gldpg]: http://sitaramc.github.com/gitolite/progit.html
  8
+[gltoc]: http://sitaramc.github.com/gitolite/master-toc.html
  9
+
  10
+Gitolite is an authorisation layer on top of git, relying on sshd or httpd for authentication.  (Recap: authentication is identifying who the user is, authorisation is deciding if he is allowed to do what he is attempting to).
8 11
 
9 12
 Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository.  That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
10 13
 
@@ -12,7 +15,7 @@ Gitolite allows you to specify permissions not just by repository, but also by b
12 15
 
13 16
 Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it.  You need an account on a Unix server of some kind.  You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed.  In the examples below, we will use the `git` account on a host called `gitserver`.
14 17
 
15  
-Gitolite is somewhat unusual as far as "server" software goes -- access is via ssh, and so every userid on the server is a potential "gitolite host".  Gitolite is at present best installed manually, as the "g3" version does not yet have RPM/DEB support from distros.  We will describe the simplest install method in this article; for the other methods please see the documentation.
  18
+Gitolite is somewhat unusual as far as "server" software goes -- access is via ssh, and so every userid on the server is a potential "gitolite host".  We will describe the simplest install method in this article; for the other methods please see the documentation.
16 19
 
17 20
 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:
18 21
 
@@ -24,7 +27,7 @@ To begin, create a user called `git` on your server and login to this user.  Cop
24 27
 
25 28
 Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
26 29
 
27  
-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.
  30
+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.
28 31
 
29 32
 ### Customising the Install ###
30 33
 
@@ -32,7 +35,7 @@ While the default, quick, install works for most people, there are some ways to
32 35
 
33 36
 ### Config File and Access Control Rules ###
34 37
 
35  
-Once the install is done, you switch to the `gitolite-admin` repository (placed in your HOME directory) and poke around to see what you got:
  38
+Once the install is done, you switch to the `gitolite-admin` clone you just made on your workstation, and poke around to see what you got:
36 39
 
37 40
 	$ cd ~/gitolite-admin/
38 41
 	$ ls
@@ -50,6 +53,8 @@ Once the install is done, you switch to the `gitolite-admin` repository (placed
50 53
 
51 54
 Notice that "sitaram" (the name of the pubkey in the gl-setup command you used earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
52 55
 
  56
+Adding users is easy.  To add a user called "alice", obtain her public key, name it "alice.pub", and put it in the "keydir" directory of the clone of the gitolite-admin repo you just made on your workstation.  Add, commit, and push the change, and the user has been added.
  57
+
53 58
 The config file syntax for gitolite is [well documented][conf], so we'll only mention some highlights here.
54 59
 
55 60
 You can group users or repos for convenience.  The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
@@ -89,7 +94,7 @@ The second level, applicable only to "write" access, is by branch or tag within
89 94
 
90 95
 ### Advanced Access Control with "deny" rules ###
91 96
 
92  
-So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`.  However, gitolite allows another permission: `-`, standing for "deny".  This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
  97
+So far, we've only seen permissions to be one of `R`, `RW`, or `RW+`.  However, gitolite allows another permission: `-`, standing for "deny".  This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
93 98
 
94 99
 Let us say, in the situation above, we want engineers to be able to rewind any branch *except* master and integ.  Here's how to do that:
95 100
 
@@ -99,20 +104,6 @@ Let us say, in the situation above, we want engineers to be able to rewind any b
99 104
 
100 105
 Again, you simply follow the rules top down until you hit a match for your access mode, or a deny.  Non-rewind push to master or integ is allowed by the first rule.  A rewind push to those refs does not match the first rule, drops down to the second, and is therefore denied.  Any push (rewind or non-rewind) to refs other than master or integ won't match the first two rules anyway, and the third rule allows it.
101 106
 
102  
-You can also use deny rules to hide specific repos from people (or gitweb, or git-daemon, etc.), when you have otherwise allowed them access to *all* repos.  For example, a server containing open source repos may nevertheless wish to hide the special 'gitolite-admin' repo from gitweb, even though all the other repos can be made visible:
103  
-
104  
-	    repo gitolite-admin
105  
-		-   =   gitweb daemon
106  
-		[... other access rules ...]
107  
-		option deny-rules = 1
108  
-                # remember this is for gitolite "g3"; the older gitolite had a
109  
-                # different syntax
110  
-
111  
-	    repo @all
112  
-		R   =   gitweb daemon
113  
-
114  
-[This][deny-rules] page has more details.
115  
-
116 107
 ### Restricting pushes by files changed ###
117 108
 
118 109
 In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch.  For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*.  You can tell gitolite:
@@ -146,7 +137,7 @@ We'll round off this discussion with a sampling of other features, all of which,
146 137
 
147 138
 **Access rights reporting**: Another convenient feature is what happens when you try and just ssh to the server.  Gitolite shows you what repos you have access to, and what that access may be.  Here's an example:
148 139
 
149  
-        hello sitaram, this is git@git running gitolite3 v0.02-15-g1db50f4 on git 1.7.4.4
  140
+        hello sitaram, this is git@git running gitolite3 v3.01-18-g9609868 on git 1.7.4.4
150 141
 
151 142
              R     anu-wsd
152 143
              R     entrans
@@ -159,5 +150,3 @@ We'll round off this discussion with a sampling of other features, all of which,
159 150
 **Delegation**: For really large installations, you can delegate responsibility for groups of repositories to various people and have them manage those pieces independently.  This reduces the load on the main admin, and makes him less of a bottleneck.  See [here][deleg] for more on this.
160 151
 
161 152
 **Mirroring**: Gitolite can help you maintain multiple [mirrors][mirroring], and switch between them easily if the primary server goes down.
162  
-
163  
-[progit]: http://sitaramc.github.com/gitolite/progit.html

0 notes on commit d39a172

Please sign in to comment.
Something went wrong with that request. Please try again.