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       The configuration file is used to override the default settings that
26       were built into gitweb at the time the gitweb.cgi script was generated.
27
28       While one could just alter the configuration settings in the gitweb CGI
29       itself, those changes would be lost upon upgrade. Configuration
30       settings might also be placed into a file in the same directory as the
31       CGI script with the default name gitweb_config.perl — allowing one to
32       have multiple gitweb instances with different configurations by the use
33       of symlinks.
34
35       Note that some configuration can be controlled on per-repository rather
36       than gitweb-wide basis: see "Per-repository gitweb configuration"
37       subsection on gitweb(1) manpage.
38

DISCUSSION

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

CONFIGURATION VARIABLES

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

CONFIGURING GITWEB FEATURES

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

EXAMPLES

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

BUGS

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

ENVIRONMENT

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

FILES

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

SEE ALSO

912       gitweb(1), git-instaweb(1)
913
914       gitweb/README, gitweb/INSTALL
915

GIT

917       Part of the git(1) suite
918
919
920
921Git 2.36.1                        2022-05-05                    GITWEB.CONF(5)
Impressum