]>
Commit | Line | Data |
---|---|---|
07ea4df2 JN |
1 | gitweb(1) |
2 | ========= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitweb - Git web interface (web frontend to Git repositories) | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
2de9b711 | 10 | To get started with gitweb, run linkgit:git-instaweb[1] from a Git repository. |
07ea4df2 JN |
11 | This would configure and start your web server, and run web browser pointing to |
12 | gitweb. | |
13 | ||
14 | ||
15 | DESCRIPTION | |
16 | ----------- | |
2de9b711 | 17 | Gitweb provides a web interface to Git repositories. Its features include: |
07ea4df2 JN |
18 | |
19 | * Viewing multiple Git repositories with common root. | |
20 | * Browsing every revision of the repository. | |
21 | * Viewing the contents of files in the repository at any revision. | |
22 | * Viewing the revision log of branches, history of files and directories, | |
23 | see what was changed when, by who. | |
24 | * Viewing the blame/annotation details of any file (if enabled). | |
25 | * Generating RSS and Atom feeds of commits, for any branch. | |
26 | The feeds are auto-discoverable in modern web browsers. | |
27 | * Viewing everything that was changed in a revision, and step through | |
28 | revisions one at a time, viewing the history of the repository. | |
29 | * Finding commits which commit messages matches given search term. | |
30 | ||
31 | See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or | |
32 | http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, | |
33 | browsed using gitweb itself. | |
34 | ||
35 | ||
36 | CONFIGURATION | |
37 | ------------- | |
38 | Various aspects of gitweb's behavior can be controlled through the configuration | |
39 | file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] | |
40 | for details. | |
41 | ||
42 | Repositories | |
43 | ~~~~~~~~~~~~ | |
44 | Gitweb can show information from one or more Git repositories. These | |
45 | repositories have to be all on local filesystem, and have to share common | |
46 | repository root, i.e. be all under a single parent repository (but see also | |
47 | "Advanced web server setup" section, "Webserver configuration with multiple | |
48 | projects' root" subsection). | |
49 | ||
50 | ----------------------------------------------------------------------- | |
51 | our $projectroot = '/path/to/parent/directory'; | |
52 | ----------------------------------------------------------------------- | |
53 | ||
54 | The default value for `$projectroot` is '/pub/git'. You can change it during | |
55 | building gitweb via `GITWEB_PROJECTROOT` build configuration variable. | |
56 | ||
2de9b711 | 57 | By default all Git repositories under `$projectroot` are visible and available |
07ea4df2 | 58 | to gitweb. The list of projects is generated by default by scanning the |
2de9b711 | 59 | `$projectroot` directory for Git repositories (for object databases to be |
07ea4df2 JN |
60 | more exact; gitweb is not interested in a working area, and is best suited |
61 | to showing "bare" repositories). | |
62 | ||
c32c9591 | 63 | The name of the repository in gitweb is the path to its `$GIT_DIR` (its object |
07ea4df2 JN |
64 | database) relative to `$projectroot`. Therefore the repository $repo can be |
65 | found at "$projectroot/$repo". | |
66 | ||
67 | ||
68 | Projects list file format | |
69 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
70 | Instead of having gitweb find repositories by scanning filesystem | |
71 | starting from $projectroot, you can provide a pre-generated list of | |
72 | visible projects by setting `$projects_list` to point to a plain text | |
73 | file with a list of projects (with some additional info). | |
74 | ||
75 | This file uses the following format: | |
76 | ||
77 | * One record (for project / repository) per line; does not support line | |
78 | continuation (newline escaping). | |
79 | ||
80 | * Leading and trailing whitespace are ignored. | |
81 | ||
82 | * Whitespace separated fields; any run of whitespace can be used as field | |
83 | separator (rules for Perl's "`split(" ", $line)`"). | |
84 | ||
85 | * Fields use modified URI encoding, defined in RFC 3986, section 2.1 | |
86 | (Percent-Encoding), or rather "Query string encoding" (see | |
2df85669 | 87 | http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference |
07ea4df2 JN |
88 | being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be |
89 | also percent-encoded). | |
90 | + | |
91 | Reserved characters are: "%" (used for encoding), "{plus}" (can be used to | |
92 | encode SPACE), all whitespace characters as defined in Perl, including SP, | |
93 | TAB and LF, (used to separate fields in a record). | |
94 | ||
95 | * Currently recognized fields are: | |
96 | <repository path>:: | |
97 | path to repository GIT_DIR, relative to `$projectroot` | |
98 | <repository owner>:: | |
99 | displayed as repository owner, preferably full name, or email, | |
100 | or both | |
101 | ||
102 | You can generate the projects list index file using the project_index action | |
103 | (the 'TXT' link on projects list page) directly from gitweb; see also | |
104 | "Generating projects list using gitweb" section below. | |
105 | ||
106 | Example contents: | |
107 | ----------------------------------------------------------------------- | |
108 | foo.git Joe+R+Hacker+<joe@example.com> | |
109 | foo/bar.git O+W+Ner+<owner@example.org> | |
110 | ----------------------------------------------------------------------- | |
111 | ||
112 | ||
113 | By default this file controls only which projects are *visible* on projects | |
2de9b711 | 114 | list page (note that entries that do not point to correctly recognized Git |
07ea4df2 JN |
115 | repositories won't be displayed by gitweb). Even if a project is not |
116 | visible on projects list page, you can view it nevertheless by hand-crafting | |
117 | a gitweb URL. By setting `$strict_export` configuration variable (see | |
118 | linkgit:gitweb.conf[5]) to true value you can allow viewing only of | |
119 | repositories also shown on the overview page (i.e. only projects explicitly | |
120 | listed in projects list file will be accessible). | |
121 | ||
122 | ||
123 | Generating projects list using gitweb | |
124 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
125 | ||
126 | We assume that GITWEB_CONFIG has its default Makefile value, namely | |
127 | 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: | |
128 | ---------------------------------------------------------------------------- | |
129 | read_config_file("gitweb_config.perl"); | |
130 | $projects_list = $projectroot; | |
131 | ---------------------------------------------------------------------------- | |
132 | ||
133 | Then create the following script to get list of project in the format | |
134 | suitable for GITWEB_LIST build configuration variable (or | |
135 | `$projects_list` variable in gitweb config): | |
136 | ||
137 | ---------------------------------------------------------------------------- | |
138 | #!/bin/sh | |
139 | ||
140 | export GITWEB_CONFIG="gitweb_make_index.perl" | |
141 | export GATEWAY_INTERFACE="CGI/1.1" | |
142 | export HTTP_ACCEPT="*/*" | |
143 | export REQUEST_METHOD="GET" | |
144 | export QUERY_STRING="a=project_index" | |
145 | ||
146 | perl -- /var/www/cgi-bin/gitweb.cgi | |
147 | ---------------------------------------------------------------------------- | |
148 | ||
149 | Run this script and save its output to a file. This file could then be used | |
150 | as projects list file, which means that you can set `$projects_list` to its | |
151 | filename. | |
152 | ||
153 | ||
2de9b711 | 154 | Controlling access to Git repositories |
07ea4df2 | 155 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
2de9b711 | 156 | By default all Git repositories under `$projectroot` are visible and |
07ea4df2 JN |
157 | available to gitweb. You can however configure how gitweb controls access |
158 | to repositories. | |
159 | ||
160 | * As described in "Projects list file format" section, you can control which | |
161 | projects are *visible* by selectively including repositories in projects | |
162 | list file, and setting `$projects_list` gitweb configuration variable to | |
163 | point to it. With `$strict_export` set, projects list file can be used to | |
164 | control which repositories are *available* as well. | |
165 | ||
166 | * You can configure gitweb to only list and allow viewing of the explicitly | |
167 | exported repositories, via `$export_ok` variable in gitweb config file; see | |
168 | linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows | |
169 | repositories only if this file named by `$export_ok` exists in its object | |
170 | database (if directory has the magic file named `$export_ok`). | |
171 | + | |
172 | For example linkgit:git-daemon[1] by default (unless `--export-all` option | |
173 | is used) allows pulling only for those repositories that have | |
174 | 'git-daemon-export-ok' file. Adding | |
175 | + | |
176 | -------------------------------------------------------------------------- | |
177 | our $export_ok = "git-daemon-export-ok"; | |
178 | -------------------------------------------------------------------------- | |
179 | + | |
180 | makes gitweb show and allow access only to those repositories that can be | |
181 | fetched from via `git://` protocol. | |
182 | ||
183 | * Finally, it is possible to specify an arbitrary perl subroutine that will | |
184 | be called for each repository to determine if it can be exported. The | |
185 | subroutine receives an absolute path to the project (repository) as its only | |
186 | parameter (i.e. "$projectroot/$project"). | |
187 | + | |
188 | For example, if you use mod_perl to run the script, and have dumb | |
189 | HTTP protocol authentication configured for your repositories, you | |
190 | can use the following hook to allow access only if the user is | |
191 | authorized to read the files: | |
192 | + | |
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 | ||
205 | ||
206 | Per-repository gitweb configuration | |
207 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
208 | You can configure individual repositories shown in gitweb by creating file | |
2de9b711 | 209 | in the 'GIT_DIR' of Git repository, or by setting some repo configuration |
07ea4df2 JN |
210 | variable (in 'GIT_DIR/config', see linkgit:git-config[1]). |
211 | ||
212 | You can use the following files in repository: | |
213 | ||
214 | README.html:: | |
215 | A html file (HTML fragment) which is included on the gitweb project | |
216 | "summary" page inside `<div>` block element. You can use it for longer | |
217 | description of a project, to provide links (for example to project's | |
218 | homepage), etc. This is recognized only if XSS prevention is off | |
219 | (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include | |
220 | a README safely when XSS prevention is on may be worked out in the | |
221 | future. | |
222 | ||
223 | description (or `gitweb.description`):: | |
224 | Short (shortened to `$projects_list_description_width` in the projects | |
225 | list page, which is 25 characters by default; see | |
226 | linkgit:gitweb.conf[5]) single line description of a project (of a | |
227 | repository). Plain text file; HTML will be escaped. By default set to | |
228 | + | |
229 | ------------------------------------------------------------------------------- | |
230 | Unnamed repository; edit this file to name it for gitweb. | |
231 | ------------------------------------------------------------------------------- | |
232 | + | |
233 | from the template during repository creation, usually installed in | |
234 | '/usr/share/git-core/templates/'. You can use the `gitweb.description` repo | |
235 | configuration variable, but the file takes precedence. | |
236 | ||
237 | category (or `gitweb.category`):: | |
238 | Singe line category of a project, used to group projects if | |
239 | `$projects_list_group_categories` is enabled. By default (file and | |
240 | configuration variable absent), uncategorized projects are put in the | |
241 | `$project_list_default_category` category. You can use the | |
242 | `gitweb.category` repo configuration variable, but the file takes | |
243 | precedence. | |
244 | + | |
245 | The configuration variables `$projects_list_group_categories` and | |
246 | `$project_list_default_category` are described in linkgit:gitweb.conf[5] | |
247 | ||
248 | cloneurl (or multiple-valued `gitweb.url`):: | |
249 | File with repository URL (used for clone and fetch), one per line. | |
250 | Displayed in the project summary page. You can use multiple-valued | |
251 | `gitweb.url` repository configuration variable for that, but the file | |
252 | takes precedence. | |
253 | + | |
254 | This is per-repository enhancement / version of global prefix-based | |
255 | `@git_base_url_list` gitweb configuration variable (see | |
256 | linkgit:gitweb.conf[5]). | |
257 | ||
258 | gitweb.owner:: | |
259 | You can use the `gitweb.owner` repository configuration variable to set | |
260 | repository's owner. It is displayed in the project list and summary | |
261 | page. | |
262 | + | |
263 | If it's not set, filesystem directory's owner is used (via GECOS field, | |
264 | i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset | |
265 | (gitweb scans `$projectroot` for repositories); if `$projects_list` | |
266 | points to file with list of repositories, then project owner defaults to | |
267 | value from this file for given repository. | |
268 | ||
269 | various `gitweb.*` config variables (in config):: | |
270 | Read description of `%feature` hash for detailed list, and descriptions. | |
271 | See also "Configuring gitweb features" section in linkgit:gitweb.conf[5] | |
272 | ||
273 | ||
274 | ACTIONS, AND URLS | |
275 | ----------------- | |
276 | Gitweb can use path_info (component) based URLs, or it can pass all necessary | |
277 | information via query parameters. The typical gitweb URLs are broken down in to | |
278 | five components: | |
279 | ||
280 | ----------------------------------------------------------------------- | |
281 | .../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments> | |
282 | ----------------------------------------------------------------------- | |
283 | ||
284 | repo:: | |
285 | The repository the action will be performed on. | |
286 | + | |
287 | All actions except for those that list all available projects, | |
288 | in whatever form, require this parameter. | |
289 | ||
290 | action:: | |
291 | The action that will be run. Defaults to 'projects_list' if repo | |
292 | is not set, and to 'summary' otherwise. | |
293 | ||
294 | revision:: | |
295 | Revision shown. Defaults to HEAD. | |
296 | ||
297 | path:: | |
298 | The path within the <repository> that the action is performed on, | |
299 | for those actions that require it. | |
300 | ||
301 | arguments:: | |
302 | Any arguments that control the behaviour of the action. | |
303 | ||
304 | Some actions require or allow to specify two revisions, and sometimes even two | |
305 | pathnames. In most general form such path_info (component) based gitweb URL | |
306 | looks like this: | |
307 | ||
308 | ----------------------------------------------------------------------- | |
309 | .../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments> | |
310 | ----------------------------------------------------------------------- | |
311 | ||
312 | ||
313 | Each action is implemented as a subroutine, and must be present in %actions | |
314 | hash. Some actions are disabled by default, and must be turned on via feature | |
315 | mechanism. For example to enable 'blame' view add the following to gitweb | |
316 | configuration file: | |
317 | ||
318 | ----------------------------------------------------------------------- | |
319 | $feature{'blame'}{'default'} = [1]; | |
320 | ----------------------------------------------------------------------- | |
321 | ||
322 | ||
323 | Actions: | |
324 | ~~~~~~~~ | |
325 | The standard actions are: | |
326 | ||
327 | project_list:: | |
328 | Lists the available Git repositories. This is the default command if no | |
329 | repository is specified in the URL. | |
330 | ||
331 | summary:: | |
332 | Displays summary about given repository. This is the default command if | |
333 | no action is specified in URL, and only repository is specified. | |
334 | ||
335 | heads:: | |
336 | remotes:: | |
337 | Lists all local or all remote-tracking branches in given repository. | |
338 | + | |
339 | The latter is not available by default, unless configured. | |
340 | ||
341 | tags:: | |
342 | List all tags (lightweight and annotated) in given repository. | |
343 | ||
344 | blob:: | |
345 | tree:: | |
346 | Shows the files and directories in a given repository path, at given | |
347 | revision. This is default command if no action is specified in the URL, | |
348 | and path is given. | |
349 | ||
350 | blob_plain:: | |
351 | Returns the raw data for the file in given repository, at given path and | |
352 | revision. Links to this action are marked 'raw'. | |
353 | ||
354 | blobdiff:: | |
355 | Shows the difference between two revisions of the same file. | |
356 | ||
357 | blame:: | |
358 | blame_incremental:: | |
359 | Shows the blame (also called annotation) information for a file. On a | |
360 | per line basis it shows the revision in which that line was last changed | |
361 | and the user that committed the change. The incremental version (which | |
362 | if configured is used automatically when JavaScript is enabled) uses | |
363 | Ajax to incrementally add blame info to the contents of given file. | |
364 | + | |
365 | This action is disabled by default for performance reasons. | |
366 | ||
367 | commit:: | |
368 | commitdiff:: | |
369 | Shows information about a specific commit in a repository. The 'commit' | |
370 | view shows information about commit in more detail, the 'commitdiff' | |
371 | action shows changeset for given commit. | |
372 | ||
373 | patch:: | |
374 | Returns the commit in plain text mail format, suitable for applying with | |
375 | linkgit:git-am[1]. | |
376 | ||
377 | tag:: | |
378 | Display specific annotated tag (tag object). | |
379 | ||
380 | log:: | |
381 | shortlog:: | |
382 | Shows log information (commit message or just commit subject) for a | |
383 | given branch (starting from given revision). | |
384 | + | |
385 | The 'shortlog' view is more compact; it shows one commit per line. | |
386 | ||
387 | history:: | |
388 | Shows history of the file or directory in a given repository path, | |
389 | starting from given revision (defaults to HEAD, i.e. default branch). | |
390 | + | |
391 | This view is similar to 'shortlog' view. | |
392 | ||
393 | rss:: | |
394 | atom:: | |
395 | Generates an RSS (or Atom) feed of changes to repository. | |
396 | ||
397 | ||
398 | WEBSERVER CONFIGURATION | |
399 | ----------------------- | |
400 | This section explains how to configure some common webservers to run gitweb. In | |
401 | all cases, `/path/to/gitweb` in the examples is the directory you ran installed | |
402 | gitweb in, and contains `gitweb_config.perl`. | |
403 | ||
404 | If you've configured a web server that isn't listed here for gitweb, please send | |
405 | in the instructions so they can be included in a future release. | |
406 | ||
407 | Apache as CGI | |
408 | ~~~~~~~~~~~~~ | |
409 | Apache must be configured to support CGI scripts in the directory in | |
410 | which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' | |
411 | directory. | |
412 | ||
413 | ----------------------------------------------------------------------- | |
414 | ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" | |
415 | ||
416 | <Directory "/var/www/cgi-bin"> | |
417 | Options Indexes FollowSymlinks ExecCGI | |
418 | AllowOverride None | |
419 | Order allow,deny | |
420 | Allow from all | |
421 | </Directory> | |
422 | ----------------------------------------------------------------------- | |
423 | ||
424 | With that configuration the full path to browse repositories would be: | |
425 | ||
426 | http://server/cgi-bin/gitweb.cgi | |
427 | ||
428 | Apache with mod_perl, via ModPerl::Registry | |
429 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
430 | You can use mod_perl with gitweb. You must install Apache::Registry | |
431 | (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable | |
432 | this support. | |
433 | ||
434 | Assuming that gitweb is installed to '/var/www/perl', the following | |
435 | Apache configuration (for mod_perl 2.x) is suitable. | |
436 | ||
437 | ----------------------------------------------------------------------- | |
438 | Alias /perl "/var/www/perl" | |
439 | ||
440 | <Directory "/var/www/perl"> | |
441 | SetHandler perl-script | |
442 | PerlResponseHandler ModPerl::Registry | |
443 | PerlOptions +ParseHeaders | |
444 | Options Indexes FollowSymlinks +ExecCGI | |
445 | AllowOverride None | |
446 | Order allow,deny | |
447 | Allow from all | |
448 | </Directory> | |
449 | ----------------------------------------------------------------------- | |
450 | ||
451 | With that configuration the full path to browse repositories would be: | |
452 | ||
453 | http://server/perl/gitweb.cgi | |
454 | ||
455 | Apache with FastCGI | |
456 | ~~~~~~~~~~~~~~~~~~~ | |
457 | Gitweb works with Apache and FastCGI. First you need to rename, copy | |
458 | or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is | |
459 | installed in '/usr/share/gitweb' directory. The following Apache | |
460 | configuration is suitable (UNTESTED!) | |
461 | ||
462 | ----------------------------------------------------------------------- | |
463 | FastCgiServer /usr/share/gitweb/gitweb.cgi | |
464 | ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi | |
465 | ||
466 | Alias /gitweb/static /usr/share/gitweb/static | |
467 | <Directory /usr/share/gitweb/static> | |
468 | SetHandler default-handler | |
469 | </Directory> | |
470 | ----------------------------------------------------------------------- | |
471 | ||
472 | With that configuration the full path to browse repositories would be: | |
473 | ||
474 | http://server/gitweb | |
475 | ||
476 | ||
477 | ADVANCED WEB SERVER SETUP | |
478 | ------------------------- | |
479 | All of those examples use request rewriting, and need `mod_rewrite` | |
480 | (or equivalent; examples below are written for Apache). | |
481 | ||
482 | Single URL for gitweb and for fetching | |
483 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
484 | If you want to have one URL for both gitweb and your `http://` | |
485 | repositories, you can configure Apache like this: | |
486 | ||
487 | ----------------------------------------------------------------------- | |
488 | <VirtualHost *:80> | |
489 | ServerName git.example.org | |
490 | DocumentRoot /pub/git | |
491 | SetEnv GITWEB_CONFIG /etc/gitweb.conf | |
492 | ||
493 | # turning on mod rewrite | |
494 | RewriteEngine on | |
495 | ||
496 | # make the front page an internal rewrite to the gitweb script | |
497 | RewriteRule ^/$ /cgi-bin/gitweb.cgi | |
498 | ||
499 | # make access for "dumb clients" work | |
500 | RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ | |
501 | /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] | |
502 | </VirtualHost> | |
503 | ----------------------------------------------------------------------- | |
504 | ||
505 | The above configuration expects your public repositories to live under | |
506 | '/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, | |
17b83d71 | 507 | both as clonable Git URL and as browseable gitweb interface. If you then |
07ea4df2 JN |
508 | start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` |
509 | then you can even use the `git://` URL with exactly the same path. | |
510 | ||
511 | Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the | |
512 | named file (i.e. in this example '/etc/gitweb.conf') as a configuration for | |
513 | gitweb. You don't really need it in above example; it is required only if | |
514 | your configuration file is in different place than built-in (during | |
515 | compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See | |
516 | linkgit:gitweb.conf[5] for details, especially information about precedence | |
517 | rules. | |
518 | ||
519 | If you use the rewrite rules from the example you *might* also need | |
520 | something like the following in your gitweb configuration file | |
521 | ('/etc/gitweb.conf' following example): | |
522 | ---------------------------------------------------------------------------- | |
523 | @stylesheets = ("/some/absolute/path/gitweb.css"); | |
524 | $my_uri = "/"; | |
525 | $home_link = "/"; | |
526 | $per_request_config = 1; | |
527 | ---------------------------------------------------------------------------- | |
528 | Nowadays though gitweb should create HTML base tag when needed (to set base | |
529 | URI for relative links), so it should work automatically. | |
530 | ||
531 | ||
532 | Webserver configuration with multiple projects' root | |
533 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
534 | If you want to use gitweb with several project roots you can edit your | |
535 | Apache virtual host and gitweb configuration files in the following way. | |
536 | ||
537 | The virtual host configuration (in Apache configuration file) should look | |
538 | like this: | |
539 | -------------------------------------------------------------------------- | |
540 | <VirtualHost *:80> | |
541 | ServerName git.example.org | |
542 | DocumentRoot /pub/git | |
543 | SetEnv GITWEB_CONFIG /etc/gitweb.conf | |
544 | ||
545 | # turning on mod rewrite | |
546 | RewriteEngine on | |
547 | ||
548 | # make the front page an internal rewrite to the gitweb script | |
549 | RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] | |
550 | ||
551 | # look for a public_git folder in unix users' home | |
552 | # http://git.example.org/~<user>/ | |
553 | RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ | |
554 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] | |
555 | ||
556 | # http://git.example.org/+<user>/ | |
557 | #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ | |
558 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] | |
559 | ||
560 | # http://git.example.org/user/<user>/ | |
561 | #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ | |
562 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] | |
563 | ||
564 | # defined list of project roots | |
565 | RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ | |
566 | [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] | |
567 | RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ | |
568 | [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] | |
569 | ||
570 | # make access for "dumb clients" work | |
571 | RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ | |
572 | /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] | |
573 | </VirtualHost> | |
574 | -------------------------------------------------------------------------- | |
575 | ||
576 | Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` | |
577 | environment variable from a web server, so you need to put the following | |
578 | line in gitweb configuration file ('/etc/gitweb.conf' in above example): | |
579 | -------------------------------------------------------------------------- | |
580 | $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; | |
581 | -------------------------------------------------------------------------- | |
582 | *Note* that this requires to be set for each request, so either | |
583 | `$per_request_config` must be false, or the above must be put in code | |
584 | referenced by `$per_request_config`; | |
585 | ||
586 | These configurations enable two things. First, each unix user (`<user>`) of | |
2de9b711 | 587 | the server will be able to browse through gitweb Git repositories found in |
07ea4df2 JN |
588 | '~/public_git/' with the following url: |
589 | ||
590 | http://git.example.org/~<user>/ | |
591 | ||
592 | If you do not want this feature on your server just remove the second | |
593 | rewrite rule. | |
594 | ||
595 | If you already use `mod_userdir` in your virtual host or you don't want to | |
596 | use the \'~' as first character, just comment or remove the second rewrite | |
597 | rule, and uncomment one of the following according to what you want. | |
598 | ||
599 | Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible | |
600 | through `http://git.example.org/scm/` and `http://git.example.org/var/`. | |
601 | You can add as many project roots as you want by adding rewrite rules like | |
602 | the third and the fourth. | |
603 | ||
604 | ||
605 | PATH_INFO usage | |
606 | ~~~~~~~~~~~~~~~ | |
607 | If you enable PATH_INFO usage in gitweb by putting | |
608 | ---------------------------------------------------------------------------- | |
609 | $feature{'pathinfo'}{'default'} = [1]; | |
610 | ---------------------------------------------------------------------------- | |
611 | in your gitweb configuration file, it is possible to set up your server so | |
612 | that it consumes and produces URLs in the form | |
613 | ||
614 | http://git.example.com/project.git/shortlog/sometag | |
615 | ||
616 | i.e. without 'gitweb.cgi' part, by using a configuration such as the | |
617 | following. This configuration assumes that '/var/www/gitweb' is the | |
618 | DocumentRoot of your webserver, contains the gitweb.cgi script and | |
619 | complementary static files (stylesheet, favicon, JavaScript): | |
620 | ||
621 | ---------------------------------------------------------------------------- | |
622 | <VirtualHost *:80> | |
623 | ServerAlias git.example.com | |
624 | ||
625 | DocumentRoot /var/www/gitweb | |
626 | ||
627 | <Directory /var/www/gitweb> | |
628 | Options ExecCGI | |
629 | AddHandler cgi-script cgi | |
630 | ||
631 | DirectoryIndex gitweb.cgi | |
632 | ||
633 | RewriteEngine On | |
634 | RewriteCond %{REQUEST_FILENAME} !-f | |
635 | RewriteCond %{REQUEST_FILENAME} !-d | |
636 | RewriteRule ^.* /gitweb.cgi/$0 [L,PT] | |
637 | </Directory> | |
638 | </VirtualHost> | |
639 | ---------------------------------------------------------------------------- | |
640 | The rewrite rule guarantees that existing static files will be properly | |
641 | served, whereas any other URL will be passed to gitweb as PATH_INFO | |
642 | parameter. | |
643 | ||
644 | *Notice* that in this case you don't need special settings for | |
645 | `@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" | |
646 | access to your project .git dirs (described in "Single URL for gitweb and | |
647 | for fetching" section). A possible workaround for the latter is the | |
648 | following: in your project root dir (e.g. '/pub/git') have the projects | |
649 | named *without* a .git extension (e.g. '/pub/git/project' instead of | |
650 | '/pub/git/project.git') and configure Apache as follows: | |
651 | ---------------------------------------------------------------------------- | |
652 | <VirtualHost *:80> | |
653 | ServerAlias git.example.com | |
654 | ||
655 | DocumentRoot /var/www/gitweb | |
656 | ||
657 | AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 | |
658 | <Directory /var/www/gitweb> | |
659 | Options ExecCGI | |
660 | AddHandler cgi-script cgi | |
661 | ||
662 | DirectoryIndex gitweb.cgi | |
663 | ||
664 | RewriteEngine On | |
665 | RewriteCond %{REQUEST_FILENAME} !-f | |
666 | RewriteCond %{REQUEST_FILENAME} !-d | |
667 | RewriteRule ^.* /gitweb.cgi/$0 [L,PT] | |
668 | </Directory> | |
669 | </VirtualHost> | |
670 | ---------------------------------------------------------------------------- | |
671 | ||
672 | The additional AliasMatch makes it so that | |
673 | ||
674 | http://git.example.com/project.git | |
675 | ||
2de9b711 | 676 | will give raw access to the project's Git dir (so that the project can be |
07ea4df2 JN |
677 | cloned), while |
678 | ||
679 | http://git.example.com/project | |
680 | ||
681 | will provide human-friendly gitweb access. | |
682 | ||
683 | This solution is not 100% bulletproof, in the sense that if some project has | |
684 | a named ref (branch, tag) starting with 'git/', then paths such as | |
685 | ||
686 | http://git.example.com/project/command/abranch..git/abranch | |
687 | ||
688 | will fail with a 404 error. | |
689 | ||
690 | ||
691 | BUGS | |
692 | ---- | |
693 | Please report any bugs or feature requests to git@vger.kernel.org, | |
694 | putting "gitweb" in the subject of email. | |
695 | ||
696 | SEE ALSO | |
697 | -------- | |
698 | linkgit:gitweb.conf[5], linkgit:git-instaweb[1] | |
699 | ||
700 | 'gitweb/README', 'gitweb/INSTALL' | |
701 | ||
702 | GIT | |
703 | --- | |
704 | Part of the linkgit:git[1] suite |