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