1GITWEB(1)                         Git Manual                         GITWEB(1)
2
3
4

NAME

6       gitweb - Git web interface (web frontend to Git repositories)
7

SYNOPSIS

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

DESCRIPTION

14       Gitweb provides a web interface to Git repositories. Its features
15       include:
16
17       ·   Viewing multiple Git repositories with common root.
18
19       ·   Browsing every revision of the repository.
20
21       ·   Viewing the contents of files in the repository at any revision.
22
23       ·   Viewing the revision log of branches, history of files and
24           directories, see what was changed when, by who.
25
26       ·   Viewing the blame/annotation details of any file (if enabled).
27
28       ·   Generating RSS and Atom feeds of commits, for any branch. The feeds
29           are auto-discoverable in modern web browsers.
30
31       ·   Viewing everything that was changed in a revision, and step through
32           revisions one at a time, viewing the history of the repository.
33
34       ·   Finding commits which commit messages matches given search term.
35
36       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

CONFIGURATION

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
45   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
52           our $projectroot = '/path/to/parent/directory';
53
54
55       The default value for $projectroot is /pub/git. You can change it
56       during building gitweb via GITWEB_PROJECTROOT build configuration
57       variable.
58
59       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
65       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
69   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
75       This file uses the following format:
76
77       ·   One record (for project / repository) per line; does not support
78           line continuation (newline escaping).
79
80       ·   Leading and trailing whitespace are ignored.
81
82       ·   Whitespace separated fields; any run of whitespace can be used as
83           field separator (rules for Perl’s "split(" ", $line)").
84
85       ·   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
91           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
95       ·   Currently recognized fields are:
96
97           <repository path>
98               path to repository GIT_DIR, relative to $projectroot
99
100           <repository owner>
101               displayed as repository owner, preferably full name, or email,
102               or both
103
104       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
108       Example contents:
109
110           foo.git       Joe+R+Hacker+<joe@example.com>
111           foo/bar.git   O+W+Ner+<owner@example.org>
112
113
114       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
123   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
127           read_config_file("gitweb_config.perl");
128           $projects_list = $projectroot;
129
130
131       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
135           #!/bin/sh
136
137           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
143           perl -- /var/www/cgi-bin/gitweb.cgi
144
145
146       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
150   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
155       ·   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
162       ·   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
169           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
173               our $export_ok = "git-daemon-export-ok";
174
175           makes gitweb show and allow access only to those repositories that
176           can be fetched from via git:// protocol.
177
178       ·   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
183           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
188               $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
198
199   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
204       You can use the following files in repository:
205
206       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
215       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
222               Unnamed repository; edit this file to name it for gitweb.
223
224           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
228       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
236           The configuration variables $projects_list_group_categories and
237           $project_list_default_category are described in gitweb.conf(5)
238
239       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
245           This is per-repository enhancement / version of global prefix-based
246           @git_base_url_list gitweb configuration variable (see
247           gitweb.conf(5)).
248
249       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
254           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
261       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

ACTIONS, AND URLS

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
271           .../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>
272
273
274
275       repo
276           The repository the action will be performed on.
277
278           All actions except for those that list all available projects, in
279           whatever form, require this parameter.
280
281       action
282           The action that will be run. Defaults to projects_list if repo is
283           not set, and to summary otherwise.
284
285       revision
286           Revision shown. Defaults to HEAD.
287
288       path
289           The path within the <repository> that the action is performed on,
290           for those actions that require it.
291
292       arguments
293           Any arguments that control the behaviour of the action.
294
295       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
299           .../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
300
301
302       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
307           $feature{'blame'}{'default'} = [1];
308
309
310   Actions:
311       The standard actions are:
312
313       project_list
314           Lists the available Git repositories. This is the default command
315           if no repository is specified in the URL.
316
317       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
322       heads, remotes
323           Lists all local or all remote-tracking branches in given
324           repository.
325
326           The latter is not available by default, unless configured.
327
328       tags
329           List all tags (lightweight and annotated) in given repository.
330
331       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
336       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
340       blobdiff
341           Shows the difference between two revisions of the same file.
342
343       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
351           This action is disabled by default for performance reasons.
352
353       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
358       patch
359           Returns the commit in plain text mail format, suitable for applying
360           with git-am(1).
361
362       tag
363           Display specific annotated tag (tag object).
364
365       log, shortlog
366           Shows log information (commit message or just commit subject) for a
367           given branch (starting from given revision).
368
369           The shortlog view is more compact; it shows one commit per line.
370
371       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
376           This view is similar to shortlog view.
377
378       rss, atom
379           Generates an RSS (or Atom) feed of changes to repository.
380

WEBSERVER CONFIGURATION

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
386       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
390   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
395           ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
396
397           <Directory "/var/www/cgi-bin">
398               Options Indexes FollowSymlinks ExecCGI
399               AllowOverride None
400               Order allow,deny
401               Allow from all
402           </Directory>
403
404
405       With that configuration the full path to browse repositories would be:
406
407           http://server/cgi-bin/gitweb.cgi
408
409   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
414       Assuming that gitweb is installed to /var/www/perl, the following
415       Apache configuration (for mod_perl 2.x) is suitable.
416
417           Alias /perl "/var/www/perl"
418
419           <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
429
430       With that configuration the full path to browse repositories would be:
431
432           http://server/perl/gitweb.cgi
433
434   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
440           FastCgiServer /usr/share/gitweb/gitweb.cgi
441           ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
442
443           Alias /gitweb/static /usr/share/gitweb/static
444           <Directory /usr/share/gitweb/static>
445               SetHandler default-handler
446           </Directory>
447
448
449       With that configuration the full path to browse repositories would be:
450
451           http://server/gitweb
452

ADVANCED WEB SERVER SETUP

454       All of those examples use request rewriting, and need mod_rewrite (or
455       equivalent; examples below are written for Apache).
456
457   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
461           <VirtualHost *:80>
462               ServerName    git.example.org
463               DocumentRoot  /pub/git
464               SetEnv        GITWEB_CONFIG   /etc/gitweb.conf
465
466               # turning on mod rewrite
467               RewriteEngine on
468
469               # make the front page an internal rewrite to the gitweb script
470               RewriteRule ^/$  /cgi-bin/gitweb.cgi
471
472               # 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
477
478       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
485       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
493       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
497           @stylesheets = ("/some/absolute/path/gitweb.css");
498           $my_uri    = "/";
499           $home_link = "/";
500           $per_request_config = 1;
501
502
503       Nowadays though gitweb should create HTML base tag when needed (to set
504       base URI for relative links), so it should work automatically.
505
506   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
511       The virtual host configuration (in Apache configuration file) should
512       look like this:
513
514           <VirtualHost *:80>
515               ServerName    git.example.org
516               DocumentRoot  /pub/git
517               SetEnv        GITWEB_CONFIG  /etc/gitweb.conf
518
519               # turning on mod rewrite
520               RewriteEngine on
521
522               # make the front page an internal rewrite to the gitweb script
523               RewriteRule ^/$  /cgi-bin/gitweb.cgi  [QSA,L,PT]
524
525               # 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
530               # 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
534               # 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
538               # 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
544               # 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
549
550       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
555           $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
556
557
558       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
562       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
566           http://git.example.org/~<user>/
567
568       If you do not want this feature on your server just remove the second
569       rewrite rule.
570
571       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
576       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
581   PATH_INFO usage
582       If you enable PATH_INFO usage in gitweb by putting
583
584           $feature{'pathinfo'}{'default'} = [1];
585
586
587       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
590           http://git.example.com/project.git/shortlog/sometag
591
592       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
597           <VirtualHost *:80>
598                   ServerAlias git.example.com
599
600                   DocumentRoot /var/www/gitweb
601
602                   <Directory /var/www/gitweb>
603                           Options ExecCGI
604                           AddHandler cgi-script cgi
605
606                           DirectoryIndex gitweb.cgi
607
608                           RewriteEngine On
609                           RewriteCond %{REQUEST_FILENAME} !-f
610                           RewriteCond %{REQUEST_FILENAME} !-d
611                           RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
612                   </Directory>
613           </VirtualHost>
614
615
616       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
620       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
628           <VirtualHost *:80>
629                   ServerAlias git.example.com
630
631                   DocumentRoot /var/www/gitweb
632
633                   AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
634                   <Directory /var/www/gitweb>
635                           Options ExecCGI
636                           AddHandler cgi-script cgi
637
638                           DirectoryIndex gitweb.cgi
639
640                           RewriteEngine On
641                           RewriteCond %{REQUEST_FILENAME} !-f
642                           RewriteCond %{REQUEST_FILENAME} !-d
643                           RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
644                   </Directory>
645           </VirtualHost>
646
647
648       The additional AliasMatch makes it so that
649
650           http://git.example.com/project.git
651
652       will give raw access to the project’s Git dir (so that the project can
653       be cloned), while
654
655           http://git.example.com/project
656
657       will provide human-friendly gitweb access.
658
659       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
663           http://git.example.com/project/command/abranch..git/abranch
664
665       will fail with a 404 error.
666

BUGS

668       Please report any bugs or feature requests to git@vger.kernel.org[1],
669       putting "gitweb" in the subject of email.
670

SEE ALSO

672       gitweb.conf(5), git-instaweb(1)
673
674       gitweb/README, gitweb/INSTALL
675

GIT

677       Part of the git(1) suite
678

NOTES

680        1. git@vger.kernel.org
681           mailto:git@vger.kernel.org
682
683
684
685Git 2.21.0                        02/24/2019                         GITWEB(1)
Impressum