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