1GITWEB.CONF(5)                    Git Manual                    GITWEB.CONF(5)
2
3
4

NAME

6       gitweb.conf - Gitweb (Git web interface) configuration file
7

SYNOPSIS

9       /etc/gitweb.conf, /etc/gitweb-common.conf,
10       $GITWEBDIR/gitweb_config.perl
11

DESCRIPTION

13       The gitweb CGI script for viewing Git repositories over the web uses a
14       perl script fragment as its configuration file. You can set variables
15       using "our $variable = value"; text from a "#" character until the end
16       of a line is ignored. See perlsyn(1) for details.
17
18       An example:
19
20           # gitweb configuration file for http://git.example.org
21           #
22           our $projectroot = "/srv/git"; # FHS recommendation
23           our $site_name = 'Example.org >> Repos';
24
25
26       The configuration file is used to override the default settings that
27       were built into gitweb at the time the gitweb.cgi script was generated.
28
29       While one could just alter the configuration settings in the gitweb CGI
30       itself, those changes would be lost upon upgrade. Configuration
31       settings might also be placed into a file in the same directory as the
32       CGI script with the default name gitweb_config.perl — allowing one to
33       have multiple gitweb instances with different configurations by the use
34       of symlinks.
35
36       Note that some configuration can be controlled on per-repository rather
37       than gitweb-wide basis: see "Per-repository gitweb configuration"
38       subsection on gitweb(1) manpage.
39

DISCUSSION

41       Gitweb reads configuration data from the following sources in the
42       following order:
43
44       ·   built-in values (some set during build stage),
45
46       ·   common system-wide configuration file (defaults to
47           /etc/gitweb-common.conf),
48
49       ·   either per-instance configuration file (defaults to
50           gitweb_config.perl in the same directory as the installed gitweb),
51           or if it does not exists then fallback system-wide configuration
52           file (defaults to /etc/gitweb.conf).
53
54       Values obtained in later configuration files override values obtained
55       earlier in the above sequence.
56
57       Locations of the common system-wide configuration file, the fallback
58       system-wide configuration file and the per-instance configuration file
59       are defined at compile time using build-time Makefile configuration
60       variables, respectively GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and
61       GITWEB_CONFIG.
62
63       You can also override locations of gitweb configuration files during
64       runtime by setting the following environment variables:
65       GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG to a
66       non-empty value.
67
68       The syntax of the configuration files is that of Perl, since these
69       files are handled by sourcing them as fragments of Perl code (the
70       language that gitweb itself is written in). Variables are typically set
71       using the our qualifier (as in "our $variable = <value>;") to avoid
72       syntax errors if a new version of gitweb no longer uses a variable and
73       therefore stops declaring it.
74
75       You can include other configuration file using read_config_file()
76       subroutine. For example, one might want to put gitweb configuration
77       related to access control for viewing repositories via Gitolite (one of
78       Git repository management tools) in a separate file, e.g. in
79       /etc/gitweb-gitolite.conf. To include it, put
80
81           read_config_file("/etc/gitweb-gitolite.conf");
82
83
84       somewhere in gitweb configuration file used, e.g. in per-installation
85       gitweb configuration file. Note that read_config_file() checks itself
86       that the file it reads exists, and does nothing if it is not found. It
87       also handles errors in included file.
88
89       The default configuration with no configuration file at all may work
90       perfectly well for some installations. Still, a configuration file is
91       useful for customizing or tweaking the behavior of gitweb in many ways,
92       and some optional features will not be present unless explicitly
93       enabled using the configurable %features variable (see also
94       "Configuring gitweb features" section below).
95

CONFIGURATION VARIABLES

97       Some configuration variables have their default values (embedded in the
98       CGI script) set during building gitweb — if that is the case, this fact
99       is put in their description. See gitweb’s INSTALL file for instructions
100       on building and installing gitweb.
101
102   Location of repositories
103       The configuration variables described below control how gitweb finds
104       Git repositories, and how repositories are displayed and accessed.
105
106       See also "Repositories" and later subsections in gitweb(1) manpage.
107
108       $projectroot
109           Absolute filesystem path which will be prepended to project path;
110           the path to repository is $projectroot/$project. Set to
111           $GITWEB_PROJECTROOT during installation. This variable has to be
112           set correctly for gitweb to find repositories.
113
114           For example, if $projectroot is set to "/srv/git" by putting the
115           following in gitweb config file:
116
117               our $projectroot = "/srv/git";
118
119           then
120
121               http://git.example.com/gitweb.cgi?p=foo/bar.git
122
123           and its path_info based equivalent
124
125               http://git.example.com/gitweb.cgi/foo/bar.git
126
127           will map to the path /srv/git/foo/bar.git on the filesystem.
128
129       $projects_list
130           Name of a plain text file listing projects, or a name of directory
131           to be scanned for projects.
132
133           Project list files should list one project per line, with each line
134           having the following format
135
136               <URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
137
138           The default value of this variable is determined by the GITWEB_LIST
139           makefile variable at installation time. If this variable is empty,
140           gitweb will fall back to scanning the $projectroot directory for
141           repositories.
142
143       $project_maxdepth
144           If $projects_list variable is unset, gitweb will recursively scan
145           filesystem for Git repositories. The $project_maxdepth is used to
146           limit traversing depth, relative to $projectroot (starting point);
147           it means that directories which are further from $projectroot than
148           $project_maxdepth will be skipped.
149
150           It is purely performance optimization, originally intended for
151           MacOS X, where recursive directory traversal is slow. Gitweb
152           follows symbolic links, but it detects cycles, ignoring any
153           duplicate files and directories.
154
155           The default value of this variable is determined by the build-time
156           configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to
157           2007.
158
159       $export_ok
160           Show repository only if this file exists (in repository). Only
161           effective if this variable evaluates to true. Can be set when
162           building gitweb by setting GITWEB_EXPORT_OK. This path is relative
163           to GIT_DIR. git-daemon[1] uses git-daemon-export-ok, unless started
164           with --export-all. By default this variable is not set, which means
165           that this feature is turned off.
166
167       $export_auth_hook
168           Function used to determine which repositories should be shown. This
169           subroutine should take one parameter, the full path to a project,
170           and if it returns true, that project will be included in the
171           projects list and can be accessed through gitweb as long as it
172           fulfills the other requirements described by $export_ok,
173           $projects_list, and $projects_maxdepth. Example:
174
175               our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
176
177           though the above might be done by using $export_ok instead
178
179               our $export_ok = "git-daemon-export-ok";
180
181           If not set (default), it means that this feature is disabled.
182
183           See also more involved example in "Controlling access to Git
184           repositories" subsection on gitweb(1) manpage.
185
186       $strict_export
187           Only allow viewing of repositories also shown on the overview page.
188           This for example makes $export_ok file decide if repository is
189           available and not only if it is shown. If $projects_list points to
190           file with list of project, only those repositories listed would be
191           available for gitweb. Can be set during building gitweb via
192           GITWEB_STRICT_EXPORT. By default this variable is not set, which
193           means that you can directly access those repositories that are
194           hidden from projects list page (e.g. the are not listed in the
195           $projects_list file).
196
197   Finding files
198       The following configuration variables tell gitweb where to find files.
199       The values of these variables are paths on the filesystem.
200
201       $GIT
202           Core git executable to use. By default set to $GIT_BINDIR/git,
203           which in turn is by default set to $(bindir)/git. If you use Git
204           installed from a binary package, you should usually set this to
205           "/usr/bin/git". This can just be "git" if your web server has a
206           sensible PATH; from security point of view it is better to use
207           absolute path to git binary. If you have multiple Git versions
208           installed it can be used to choose which one to use. Must be
209           (correctly) set for gitweb to be able to work.
210
211       $mimetypes_file
212           File to use for (filename extension based) guessing of MIME types
213           before trying /etc/mime.types.  NOTE that this path, if relative,
214           is taken as relative to the current Git repository, not to CGI
215           script. If unset, only /etc/mime.types is used (if present on
216           filesystem). If no mimetypes file is found, mimetype guessing based
217           on extension of file is disabled. Unset by default.
218
219       $highlight_bin
220           Path to the highlight executable to use (it must be the one from
221           http://www.andre-simon.de due to assumptions about parameters and
222           output). By default set to highlight; set it to full path to
223           highlight executable if it is not installed on your web server’s
224           PATH. Note that highlight feature must be set for gitweb to
225           actually use syntax highlighting.
226
227           NOTE: for a file to be highlighted, its syntax type must be
228           detected and that syntax must be supported by "highlight". The
229           default syntax detection is minimal, and there are many supported
230           syntax types with no detection by default. There are three options
231           for adding syntax detection. The first and second priority are
232           %highlight_basename and %highlight_ext, which detect based on
233           basename (the full filename, for example "Makefile") and extension
234           (for example "sh"). The keys of these hashes are the basename and
235           extension, respectively, and the value for a given key is the name
236           of the syntax to be passed via --syntax <syntax> to "highlight".
237           The last priority is the "highlight" configuration of Shebang
238           regular expressions to detect the language based on the first line
239           in the file, (for example, matching the line "#!/bin/bash"). See
240           the highlight documentation and the default config at
241           /etc/highlight/filetypes.conf for more details.
242
243           For example if repositories you are hosting use "phtml" extension
244           for PHP files, and you want to have correct syntax-highlighting for
245           those files, you can add the following to gitweb configuration:
246
247               our %highlight_ext;
248               $highlight_ext{'phtml'} = 'php';
249
250
251   Links and their targets
252       The configuration variables described below configure some of gitweb
253       links: their target and their look (text or image), and where to find
254       page prerequisites (stylesheet, favicon, images, scripts). Usually they
255       are left at their default values, with the possible exception of
256       @stylesheets variable.
257
258       @stylesheets
259           List of URIs of stylesheets (relative to the base URI of a page).
260           You might specify more than one stylesheet, for example to use
261           "gitweb.css" as base with site specific modifications in a separate
262           stylesheet to make it easier to upgrade gitweb. For example, you
263           can add a site stylesheet by putting
264
265               push @stylesheets, "gitweb-site.css";
266
267           in the gitweb config file. Those values that are relative paths are
268           relative to base URI of gitweb.
269
270           This list should contain the URI of gitweb’s standard stylesheet.
271           The default URI of gitweb stylesheet can be set at build time using
272           the GITWEB_CSS makefile variable. Its default value is
273           static/gitweb.css (or static/gitweb.min.css if the CSSMIN variable
274           is defined, i.e. if CSS minifier is used during build).
275
276           Note: there is also a legacy $stylesheet configuration variable,
277           which was used by older gitweb. If $stylesheet variable is defined,
278           only CSS stylesheet given by this variable is used by gitweb.
279
280       $logo
281           Points to the location where you put git-logo.png on your web
282           server, or to be more the generic URI of logo, 72x27 size). This
283           image is displayed in the top right corner of each gitweb page and
284           used as a logo for the Atom feed. Relative to the base URI of
285           gitweb (as a path). Can be adjusted when building gitweb using
286           GITWEB_LOGO variable By default set to static/git-logo.png.
287
288       $favicon
289           Points to the location where you put git-favicon.png on your web
290           server, or to be more the generic URI of favicon, which will be
291           served as "image/png" type. Web browsers that support favicons
292           (website icons) may display them in the browser’s URL bar and next
293           to the site name in bookmarks. Relative to the base URI of gitweb.
294           Can be adjusted at build time using GITWEB_FAVICON variable. By
295           default set to static/git-favicon.png.
296
297       $javascript
298           Points to the location where you put gitweb.js on your web server,
299           or to be more generic the URI of JavaScript code used by gitweb.
300           Relative to the base URI of gitweb. Can be set at build time using
301           the GITWEB_JS build-time configuration variable.
302
303           The default value is either static/gitweb.js, or
304           static/gitweb.min.js if the JSMIN build variable was defined, i.e.
305           if JavaScript minifier was used at build time.  Note that this
306           single file is generated from multiple individual JavaScript
307           "modules".
308
309       $home_link
310           Target of the home link on the top of all pages (the first part of
311           view "breadcrumbs"). By default it is set to the absolute URI of a
312           current page (to the value of $my_uri variable, or to "/" if
313           $my_uri is undefined or is an empty string).
314
315       $home_link_str
316           Label for the "home link" at the top of all pages, leading to
317           $home_link (usually the main gitweb page, which contains the
318           projects list). It is used as the first component of gitweb’s
319           "breadcrumb trail": <home link> / <project> / <action>. Can be set
320           at build time using the GITWEB_HOME_LINK_STR variable. By default
321           it is set to "projects", as this link leads to the list of
322           projects. Another popular choice is to set it to the name of site.
323           Note that it is treated as raw HTML so it should not be set from
324           untrusted sources.
325
326       @extra_breadcrumbs
327           Additional links to be added to the start of the breadcrumb trail
328           before the home link, to pages that are logically "above" the
329           gitweb projects list, such as the organization and department which
330           host the gitweb server. Each element of the list is a reference to
331           an array, in which element 0 is the link text (equivalent to
332           $home_link_str) and element 1 is the target URL (equivalent to
333           $home_link).
334
335           For example, the following setting produces a breadcrumb trail like
336           "home / dev / projects / ..." where "projects" is the home link.
337
338                   our @extra_breadcrumbs = (
339                     [ 'home' => 'https://www.example.org/' ],
340                     [ 'dev'  => 'https://dev.example.org/' ],
341                   );
342
343
344       $logo_url, $logo_label
345           URI and label (title) for the Git logo link (or your site logo, if
346           you chose to use different logo image). By default, these both
347           refer to Git homepage, https://git-scm.com; in the past, they
348           pointed to Git documentation at https://www.kernel.org.
349
350   Changing gitweb’s look
351       You can adjust how pages generated by gitweb look using the variables
352       described below. You can change the site name, add common headers and
353       footers for all pages, and add a description of this gitweb
354       installation on its main page (which is the projects list page), etc.
355
356       $site_name
357           Name of your site or organization, to appear in page titles. Set it
358           to something descriptive for clearer bookmarks etc. If this
359           variable is not set or is, then gitweb uses the value of the
360           SERVER_NAME CGI environment variable, setting site name to
361           "$SERVER_NAME Git", or "Untitled Git" if this variable is not set
362           (e.g. if running gitweb as standalone script).
363
364           Can be set using the GITWEB_SITENAME at build time. Unset by
365           default.
366
367       $site_html_head_string
368           HTML snippet to be included in the <head> section of each page. Can
369           be set using GITWEB_SITE_HTML_HEAD_STRING at build time. No default
370           value.
371
372       $site_header
373           Name of a file with HTML to be included at the top of each page.
374           Relative to the directory containing the gitweb.cgi script. Can be
375           set using GITWEB_SITE_HEADER at build time. No default value.
376
377       $site_footer
378           Name of a file with HTML to be included at the bottom of each page.
379           Relative to the directory containing the gitweb.cgi script. Can be
380           set using GITWEB_SITE_FOOTER at build time. No default value.
381
382       $home_text
383           Name of a HTML file which, if it exists, is included on the gitweb
384           projects overview page ("projects_list" view). Relative to the
385           directory containing the gitweb.cgi script. Default value can be
386           adjusted during build time using GITWEB_HOMETEXT variable. By
387           default set to indextext.html.
388
389       $projects_list_description_width
390           The width (in characters) of the "Description" column of the
391           projects list. Longer descriptions will be truncated (trying to cut
392           at word boundary); the full description is available in the title
393           attribute (usually shown on mouseover). The default is 25, which
394           might be too small if you use long project descriptions.
395
396       $default_projects_order
397           Default value of ordering of projects on projects list page, which
398           means the ordering used if you don’t explicitly sort projects list
399           (if there is no "o" CGI query parameter in the URL). Valid values
400           are "none" (unsorted), "project" (projects are by project name,
401           i.e. path to repository relative to $projectroot), "descr" (project
402           description), "owner", and "age" (by date of most current commit).
403
404           Default value is "project". Unknown value means unsorted.
405
406   Changing gitweb’s behavior
407       These configuration variables control internal gitweb behavior.
408
409       $default_blob_plain_mimetype
410           Default mimetype for the blob_plain (raw) view, if mimetype
411           checking doesn’t result in some other type; by default
412           "text/plain". Gitweb guesses mimetype of a file to display based on
413           extension of its filename, using $mimetypes_file (if set and file
414           exists) and /etc/mime.types files (see mime.types(5) manpage; only
415           filename extension rules are supported by gitweb).
416
417       $default_text_plain_charset
418           Default charset for text files. If this is not set, the web server
419           configuration will be used. Unset by default.
420
421       $fallback_encoding
422           Gitweb assumes this charset when a line contains non-UTF-8
423           characters. The fallback decoding is used without error checking,
424           so it can be even "utf-8". The value must be a valid encoding; see
425           the Encoding::Supported(3pm) man page for a list. The default is
426           "latin1", aka. "iso-8859-1".
427
428       @diff_opts
429           Rename detection options for git-diff and git-diff-tree. The
430           default is ('-M'); set it to ('-C') or ('-C', '-C') to also detect
431           copies, or set it to () i.e. empty list if you don’t want to have
432           renames detection.
433
434           Note that rename and especially copy detection can be quite
435           CPU-intensive. Note also that non Git tools can have problems with
436           patches generated with options mentioned above, especially when
437           they involve file copies ('-C') or criss-cross renames ('-B').
438
439   Some optional features and policies
440       Most of features are configured via %feature hash; however some of
441       extra gitweb features can be turned on and configured using variables
442       described below. This list beside configuration variables that control
443       how gitweb looks does contain variables configuring administrative side
444       of gitweb (e.g. cross-site scripting prevention; admittedly this as
445       side effect affects how "summary" pages look like, or load limiting).
446
447       @git_base_url_list
448           List of Git base URLs. These URLs are used to generate URLs
449           describing from where to fetch a project, which are shown on
450           project summary page. The full fetch URL is
451           "$git_base_url/$project", for each element of this list. You can
452           set up multiple base URLs (for example one for git:// protocol, and
453           one for http:// protocol).
454
455           Note that per repository configuration can be set in
456           $GIT_DIR/cloneurl file, or as values of multi-value gitweb.url
457           configuration variable in project config. Per-repository
458           configuration takes precedence over value composed from
459           @git_base_url_list elements and project name.
460
461           You can setup one single value (single entry/item in this list) at
462           build time by setting the GITWEB_BASE_URL build-time configuration
463           variable. By default it is set to (), i.e. an empty list. This
464           means that gitweb would not try to create project URL (to fetch)
465           from project name.
466
467       $projects_list_group_categories
468           Whether to enable the grouping of projects by category on the
469           project list page. The category of a project is determined by the
470           $GIT_DIR/category file or the gitweb.category variable in each
471           repository’s configuration. Disabled by default (set to 0).
472
473       $project_list_default_category
474           Default category for projects for which none is specified. If this
475           is set to the empty string, such projects will remain uncategorized
476           and listed at the top, above categorized projects. Used only if
477           project categories are enabled, which means if
478           $projects_list_group_categories is true. By default set to ""
479           (empty string).
480
481       $prevent_xss
482           If true, some gitweb features are disabled to prevent content in
483           repositories from launching cross-site scripting (XSS) attacks. Set
484           this to true if you don’t trust the content of your repositories.
485           False by default (set to 0).
486
487       $maxload
488           Used to set the maximum load that we will still respond to gitweb
489           queries. If the server load exceeds this value then gitweb will
490           return "503 Service Unavailable" error. The server load is taken to
491           be 0 if gitweb cannot determine its value. Currently it works only
492           on Linux, where it uses /proc/loadavg; the load there is the number
493           of active tasks on the system — processes that are actually running
494           — averaged over the last minute.
495
496           Set $maxload to undefined value (undef) to turn this feature off.
497           The default value is 300.
498
499       $omit_age_column
500           If true, omit the column with date of the most current commit on
501           the projects list page. It can save a bit of I/O and a fork per
502           repository.
503
504       $omit_owner
505           If true prevents displaying information about repository owner.
506
507       $per_request_config
508           If this is set to code reference, it will be run once for each
509           request. You can set parts of configuration that change per session
510           this way. For example, one might use the following code in a gitweb
511           configuration file
512
513               our $per_request_config = sub {
514                       $ENV{GL_USER} = $cgi->remote_user || "gitweb";
515               };
516
517           If $per_request_config is not a code reference, it is interpreted
518           as boolean value. If it is true gitweb will process config files
519           once per request, and if it is false gitweb will process config
520           files only once, each time it is executed. True by default (set to
521           1).
522
523           NOTE: $my_url, $my_uri, and $base_url are overwritten with their
524           default values before every request, so if you want to change them,
525           be sure to set this variable to true or a code reference effecting
526           the desired changes.
527
528           This variable matters only when using persistent web environments
529           that serve multiple requests using single gitweb instance, like
530           mod_perl, FastCGI or Plackup.
531
532   Other variables
533       Usually you should not need to change (adjust) any of configuration
534       variables described below; they should be automatically set by gitweb
535       to correct value.
536
537       $version
538           Gitweb version, set automatically when creating gitweb.cgi from
539           gitweb.perl. You might want to modify it if you are running
540           modified gitweb, for example
541
542               our $version .= " with caching";
543
544           if you run modified version of gitweb with caching support. This
545           variable is purely informational, used e.g. in the "generator" meta
546           header in HTML header.
547
548       $my_url, $my_uri
549           Full URL and absolute URL of the gitweb script; in earlier versions
550           of gitweb you might have need to set those variables, but now there
551           should be no need to do it. See $per_request_config if you need to
552           set them still.
553
554       $base_url
555           Base URL for relative URLs in pages generated by gitweb, (e.g.
556           $logo, $favicon, @stylesheets if they are relative URLs), needed
557           and used <base href="$base_url"> only for URLs with nonempty
558           PATH_INFO. Usually gitweb sets its value correctly, and there is no
559           need to set this variable, e.g. to $my_uri or "/". See
560           $per_request_config if you need to override it anyway.
561

CONFIGURING GITWEB FEATURES

563       Many gitweb features can be enabled (or disabled) and configured using
564       the %feature hash. Names of gitweb features are keys of this hash.
565
566       Each %feature hash element is a hash reference and has the following
567       structure:
568
569           "<feature_name>" => {
570                   "sub" => <feature-sub (subroutine)>,
571                   "override" => <allow-override (boolean)>,
572                   "default" => [ <options>... ]
573           },
574
575
576       Some features cannot be overridden per project. For those features the
577       structure of appropriate %feature hash element has a simpler form:
578
579           "<feature_name>" => {
580                   "override" => 0,
581                   "default" => [ <options>... ]
582           },
583
584
585       As one can see it lacks the 'sub' element.
586
587       The meaning of each part of feature configuration is described below:
588
589       default
590           List (array reference) of feature parameters (if there are any),
591           used also to toggle (enable or disable) given feature.
592
593           Note that it is currently always an array reference, even if
594           feature doesn’t accept any configuration parameters, and 'default'
595           is used only to turn it on or off. In such case you turn feature on
596           by setting this element to [1], and torn it off by setting it to
597           [0]. See also the passage about the "blame" feature in the
598           "Examples" section.
599
600           To disable features that accept parameters (are configurable), you
601           need to set this element to empty list i.e.  [].
602
603       override
604           If this field has a true value then the given feature is
605           overridable, which means that it can be configured (or
606           enabled/disabled) on a per-repository basis.
607
608           Usually given "<feature>" is configurable via the gitweb.<feature>
609           config variable in the per-repository Git configuration file.
610
611           Note that no feature is overridable by default.
612
613       sub
614           Internal detail of implementation. What is important is that if
615           this field is not present then per-repository override for given
616           feature is not supported.
617
618           You wouldn’t need to ever change it in gitweb config file.
619
620   Features in %feature
621       The gitweb features that are configurable via %feature hash are listed
622       below. This should be a complete list, but ultimately the authoritative
623       and complete list is in gitweb.cgi source code, with features described
624       in the comments.
625
626       blame
627           Enable the "blame" and "blame_incremental" blob views, showing for
628           each line the last commit that modified it; see git-blame(1). This
629           can be very CPU-intensive and is therefore disabled by default.
630
631           This feature can be configured on a per-repository basis via
632           repository’s gitweb.blame configuration variable (boolean).
633
634       snapshot
635           Enable and configure the "snapshot" action, which allows user to
636           download a compressed archive of any tree or commit, as produced by
637           git-archive(1) and possibly additionally compressed. This can
638           potentially generate high traffic if you have large project.
639
640           The value of 'default' is a list of names of snapshot formats,
641           defined in %known_snapshot_formats hash, that you wish to offer.
642           Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
643           compressed tar archive) and "zip"; please consult gitweb sources
644           for a definitive list. By default only "tgz" is offered.
645
646           This feature can be configured on a per-repository basis via
647           repository’s gitweb.snapshot configuration variable, which contains
648           a comma separated list of formats or "none" to disable snapshots.
649           Unknown values are ignored.
650
651       grep
652           Enable grep search, which lists the files in currently selected
653           tree (directory) containing the given string; see git-grep(1). This
654           can be potentially CPU-intensive, of course. Enabled by default.
655
656           This feature can be configured on a per-repository basis via
657           repository’s gitweb.grep configuration variable (boolean).
658
659       pickaxe
660           Enable the so called pickaxe search, which will list the commits
661           that introduced or removed a given string in a file. This can be
662           practical and quite faster alternative to "blame" action, but it is
663           still potentially CPU-intensive. Enabled by default.
664
665           The pickaxe search is described in git-log(1) (the description of
666           -S<string> option, which refers to pickaxe entry in gitdiffcore(7)
667           for more details).
668
669           This feature can be configured on a per-repository basis by setting
670           repository’s gitweb.pickaxe configuration variable (boolean).
671
672       show-sizes
673           Enable showing size of blobs (ordinary files) in a "tree" view, in
674           a separate column, similar to what ls -l does; see description of
675           -l option in git-ls-tree(1) manpage. This costs a bit of I/O.
676           Enabled by default.
677
678           This feature can be configured on a per-repository basis via
679           repository’s gitweb.showSizes configuration variable (boolean).
680
681       patches
682           Enable and configure "patches" view, which displays list of commits
683           in email (plain text) output format; see also git-format-patch(1).
684           The value is the maximum number of patches in a patchset generated
685           in "patches" view. Set the default field to a list containing
686           single item of or to an empty list to disable patch view, or to a
687           list containing a single negative number to remove any limit.
688           Default value is 16.
689
690           This feature can be configured on a per-repository basis via
691           repository’s gitweb.patches configuration variable (integer).
692
693       avatar
694           Avatar support. When this feature is enabled, views such as
695           "shortlog" or "commit" will display an avatar associated with the
696           email of each committer and author.
697
698           Currently available providers are "gravatar" and "picon". Only one
699           provider at a time can be selected (default is one element list).
700           If an unknown provider is specified, the feature is disabled.  Note
701           that some providers might require extra Perl packages to be
702           installed; see gitweb/INSTALL for more details.
703
704           This feature can be configured on a per-repository basis via
705           repository’s gitweb.avatar configuration variable.
706
707           See also %avatar_size with pixel sizes for icons and avatars
708           ("default" is used for one-line like "log" and "shortlog", "double"
709           is used for two-line like "commit", "commitdiff" or "tag"). If the
710           default font sizes or lineheights are changed (e.g. via adding
711           extra CSS stylesheet in @stylesheets), it may be appropriate to
712           change these values.
713
714       highlight
715           Server-side syntax highlight support in "blob" view. It requires
716           $highlight_bin program to be available (see the description of this
717           variable in the "Configuration variables" section above), and
718           therefore is disabled by default.
719
720           This feature can be configured on a per-repository basis via
721           repository’s gitweb.highlight configuration variable (boolean).
722
723       remote_heads
724           Enable displaying remote heads (remote-tracking branches) in the
725           "heads" list. In most cases the list of remote-tracking branches is
726           an unnecessary internal private detail, and this feature is
727           therefore disabled by default.  git-instaweb(1), which is usually
728           used to browse local repositories, enables and uses this feature.
729
730           This feature can be configured on a per-repository basis via
731           repository’s gitweb.remote_heads configuration variable (boolean).
732
733       The remaining features cannot be overridden on a per project basis.
734
735       search
736           Enable text search, which will list the commits which match author,
737           committer or commit text to a given string; see the description of
738           --author, --committer and --grep options in git-log(1) manpage.
739           Enabled by default.
740
741           Project specific override is not supported.
742
743       forks
744           If this feature is enabled, gitweb considers projects in
745           subdirectories of project root (basename) to be forks of existing
746           projects. For each project $projname.git, projects in the
747           $projname/ directory and its subdirectories will not be shown in
748           the main projects list. Instead, a '+' mark is shown next to
749           $projname, which links to a "forks" view that lists all the forks
750           (all projects in $projname/ subdirectory). Additionally a "forks"
751           view for a project is linked from project summary page.
752
753           If the project list is taken from a file ($projects_list points to
754           a file), forks are only recognized if they are listed after the
755           main project in that file.
756
757           Project specific override is not supported.
758
759       actions
760           Insert custom links to the action bar of all project pages. This
761           allows you to link to third-party scripts integrating into gitweb.
762
763           The "default" value consists of a list of triplets in the form
764           ‘("<label>", "<link>", "<position>")` where "position" is the label
765           after which to insert the link, "link" is a format string where %n
766           expands to the project name, %f to the project path within the
767           filesystem (i.e. "$projectroot/$project"), %h to the current hash
768           ('h’ gitweb parameter) and ‘%b` to the current hash base ('hb’
769           gitweb parameter); ‘%%` expands to '%’.
770
771           For example, at the time this page was written, the
772           http://repo.or.cz Git hosting site set it to the following to
773           enable graphical log (using the third party tool git-browser):
774
775               $feature{'actions'}{'default'} =
776                       [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
777
778           This adds a link titled "graphiclog" after the "summary" link,
779           leading to git-browser script, passing r=<project> as a query
780           parameter.
781
782           Project specific override is not supported.
783
784       timed
785           Enable displaying how much time and how many Git commands it took
786           to generate and display each page in the page footer (at the bottom
787           of page). For example the footer might contain: "This page took
788           6.53325 seconds and 13 Git commands to generate." Disabled by
789           default.
790
791           Project specific override is not supported.
792
793       javascript-timezone
794           Enable and configure the ability to change a common time zone for
795           dates in gitweb output via JavaScript. Dates in gitweb output
796           include authordate and committerdate in "commit", "commitdiff" and
797           "log" views, and taggerdate in "tag" view. Enabled by default.
798
799           The value is a list of three values: a default time zone (for if
800           the client hasn’t selected some other time zone and saved it in a
801           cookie), a name of cookie where to store selected time zone, and a
802           CSS class used to mark up dates for manipulation. If you want to
803           turn this feature off, set "default" to empty list: [].
804
805           Typical gitweb config files will only change starting (default)
806           time zone, and leave other elements at their default values:
807
808               $feature{'javascript-timezone'}{'default'}[0] = "utc";
809
810           The example configuration presented here is guaranteed to be
811           backwards and forward compatible.
812
813           Time zone values can be "local" (for local time zone that browser
814           uses), "utc" (what gitweb uses when JavaScript or this feature is
815           disabled), or numerical time zones in the form of "+/-HHMM", such
816           as "+0200".
817
818           Project specific override is not supported.
819
820       extra-branch-refs
821           List of additional directories under "refs" which are going to be
822           used as branch refs. For example if you have a gerrit setup where
823           all branches under refs/heads/ are official, push-after-review ones
824           and branches under refs/sandbox/, refs/wip and refs/other are user
825           ones where permissions are much wider, then you might want to set
826           this variable as follows:
827
828               $feature{'extra-branch-refs'}{'default'} =
829                       ['sandbox', 'wip', 'other'];
830
831           This feature can be configured on per-repository basis after
832           setting $feature{extra-branch-refs}{override} to true, via
833           repository’s gitweb.extraBranchRefs configuration variable, which
834           contains a space separated list of refs. An example:
835
836               [gitweb]
837                       extraBranchRefs = sandbox wip other
838
839           The gitweb.extraBranchRefs is actually a multi-valued configuration
840           variable, so following example is also correct and the result is
841           the same as of the snippet above:
842
843               [gitweb]
844                       extraBranchRefs = sandbox
845                       extraBranchRefs = wip other
846
847           It is an error to specify a ref that does not pass "git
848           check-ref-format" scrutiny. Duplicated values are filtered.
849

EXAMPLES

851       To enable blame, pickaxe search, and snapshot support (allowing
852       "tar.gz" and "zip" snapshots), while allowing individual projects to
853       turn them off, put the following in your GITWEB_CONFIG file:
854
855           $feature{'blame'}{'default'} = [1];
856           $feature{'blame'}{'override'} = 1;
857
858           $feature{'pickaxe'}{'default'} = [1];
859           $feature{'pickaxe'}{'override'} = 1;
860
861           $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
862           $feature{'snapshot'}{'override'} = 1;
863
864
865       If you allow overriding for the snapshot feature, you can specify which
866       snapshot formats are globally disabled. You can also add any
867       command-line options you want (such as setting the compression level).
868       For instance, you can disable Zip compressed snapshots and set gzip(1)
869       to run at level 6 by adding the following lines to your gitweb
870       configuration file:
871
872           $known_snapshot_formats{'zip'}{'disabled'} = 1;
873           $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
874

BUGS

876       Debugging would be easier if the fallback configuration file
877       (/etc/gitweb.conf) and environment variable to override its location
878       (GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. The
879       current names are kept to avoid breaking working setups.
880

ENVIRONMENT

882       The location of per-instance and system-wide configuration files can be
883       overridden using the following environment variables:
884
885       GITWEB_CONFIG
886           Sets location of per-instance configuration file.
887
888       GITWEB_CONFIG_SYSTEM
889           Sets location of fallback system-wide configuration file. This file
890           is read only if per-instance one does not exist.
891
892       GITWEB_CONFIG_COMMON
893           Sets location of common system-wide configuration file.
894

FILES

896       gitweb_config.perl
897           This is default name of per-instance configuration file. The format
898           of this file is described above.
899
900       /etc/gitweb.conf
901           This is default name of fallback system-wide configuration file.
902           This file is used only if per-instance configuration variable is
903           not found.
904
905       /etc/gitweb-common.conf
906           This is default name of common system-wide configuration file.
907

SEE ALSO

909       gitweb(1), git-instaweb(1)
910
911       gitweb/README, gitweb/INSTALL
912

GIT

914       Part of the git(1) suite
915
916
917
918Git 2.24.1                        12/10/2019                    GITWEB.CONF(5)
Impressum