]>
Commit | Line | Data |
---|---|---|
cd67c8e0 JN |
1 | GIT web Interface (gitweb) Installation |
2 | ======================================= | |
3 | ||
4 | First you have to generate gitweb.cgi from gitweb.perl using | |
e3918594 MR |
5 | "make gitweb", then copy appropriate files (gitweb.cgi, gitweb.js, |
6 | gitweb.css, git-logo.png and git-favicon.png) to their destination. | |
7 | For example if git was (or is) installed with /usr prefix, you can do | |
cd67c8e0 | 8 | |
e3918594 | 9 | $ make prefix=/usr gitweb ;# as yourself |
cd67c8e0 JN |
10 | # cp gitweb/git* /var/www/cgi-bin/ ;# as root |
11 | ||
12 | Alternatively you can use autoconf generated ./configure script to | |
13 | set up path to git binaries (via config.mak.autogen), so you can write | |
14 | instead | |
15 | ||
16 | $ make configure ;# as yourself | |
17 | $ ./configure --prefix=/usr ;# as yourself | |
e3918594 | 18 | $ make gitweb ;# as yourself |
cd67c8e0 JN |
19 | # cp gitweb/git* /var/www/cgi-bin/ ;# as root |
20 | ||
21 | The above example assumes that your web server is configured to run | |
22 | [executable] files in /var/www/cgi-bin/ as server scripts (as CGI | |
23 | scripts). | |
24 | ||
25 | ||
26 | Build time configuration | |
27 | ------------------------ | |
28 | ||
29 | See also "How to configure gitweb for your local system" in README | |
30 | file for gitweb (in gitweb/README). | |
31 | ||
eae7a759 | 32 | - There are many configuration variables which affect building of |
cd67c8e0 | 33 | gitweb.cgi; see "default configuration for gitweb" section in main |
e3918594 | 34 | (top dir) Makefile, and instructions for building gitweb target. |
cd67c8e0 | 35 | |
eae7a759 RGS |
36 | One of the most important is where to find the git wrapper binary. Gitweb |
37 | tries to find the git wrapper at $(bindir)/git, so you have to set $bindir | |
cd67c8e0 | 38 | when building gitweb.cgi, or $prefix from which $bindir is derived. If |
eae7a759 | 39 | you build and install gitweb together with the rest of the git suite, |
cd67c8e0 JN |
40 | there should be no problems. Otherwise, if git was for example |
41 | installed from a binary package, you have to set $prefix (or $bindir) | |
42 | accordingly. | |
43 | ||
44 | - Another important issue is where are git repositories you want to make | |
eae7a759 | 45 | available to gitweb. By default gitweb searches for repositories under |
cd67c8e0 JN |
46 | /pub/git; if you want to have projects somewhere else, like /home/git, |
47 | use GITWEB_PROJECTROOT build configuration variable. | |
48 | ||
49 | By default all git repositories under projectroot are visible and | |
eae7a759 | 50 | available to gitweb. The list of projects is generated by default by |
cd67c8e0 JN |
51 | scanning the projectroot directory for git repositories. This can be |
52 | changed (configured) as described in "Gitweb repositories" section | |
53 | below. | |
54 | ||
eae7a759 RGS |
55 | Note that gitweb deals directly with the object database, and does not |
56 | need a working directory; the name of the project is the name of its | |
cd67c8e0 JN |
57 | repository object database, usually projectname.git for bare |
58 | repositories. If you want to provide gitweb access to non-bare (live) | |
eae7a759 | 59 | repositories, you can make projectname.git a symbolic link under |
cd67c8e0 JN |
60 | projectroot linking to projectname/.git (but it is just |
61 | a suggestion). | |
62 | ||
63 | - You can control where gitweb tries to find its main CSS style file, | |
a8ab675f MR |
64 | its JavaScript file, its favicon and logo with the GITWEB_CSS, GITWEB_JS |
65 | GITWEB_FAVICON and GITWEB_LOGO build configuration variables. By default | |
66 | gitweb tries to find them in the same directory as gitweb.cgi script. | |
cd67c8e0 | 67 | |
a8ab675f MR |
68 | - You can optionally generate minified versions of gitweb.js and gitweb.css |
69 | by defining the JSMIN and CSSMIN build configuration variables. By default | |
70 | the non-minified versions will be used. NOTE: if you enable this option, | |
71 | substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and | |
72 | gitweb.css in the help files. | |
0e6ce213 | 73 | |
cd67c8e0 JN |
74 | Build example |
75 | ~~~~~~~~~~~~~ | |
76 | ||
77 | - To install gitweb to /var/www/cgi-bin/gitweb/ when git wrapper | |
78 | is installed at /usr/local/bin/git and the repositories (projects) | |
79 | we want to display are under /home/local/scm, you can do | |
80 | ||
81 | make GITWEB_PROJECTROOT="/home/local/scm" \ | |
a8ab675f | 82 | GITWEB_JS="/gitweb/gitweb.js" \ |
cd67c8e0 JN |
83 | GITWEB_CSS="/gitweb/gitweb.css" \ |
84 | GITWEB_LOGO="/gitweb/git-logo.png" \ | |
85 | GITWEB_FAVICON="/gitweb/git-favicon.png" \ | |
86 | bindir=/usr/local/bin \ | |
e3918594 | 87 | gitweb |
cd67c8e0 | 88 | |
a8ab675f | 89 | cp -fv ~/git/gitweb/gitweb.{cgi,js,css} \ |
cd67c8e0 JN |
90 | ~/git/gitweb/git-{favicon,logo}.png \ |
91 | /var/www/cgi-bin/gitweb/ | |
92 | ||
93 | ||
94 | Gitweb config file | |
95 | ------------------ | |
96 | ||
97 | See also "Runtime gitweb configuration" section in README file | |
98 | for gitweb (in gitweb/README). | |
99 | ||
eae7a759 RGS |
100 | - You can configure gitweb further using the gitweb configuration file; |
101 | by default this is a file named gitweb_config.perl in the same place as | |
102 | gitweb.cgi script. You can control the default place for the config file | |
103 | using the GITWEB_CONFIG build configuration variable, and you can set it | |
104 | using the GITWEB_CONFIG environment variable. If this file does not | |
17a8b250 GP |
105 | exist, gitweb looks for a system-wide configuration file, normally |
106 | /etc/gitweb.conf. You can change the default using the | |
107 | GITWEB_CONFIG_SYSTEM build configuration variable, and override it | |
eae7a759 | 108 | through the GITWEB_CONFIG_SYSTEM environment variable. |
cd67c8e0 | 109 | |
eae7a759 | 110 | - The gitweb config file is a fragment of perl code. You can set variables |
cd67c8e0 JN |
111 | using "our $variable = value"; text from "#" character until the end |
112 | of a line is ignored. See perlsyn(1) for details. | |
113 | ||
114 | See the top of gitweb.perl file for examples of customizable options. | |
115 | ||
52c813f2 JN |
116 | Config file example |
117 | ~~~~~~~~~~~~~~~~~~~ | |
cd67c8e0 | 118 | |
52c813f2 JN |
119 | To enable blame, pickaxe search, and snapshot support, while allowing |
120 | individual projects to turn them off, put the following in your | |
121 | GITWEB_CONFIG file: | |
122 | ||
123 | $feature{'blame'}{'default'} = [1]; | |
124 | $feature{'blame'}{'override'} = 1; | |
125 | ||
126 | $feature{'pickaxe'}{'default'} = [1]; | |
127 | $feature{'pickaxe'}{'override'} = 1; | |
128 | ||
1e3a2eb6 | 129 | $feature{'snapshot'}{'default'} = ['zip', 'tgz']; |
52c813f2 JN |
130 | $feature{'snapshot'}{'override'} = 1; |
131 | ||
b4c07792 MR |
132 | If you allow overriding for the snapshot feature, you can specify which |
133 | snapshot formats are globally disabled. You can also add any command line | |
134 | options you want (such as setting the compression level). For instance, | |
135 | you can disable Zip compressed snapshots and set GZip to run at level 6 by | |
136 | adding the following lines to your $GITWEB_CONFIG: | |
137 | ||
138 | $known_snapshot_formats{'zip'}{'disabled'} = 1; | |
139 | $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; | |
140 | ||
52c813f2 JN |
141 | |
142 | Gitweb repositories | |
143 | ------------------- | |
cd67c8e0 JN |
144 | |
145 | - By default all git repositories under projectroot are visible and | |
eae7a759 | 146 | available to gitweb. The list of projects is generated by default by |
cd67c8e0 JN |
147 | scanning the projectroot directory for git repositories (for object |
148 | databases to be more exact). | |
149 | ||
eae7a759 | 150 | You can provide a pre-generated list of [visible] repositories, |
cd67c8e0 | 151 | together with information about their owners (the project ownership |
eae7a759 RGS |
152 | defaults to the owner of the repository directory otherwise), by setting |
153 | the GITWEB_LIST build configuration variable (or the $projects_list | |
154 | variable in the gitweb config file) to point to a plain file. | |
155 | ||
156 | Each line of the projects list file should consist of the url-encoded path | |
157 | to the project repository database (relative to projectroot), followed | |
158 | by the url-encoded project owner on the same line (separated by a space). | |
159 | Spaces in both project path and project owner have to be encoded as either | |
160 | '%20' or '+'. | |
161 | ||
e67c9e39 JN |
162 | Other characters that have to be url-encoded, i.e. replaced by '%' |
163 | followed by two-digit character number in octal, are: other whitespace | |
164 | characters (because they are field separator in a record), plus sign '+' | |
165 | (because it can be used as replacement for spaces), and percent sign '%' | |
166 | (which is used for encoding / escaping). | |
167 | ||
eae7a759 RGS |
168 | You can generate the projects list index file using the project_index |
169 | action (the 'TXT' link on projects list page) directly from gitweb. | |
170 | ||
171 | - By default, even if a project is not visible on projects list page, you | |
172 | can view it nevertheless by hand-crafting a gitweb URL. You can set the | |
173 | GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export | |
174 | variable in the gitweb config file) to only allow viewing of | |
cd67c8e0 JN |
175 | repositories also shown on the overview page. |
176 | ||
177 | - Alternatively, you can configure gitweb to only list and allow | |
eae7a759 RGS |
178 | viewing of the explicitly exported repositories, via the |
179 | GITWEB_EXPORT_OK build configuration variable (or the $export_ok | |
cd67c8e0 | 180 | variable in gitweb config file). If it evaluates to true, gitweb |
eae7a759 RGS |
181 | shows repositories only if this file exists in its object database |
182 | (if directory has the magic file named $export_ok). | |
cd67c8e0 | 183 | |
dd7f5f10 AG |
184 | - Finally, it is possible to specify an arbitrary perl subroutine that |
185 | will be called for each project to determine if it can be exported. | |
186 | The subroutine receives an absolute path to the project as its only | |
187 | parameter. | |
188 | ||
189 | For example, if you use mod_perl to run the script, and have dumb | |
190 | http protocol authentication configured for your repositories, you | |
191 | can use the following hook to allow access only if the user is | |
192 | authorized to read the files: | |
193 | ||
194 | $export_auth_hook = sub { | |
195 | use Apache2::SubRequest (); | |
196 | use Apache2::Const -compile => qw(HTTP_OK); | |
197 | my $path = "$_[0]/HEAD"; | |
198 | my $r = Apache2::RequestUtil->request; | |
199 | my $sub = $r->lookup_file($path); | |
200 | return $sub->filename eq $path | |
201 | && $sub->status == Apache2::Const::HTTP_OK; | |
202 | }; | |
203 | ||
204 | ||
52c813f2 JN |
205 | Generating projects list using gitweb |
206 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
207 | ||
208 | We assume that GITWEB_CONFIG has its default Makefile value, namely | |
209 | gitweb_config.perl. Put the following in gitweb_make_index.perl file: | |
210 | ||
211 | $GITWEB_CONFIG = "gitweb_config.perl"; | |
212 | do $GITWEB_CONFIG if -e $GITWEB_CONFIG; | |
213 | ||
214 | $projects_list = $projectroot; | |
215 | ||
216 | Then create the following script to get list of project in the format | |
217 | suitable for GITWEB_LIST build configuration variable (or | |
218 | $projects_list variable in gitweb config): | |
219 | ||
220 | #!/bin/sh | |
221 | ||
222 | export GITWEB_CONFIG="gitweb_make_index.perl" | |
223 | export GATEWAY_INTERFACE="CGI/1.1" | |
224 | export HTTP_ACCEPT="*/*" | |
225 | export REQUEST_METHOD="GET" | |
226 | export QUERY_STRING="a=project_index" | |
227 | ||
228 | perl -- /var/www/cgi-bin/gitweb.cgi | |
229 | ||
cd67c8e0 JN |
230 | |
231 | Requirements | |
232 | ------------ | |
233 | ||
234 | - Core git tools | |
235 | - Perl | |
236 | - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename. | |
237 | - web server | |
238 | ||
239 | ||
240 | Example web server configuration | |
241 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
242 | ||
243 | See also "Webserver configuration" section in README file for gitweb | |
244 | (in gitweb/README). | |
245 | ||
246 | ||
247 | - Apache2, gitweb installed as CGI script, | |
248 | under /var/www/cgi-bin/ | |
249 | ||
250 | ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" | |
251 | ||
252 | <Directory "/var/www/cgi-bin"> | |
253 | Options Indexes FollowSymlinks ExecCGI | |
254 | AllowOverride None | |
255 | Order allow,deny | |
256 | Allow from all | |
257 | </Directory> | |
258 | ||
259 | - Apache2, gitweb installed as mod_perl legacy script, | |
260 | under /var/www/perl/ | |
261 | ||
262 | Alias /perl "/var/www/perl" | |
263 | ||
264 | <Directory "/var/www/perl"> | |
265 | SetHandler perl-script | |
266 | PerlResponseHandler ModPerl::Registry | |
267 | PerlOptions +ParseHeaders | |
268 | Options Indexes FollowSymlinks +ExecCGI | |
269 | AllowOverride None | |
270 | Order allow,deny | |
271 | Allow from all | |
272 | </Directory> |