-
Notifications
You must be signed in to change notification settings - Fork 15
/
cookbook.html
309 lines (246 loc) · 10 KB
/
cookbook.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
<head>
<title>gitolite cookbook</title>
<style>
body { background: #fff; text-color: #000; margin-left: 40px; font-size: 0.9em; font-family: sans-serif; max-width: 800px; }
h1 { background: #ffb; text-color: #000; margin-left: -30px; border-top: 5px solid #ccc; }
h2 { background: #ffb; text-color: #000; margin-left: -20px; border-top: 3px solid #ddd; }
h3 { background: #ffb; text-color: #000; margin-left: -10px; }
h4 { background: #ffb; text-color: #000; }
code { font-size: 1.1em; background: #ddf; text-color: #000; }
pre { margin-left: 2em; background: #ddf; text-color: #000; }
pre code { font-size: 1.1em; background: #ddf; text-color: #000; }
</style>
<style>
body{counter-reset: section}
h1{counter-reset: sub-section}
h2{counter-reset: composite}
h3{counter-reset: detail}
h1:before {
counter-increment: section;
content: counter(section) ". ";
}
h2:before {
counter-increment: sub-section;
content: counter(section) "." counter(sub-section) ". ";
}
h3:before {
counter-increment: composite;
content: counter(section) "." counter(sub-section) "." counter(composite) ". ";
}
h4:before {
counter-increment: detail;
content: counter(section) "." counter(sub-section) "." counter(composite) "." counter(detail) ". ";
}
</style>
</head>
<p style="text-align:center">
<a href="master-toc.html">master TOC</a>
|
<a href="index.html">main page</a>
|
<a href="gitolite.html">single-page</a>
|
<a href="index.html#license">license</a>
</p>
<p style="text-align:center">
<font color="gray">This is for gitolite "g3"; for older (v2.x) documentation click <a href="http://sitaramc.github.com/gitolite/g2/master-toc.html">here</a></font>
</p>
<h1>gitolite cookbook</h1>
<p>Documentation is meant to be as complete as possible, which means it attempts
to cover all situations and scenarios. That makes it harder to read.</p>
<p>However, if you make some assumptions, remove the rationale, justification,
exceptions and special cases, etc., and generally just say <em>what</em> is to be
done rather than explain <em>why</em>, many tasks can be described very easily.</p>
<p>Maybe this will help. If you run into problems, please check the main
documentation before asking for help.</p>
<hr />
<ul>
<li><a href="cookbook.html">gitolite cookbook</a>
<ul>
<li>administration
<ul>
<li>separating "key admin" from "repo admin"
</li>
</ul>
</li>
<li>access
<ul>
<li>looking up repo access from external tools
</li>
<li>providing access to external tools
</li>
</ul>
</li>
<li>hooks
<ul>
<li>adding you own update hooks
</li>
<li>adding other (non-update) hooks
</li>
<li>variation: managing the hooks from gitolite-admin
</li>
<li>variation: custom hooks only for some repos
</li>
</ul>
</li>
<li>moving stuff around
<ul>
<li>moving a gitolite install from one machine to another
</li>
</ul>
</li>
</ul>
</li>
</ul>
<hr />
<h2>administration</h2>
<h3>separating "key admin" from "repo admin"</h3>
<p>In gitolite, the person who controls the keys is the most powerful -- because
he can always add his own key in your name :-)</p>
<p>Traditionally, the same person also administers repos and permissions. But
sometimes you want to separate them. The following should work:</p>
<ul>
<li><p>put the following in conf/gitolite.conf:</p>
<pre><code>repo gitolite-admin
RW+ = key-manager repo-manager
<pre><code>RW+ VREF/NAME/ = key-manager
- VREF/NAME/keydir/ = @all
- VREF/NAME/conf/gitolite.conf = @all
</code></pre>
include "actual.conf"
</code></pre></li>
<li><p>then let the repo-manager manage everything through "actual.conf".</p></li>
</ul>
<h2>access</h2>
<h3>looking up repo access from external tools</h3>
<p>There are two supported interfaces for this, one in perl and one in shell.
Other languages should probably use the shell mode. (The shell mode has a
very convenient "batch" mode if you need to check many repos at once).</p>
<p><strong>Perl interface</strong>: A good intro to this, including a link to code, using
gitweb as an example can be found by looking for 'repo-specific authorisation
in gitweb' in the page on <a href="external.html">interfacing with external tools</a>. Some
notes:</p>
<ul>
<li>be sure to read the comments in the code to learn exactly how to adapt it
to your needs
</li>
<li>in place of the <code>can_read</code> function in that code, you can of course use
<code>can_write</code>. In fact, reading the comments in "Easy.pm" (look for it in
the source) shows you several other interesting tests you can make, like
<code>is_admin</code>, <code>in_group</code>, and <code>owns</code>.
</li>
</ul>
<p><strong>Shell interface</strong>: If you want to do this from shell, it's just even easier.
The same "Easy.pm" source contains comments that show shell equivalents for
each of the functions it exports, but here's a sample:</p>
<pre><code>if gitolite access -q reponame username W
then
...
</code></pre>
<p>You can even test for access to specific branches:</p>
<pre><code>if gitolite access -q reponame username W refs/heads/master
then
...
</code></pre>
<p>(note that you must use the full ref name; just 'master' won't do).</p>
<h3>providing access to external tools</h3>
<p>Giving external tools (like apache) access to gitolite repositories involves
making sure that the unix owner/group and permissions settings allow this.
This is all described in the UMASK section in the documentation on the <a href="rc.html">rc
file</a>, because that's the only setting that gitolite controls; every thing
else is pure Unix.</p>
<h2>hooks</h2>
<h3>adding you own update hooks</h3>
<p>You have some update hooks (for example crlf checking) that you want to
include in gitolite. Assuming the hook itself is tested and works as a normal
<strong>git</strong> update hook does (i.e., conforms to what <code>man githooks</code> says an update
hook should do), here's how to do this.</p>
<ol>
<li><p>add this line in the rc file, within the $RC block, if it's not already
present:</p>
<pre><code>LOCAL_CODE => "$ENV{HOME}/local",
</code></pre></li>
<li><p>copy your update hook to a subdirectory called VREF under this directory,
giving it a suitable name (let's say "crlf"):</p>
<pre><code># log on to server
cd $HOME
mkdir -p local/VREF
cp your-crlf-update-hook local/VREF/crlf
chmod +x local/VREF/crlf
</code></pre></li>
<li><p>in your gitolite-admin clone, edit conf/gitolite.conf and
add lines like this:</p>
<pre><code> - VREF/crlf = @all
</code></pre>
<p>to each repo that should have that "update" hook.</p>
<p>Alternatively, you can simply add this at the end of the
gitolite.conf file:</p>
<pre><code>repo @all
- VREF/crlf = @all
</code></pre>
<p>Either way, add/commit/push the change to the gitolite-admin repo.</p></li>
</ol>
<h3>adding other (non-update) hooks</h3>
<p>Say you want other hooks, like a post-receive hook. Here's how:</p>
<ol>
<li><p>add this line in the rc file, within the $RC block, if it's not already
present:</p>
<pre><code>LOCAL_CODE => "$ENV{HOME}/local",
</code></pre></li>
<li><p>put your hooks into that directory, in a sub-sub-directory called
"hooks/common":</p>
<pre><code># log on to server
cd $HOME
mkdir -p local/hooks/common
cp your-post-receive-hook local/hooks/common/post-receive
chmod +x local/hooks/common/post-receive
</code></pre></li>
<li><p>run <code>gitolite setup</code> to have the hooks propagate to existing repos (repos
created after this will get them anyway).</p></li>
</ol>
<h3>variation: managing the hooks from gitolite-admin</h3>
<p>If your gitolite admins already have shell access to the server, (i.e., you
don't distinguish between "someone who has shell on the server" and "someone
who only has push rights to the gitolite-admin repo"), you may like to put
these hooks also in the gitolite-admin repo for easier management.</p>
<p>You do almost the same thing, except for some changes:</p>
<ol>
<li><p>step 1 will change like so:</p>
<pre><code>LOCAL_CODE => "$ENV{HOME}/.gitolite/local",
</code></pre></li>
<li><p>step 2 will change in that you create these directories (local/VREF,
local/common/) in your gitolite-admin <em>clone</em>, not on the server.</p>
<p>After doing that, and copying the files there, you add, commit, and push.</p>
<p>Don't forget the 'chmod +x' !</p></li>
<li><p>Step 3 is the same for VREFs, but is not required for other hooks.</p></li>
</ol>
<h3>variation: custom hooks only for some repos</h3>
<p>If the hook is an update hook, you implement it as a VREF, and simply change
<code>repo @all</code> in step 3 in the update hook section above to <code>repo @repolist</code> or
whatever.</p>
<p>For the other hooks this is not possible. You have to either install the
hooks <em>manually</em> on the repos you want them on, or -- better still -- you do
something like this:</p>
<ol>
<li><p>in the conf file, add a groupname for the set of repos you want:</p>
<pre><code>@foo = list of repos
</code></pre></li>
<li><p>write your hook code with this at the top:</p>
<pre><code># check if @foo is in the list of groups of which $GL_REPO is a member
gitolite list-memberships -r $GL_REPO | grep -x @foo >/dev/null || exit 0
</code></pre></li>
<li><p>now add your hook as described in earlier steps</p></li>
</ol>
<h2>moving stuff around</h2>
<h3>moving a gitolite install from one machine to another</h3>
<p>Assuming you're not making a version change, this is what you need to do:</p>
<ul>
<li><p>clone the latest gitolite-admin repo to your workstation</p></li>
<li><p>install gitolite normally on the new machine, using the same public key
<em>and</em> name for the admin as on the old machine when running the <code>gitolite
setup -pk</code> command.</p></li>
<li><p>copy over your <code>~/.gitolite.rc</code> file from the old machine to the new</p></li>
<li><p>run <code>gitolite setup</code> (on the server)</p></li>
<li><p>go to the gitolite-admin clone you made in step 1, add or change the
remote to point to the new machine, and <code>git push -f</code></p></li>
</ul>