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 will configure and start your web server, and run a 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, seeing what was changed, when, and by whom.
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 stepping
32 through revisions one at a time, viewing the history of the
33 repository.
34 • Finding commits whose commit messages match a given search term.
36 See http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ for gitweb source
38 code, 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 a
48 common repository root, i.e. be all under a single parent repository
49 (but see also the "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
55 during building gitweb via the 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 the 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
113 projects list page (note that entries that do not point to correctly
114 recognized Git repositories won’t be displayed by gitweb). Even if a
115 project is not visible on projects list page, you can view it
116 nevertheless by hand-crafting a gitweb URL. By setting $strict_export
117 configuration variable (see gitweb.conf(5)) to true value you can allow
118 viewing only of repositories also shown on the overview page (i.e. only
119 projects explicitly listed in projects list file will be accessible).
120 Generating projects list using gitweb
122 We assume that GITWEB_CONFIG has its default Makefile value, namely
123 gitweb_config.perl. Put the following in gitweb_make_index.perl file:
124 read_config_file("gitweb_config.perl");
126 $projects_list = $projectroot;
127 Then create the following script to get list of project in the format
129 suitable for GITWEB_LIST build configuration variable (or
130 $projects_list variable in gitweb config):
131 #!/bin/sh
133 export GITWEB_CONFIG="gitweb_make_index.perl"
135 export GATEWAY_INTERFACE="CGI/1.1"
136 export HTTP_ACCEPT="*/*"
137 export REQUEST_METHOD="GET"
138 export QUERY_STRING="a=project_index"
139 perl -- /var/www/cgi-bin/gitweb.cgi
141 Run this script and save its output to a file. This file could then be
143 used as projects list file, which means that you can set $projects_list
144 to its filename.
145 Controlling access to Git repositories
147 By default all Git repositories under $projectroot are visible and
148 available to gitweb. You can however configure how gitweb controls
149 access to repositories.
150 • As described in "Projects list file format" section, you can
152 control which projects are visible by selectively including
153 repositories in projects list file, and setting $projects_list
154 gitweb configuration variable to point to it. With $strict_export
155 set, projects list file can be used to control which repositories
156 are available as well.
157 • You can configure gitweb to only list and allow viewing of the
159 explicitly exported repositories, via $export_ok variable in gitweb
160 config file; see gitweb.conf(5) manpage. If it evaluates to true,
161 gitweb shows repositories only if this file named by $export_ok
162 exists in its object database (if directory has the magic file
163 named $export_ok).
164 For example git-daemon(1) by default (unless --export-all option is
166 used) allows pulling only for those repositories that have
167 git-daemon-export-ok file. Adding
168 our $export_ok = "git-daemon-export-ok";
170 makes gitweb show and allow access only to those repositories that
172 can be fetched from via git:// protocol.
173 • Finally, it is possible to specify an arbitrary perl subroutine
175 that will be called for each repository to determine if it can be
176 exported. The subroutine receives an absolute path to the project
177 (repository) as its only parameter (i.e. "$projectroot/$project").
178 For example, if you use mod_perl to run the script, and have dumb
180 HTTP protocol authentication configured for your repositories, you
181 can use the following hook to allow access only if the user is
182 authorized to read the files:
183 $export_auth_hook = sub {
185 use Apache2::SubRequest ();
186 use Apache2::Const -compile => qw(HTTP_OK);
187 my $path = "$_[0]/HEAD";
188 my $r = Apache2::RequestUtil->request;
189 my $sub = $r->lookup_file($path);
190 return $sub->filename eq $path
191 && $sub->status == Apache2::Const::HTTP_OK;
192 };
193 Per-repository gitweb configuration
195 You can configure individual repositories shown in gitweb by creating
196 file in the GIT_DIR of Git repository, or by setting some repo
197 configuration variable (in GIT_DIR/config, see git-config(1)).
198 You can use the following files in repository:
200 README.html
202 A html file (HTML fragment) which is included on the gitweb project
203 "summary" page inside <div> block element. You can use it for
204 longer description of a project, to provide links (for example to
205 project’s homepage), etc. This is recognized only if XSS prevention
206 is off ($prevent_xss is false, see gitweb.conf(5)); a way to
207 include a README safely when XSS prevention is on may be worked out
208 in the future.
209 description (or gitweb.description)
211 Short (shortened to $projects_list_description_width in the
212 projects list page, which is 25 characters by default; see
213 gitweb.conf(5)) single line description of a project (of a
214 repository). Plain text file; HTML will be escaped. By default set
215 to
216 Unnamed repository; edit this file to name it for gitweb.
218 from the template during repository creation, usually installed in
220 /usr/share/git-core/templates/. You can use the gitweb.description
221 repo configuration variable, but the file takes precedence.
222 category (or gitweb.category)
224 Singe line category of a project, used to group projects if
225 $projects_list_group_categories is enabled. By default (file and
226 configuration variable absent), uncategorized projects are put in
227 the $project_list_default_category category. You can use the
228 gitweb.category repo configuration variable, but the file takes
229 precedence.
230 The configuration variables $projects_list_group_categories and
232 $project_list_default_category are described in gitweb.conf(5)
233 cloneurl (or multiple-valued gitweb.url)
235 File with repository URL (used for clone and fetch), one per line.
236 Displayed in the project summary page. You can use multiple-valued
237 gitweb.url repository configuration variable for that, but the file
238 takes precedence.
239 This is per-repository enhancement / version of global prefix-based
241 @git_base_url_list gitweb configuration variable (see
242 gitweb.conf(5)).
243 gitweb.owner
245 You can use the gitweb.owner repository configuration variable to
246 set repository’s owner. It is displayed in the project list and
247 summary page.
248 If it’s not set, filesystem directory’s owner is used (via GECOS
250 field, i.e. real name field from getpwuid(3)) if $projects_list is
251 unset (gitweb scans $projectroot for repositories); if
252 $projects_list points to file with list of repositories, then
253 project owner defaults to value from this file for given
254 repository.
255 various gitweb.* config variables (in config)
257 Read description of %feature hash for detailed list, and
258 descriptions. See also "Configuring gitweb features" section in
259 gitweb.conf(5)
260
262 Gitweb can use path_info (component) based URLs, or it can pass all
263 necessary information via query parameters. The typical gitweb URLs are
264 broken down in to five components:
265 .../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>
267 repo
269 The repository the action will be performed on.
270 All actions except for those that list all available projects, in
272 whatever form, require this parameter.
273 action
275 The action that will be run. Defaults to projects_list if repo is
276 not set, and to summary otherwise.
277 revision
279 Revision shown. Defaults to HEAD.
280 path
282 The path within the <repository> that the action is performed on,
283 for those actions that require it.
284 arguments
286 Any arguments that control the behaviour of the action.
287 Some actions require or allow to specify two revisions, and sometimes
289 even two pathnames. In most general form such path_info (component)
290 based gitweb URL looks like this:
291 .../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
293 Each action is implemented as a subroutine, and must be present in
295 %actions hash. Some actions are disabled by default, and must be turned
296 on via feature mechanism. For example to enable blame view add the
297 following to gitweb configuration file:
298 $feature{'blame'}{'default'} = [1];
300 Actions:
302 The standard actions are:
303 project_list
305 Lists the available Git repositories. This is the default command
306 if no repository is specified in the URL.
307 summary
309 Displays summary about given repository. This is the default
310 command if no action is specified in URL, and only repository is
311 specified.
312 heads, remotes
314 Lists all local or all remote-tracking branches in given
315 repository.
316 The latter is not available by default, unless configured.
318 tags
320 List all tags (lightweight and annotated) in given repository.
321 blob, tree
323 Shows the files and directories in a given repository path, at
324 given revision. This is default command if no action is specified
325 in the URL, and path is given.
326 blob_plain
328 Returns the raw data for the file in given repository, at given
329 path and revision. Links to this action are marked raw.
330 blobdiff
332 Shows the difference between two revisions of the same file.
333 blame, blame_incremental
335 Shows the blame (also called annotation) information for a file. On
336 a per line basis it shows the revision in which that line was last
337 changed and the user that committed the change. The incremental
338 version (which if configured is used automatically when JavaScript
339 is enabled) uses Ajax to incrementally add blame info to the
340 contents of given file.
341 This action is disabled by default for performance reasons.
343 commit, commitdiff
345 Shows information about a specific commit in a repository. The
346 commit view shows information about commit in more detail, the
347 commitdiff action shows changeset for given commit.
348 patch
350 Returns the commit in plain text mail format, suitable for applying
351 with git-am(1).
352 tag
354 Display specific annotated tag (tag object).
355 log, shortlog
357 Shows log information (commit message or just commit subject) for a
358 given branch (starting from given revision).
359 The shortlog view is more compact; it shows one commit per line.
361 history
363 Shows history of the file or directory in a given repository path,
364 starting from given revision (defaults to HEAD, i.e. default
365 branch).
366 This view is similar to shortlog view.
368 rss, atom
370 Generates an RSS (or Atom) feed of changes to repository.
371
373 This section explains how to configure some common webservers to run
374 gitweb. In all cases, /path/to/gitweb in the examples is the directory
375 you ran installed gitweb in, and contains gitweb_config.perl.
376 If you’ve configured a web server that isn’t listed here for gitweb,
378 please send in the instructions so they can be included in a future
379 release.
380 Apache as CGI
382 Apache must be configured to support CGI scripts in the directory in
383 which gitweb is installed. Let’s assume that it is /var/www/cgi-bin
384 directory.
385 ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
387 <Directory "/var/www/cgi-bin">
389 Options Indexes FollowSymlinks ExecCGI
390 AllowOverride None
391 Order allow,deny
392 Allow from all
393 </Directory>
394 With that configuration the full path to browse repositories would be:
396 http://server/cgi-bin/gitweb.cgi
398 Apache with mod_perl, via ModPerl::Registry
400 You can use mod_perl with gitweb. You must install Apache::Registry
401 (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable
402 this support.
403 Assuming that gitweb is installed to /var/www/perl, the following
405 Apache configuration (for mod_perl 2.x) is suitable.
406 Alias /perl "/var/www/perl"
408 <Directory "/var/www/perl">
410 SetHandler perl-script
411 PerlResponseHandler ModPerl::Registry
412 PerlOptions +ParseHeaders
413 Options Indexes FollowSymlinks +ExecCGI
414 AllowOverride None
415 Order allow,deny
416 Allow from all
417 </Directory>
418 With that configuration the full path to browse repositories would be:
420 http://server/perl/gitweb.cgi
422 Apache with FastCGI
424 Gitweb works with Apache and FastCGI. First you need to rename, copy or
425 symlink gitweb.cgi to gitweb.fcgi. Let’s assume that gitweb is
426 installed in /usr/share/gitweb directory. The following Apache
427 configuration is suitable (UNTESTED!)
428 FastCgiServer /usr/share/gitweb/gitweb.cgi
430 ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
431 Alias /gitweb/static /usr/share/gitweb/static
433 <Directory /usr/share/gitweb/static>
434 SetHandler default-handler
435 </Directory>
436 With that configuration the full path to browse repositories would be:
438 http://server/gitweb
440
442 All of those examples use request rewriting, and need mod_rewrite (or
443 equivalent; examples below are written for Apache).
444 Single URL for gitweb and for fetching
446 If you want to have one URL for both gitweb and your http://
447 repositories, you can configure Apache like this:
448 <VirtualHost *:80>
450 ServerName git.example.org
451 DocumentRoot /pub/git
452 SetEnv GITWEB_CONFIG /etc/gitweb.conf
453 # turning on mod rewrite
455 RewriteEngine on
456 # make the front page an internal rewrite to the gitweb script
458 RewriteRule ^/$ /cgi-bin/gitweb.cgi
459 # make access for "dumb clients" work
461 RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
462 /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
463 </VirtualHost>
464 The above configuration expects your public repositories to live under
466 /pub/git and will serve them as
467 http://git.domain.org/dir-under-pub-git, both as clonable Git URL and
468 as browsable gitweb interface. If you then start your git-daemon(1)
469 with --base-path=/pub/git --export-all then you can even use the git://
470 URL with exactly the same path.
471 Setting the environment variable GITWEB_CONFIG will tell gitweb to use
473 the named file (i.e. in this example /etc/gitweb.conf) as a
474 configuration for gitweb. You don’t really need it in above example; it
475 is required only if your configuration file is in different place than
476 built-in (during compiling gitweb) gitweb_config.perl or
477 /etc/gitweb.conf. See gitweb.conf(5) for details, especially
478 information about precedence rules.
479 If you use the rewrite rules from the example you might also need
481 something like the following in your gitweb configuration file
482 (/etc/gitweb.conf following example):
483 @stylesheets = ("/some/absolute/path/gitweb.css");
485 $my_uri = "/";
486 $home_link = "/";
487 $per_request_config = 1;
488 Nowadays though gitweb should create HTML base tag when needed (to set
490 base URI for relative links), so it should work automatically.
491 Webserver configuration with multiple projects' root
493 If you want to use gitweb with several project roots you can edit your
494 Apache virtual host and gitweb configuration files in the following
495 way.
496 The virtual host configuration (in Apache configuration file) should
498 look like this:
499 <VirtualHost *:80>
501 ServerName git.example.org
502 DocumentRoot /pub/git
503 SetEnv GITWEB_CONFIG /etc/gitweb.conf
504 # turning on mod rewrite
506 RewriteEngine on
507 # make the front page an internal rewrite to the gitweb script
509 RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT]
510 # look for a public_git directory in unix users' home
512 # http://git.example.org/~<user>/
513 RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
514 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
515 # http://git.example.org/+<user>/
517 #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
518 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
519 # http://git.example.org/user/<user>/
521 #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
522 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
523 # defined list of project roots
525 RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
526 [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
527 RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
528 [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
529 # make access for "dumb clients" work
531 RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
532 /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
533 </VirtualHost>
534 Here actual project root is passed to gitweb via GITWEB_PROJECT_ROOT
536 environment variable from a web server, so you need to put the
537 following line in gitweb configuration file (/etc/gitweb.conf in above
538 example):
539 $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
541 Note that this requires to be set for each request, so either
543 $per_request_config must be false, or the above must be put in code
544 referenced by $per_request_config;
545 These configurations enable two things. First, each unix user (<user>)
547 of the server will be able to browse through gitweb Git repositories
548 found in ~/public_git/ with the following url:
549 http://git.example.org/~<user>/
551 If you do not want this feature on your server just remove the second
553 rewrite rule.
554 If you already use mod_userdir in your virtual host or you don’t want
556 to use the '~' as first character, just comment or remove the second
557 rewrite rule, and uncomment one of the following according to what you
558 want.
559 Second, repositories found in /pub/scm/ and /var/git/ will be
561 accessible through http://git.example.org/scm/ and
562 http://git.example.org/var/. You can add as many project roots as you
563 want by adding rewrite rules like the third and the fourth.
564 PATH_INFO usage
566 If you enable PATH_INFO usage in gitweb by putting
567 $feature{'pathinfo'}{'default'} = [1];
569 in your gitweb configuration file, it is possible to set up your server
571 so that it consumes and produces URLs in the form
572 http://git.example.com/project.git/shortlog/sometag
574 i.e. without gitweb.cgi part, by using a configuration such as the
576 following. This configuration assumes that /var/www/gitweb is the
577 DocumentRoot of your webserver, contains the gitweb.cgi script and
578 complementary static files (stylesheet, favicon, JavaScript):
579 <VirtualHost *:80>
581 ServerAlias git.example.com
582 DocumentRoot /var/www/gitweb
584 <Directory /var/www/gitweb>
586 Options ExecCGI
587 AddHandler cgi-script cgi
588 DirectoryIndex gitweb.cgi
590 RewriteEngine On
592 RewriteCond %{REQUEST_FILENAME} !-f
593 RewriteCond %{REQUEST_FILENAME} !-d
594 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
595 </Directory>
596 </VirtualHost>
597 The rewrite rule guarantees that existing static files will be properly
599 served, whereas any other URL will be passed to gitweb as PATH_INFO
600 parameter.
601 Notice that in this case you don’t need special settings for
603 @stylesheets, $my_uri and $home_link, but you lose "dumb client" access
604 to your project .git dirs (described in "Single URL for gitweb and for
605 fetching" section). A possible workaround for the latter is the
606 following: in your project root dir (e.g. /pub/git) have the projects
607 named without a .git extension (e.g. /pub/git/project instead of
608 /pub/git/project.git) and configure Apache as follows:
609 <VirtualHost *:80>
611 ServerAlias git.example.com
612 DocumentRoot /var/www/gitweb
614 AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
616 <Directory /var/www/gitweb>
617 Options ExecCGI
618 AddHandler cgi-script cgi
619 DirectoryIndex gitweb.cgi
621 RewriteEngine On
623 RewriteCond %{REQUEST_FILENAME} !-f
624 RewriteCond %{REQUEST_FILENAME} !-d
625 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
626 </Directory>
627 </VirtualHost>
628 The additional AliasMatch makes it so that
630 http://git.example.com/project.git
632 will give raw access to the project’s Git dir (so that the project can
634 be cloned), while
635 http://git.example.com/project
637 will provide human-friendly gitweb access.
639 This solution is not 100% bulletproof, in the sense that if some
641 project has a named ref (branch, tag) starting with git/, then paths
642 such as
643 http://git.example.com/project/command/abranch..git/abranch
645 will fail with a 404 error.
647
649 Please report any bugs or feature requests to git@vger.kernel.org[1],
650 putting "gitweb" in the subject of email.
651
653 gitweb.conf(5), git-instaweb(1)
654 gitweb/README, gitweb/INSTALL
656
658 Part of the git(1) suite
659
661 1. git@vger.kernel.org
662 mailto:git@vger.kernel.org
663Git 2.43.0 11/20/2023 GITWEB(1)