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