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