1GITWEB.CONF(5) Git Manual GITWEB.CONF(5)
2
6 gitweb.conf - Gitweb (Git web interface) configuration file
7
9 /etc/gitweb.conf, /etc/gitweb-common.conf,
10 $GITWEBDIR/gitweb_config.perl
11
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 An example:
19 # gitweb configuration file for http://git.example.org
21 #
22 our $projectroot = "/srv/git"; # FHS recommendation
23 our $site_name = 'Example.org >> Repos';
24 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 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 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
41 Gitweb reads configuration data from the following sources in the
42 following order:
43 · built-in values (some set during build stage),
45 · common system-wide configuration file (defaults to
47 /etc/gitweb-common.conf),
48 · 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 Values obtained in later configuration files override values obtained
55 earlier in the above sequence.
56 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 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 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 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 read_config_file("/etc/gitweb-gitolite.conf");
82 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 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
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 Location of repositories
103 The configuration variables described below control how gitweb finds
104 Git repositories, and how repositories are displayed and accessed.
105 See also "Repositories" and later subsections in gitweb(1) manpage.
107 $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 For example, if $projectroot is set to "/srv/git" by putting the
115 following in gitweb config file:
116 our $projectroot = "/srv/git";
118 then
120 http://git.example.com/gitweb.cgi?p=foo/bar.git
122 and its path_info based equivalent
124 http://git.example.com/gitweb.cgi/foo/bar.git
126 will map to the path /srv/git/foo/bar.git on the filesystem.
128 $projects_list
130 Name of a plain text file listing projects, or a name of directory
131 to be scanned for projects.
132 Project list files should list one project per line, with each line
134 having the following format
135 <URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
137 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 $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 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 The default value of this variable is determined by the build-time
156 configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to
157 2007.
158 $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 $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 our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
176 though the above might be done by using $export_ok instead
178 our $export_ok = "git-daemon-export-ok";
180 If not set (default), it means that this feature is disabled.
182 See also more involved example in "Controlling access to Git
184 repositories" subsection on gitweb(1) manpage.
185 $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 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 $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 $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 $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 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 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 our %highlight_ext;
248 $highlight_ext{'phtml'} = 'php';
249 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 @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 push @stylesheets, "gitweb-site.css";
266 in the gitweb config file. Those values that are relative paths are
268 relative to base URI of gitweb.
269 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 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 $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 $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 $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 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 $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 $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 @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 For example, the following setting produces a breadcrumb trail like
336 "home / dev / projects / ..." where "projects" is the home link.
337 our @extra_breadcrumbs = (
339 [ 'home' => 'https://www.example.org/' ],
340 [ 'dev' => 'https://dev.example.org/' ],
341 );
342 $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 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 $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 Can be set using the GITWEB_SITENAME at build time. Unset by
365 default.
366 $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 $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 $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 $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 $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 $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 Default value is "project". Unknown value means unsorted.
405 Changing gitweb’s behavior
407 These configuration variables control internal gitweb behavior.
408 $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 $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 $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 @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 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 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 @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 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 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 $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 $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 $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 $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 Set $maxload to undefined value (undef) to turn this feature off.
497 The default value is 300.
498 $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 $omit_owner
505 If true prevents displaying information about repository owner.
506 $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 our $per_request_config = sub {
514 $ENV{GL_USER} = $cgi->remote_user || "gitweb";
515 };
516 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 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 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 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 $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 our $version .= " with caching";
543 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 $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 $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
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 Each %feature hash element is a hash reference and has the following
567 structure:
568 "<feature_name>" => {
570 "sub" => <feature-sub (subroutine)>,
571 "override" => <allow-override (boolean)>,
572 "default" => [ <options>... ]
573 },
574 Some features cannot be overridden per project. For those features the
577 structure of appropriate %feature hash element has a simpler form:
578 "<feature_name>" => {
580 "override" => 0,
581 "default" => [ <options>... ]
582 },
583 As one can see it lacks the 'sub' element.
586 The meaning of each part of feature configuration is described below:
588 default
590 List (array reference) of feature parameters (if there are any),
591 used also to toggle (enable or disable) given feature.
592 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 To disable features that accept parameters (are configurable), you
601 need to set this element to empty list i.e. [].
602 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 Usually given "<feature>" is configurable via the gitweb.<feature>
609 config variable in the per-repository Git configuration file.
610 Note that no feature is overridable by default.
612 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 You wouldn’t need to ever change it in gitweb config file.
619 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 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 This feature can be configured on a per-repository basis via
632 repository’s gitweb.blame configuration variable (boolean).
633 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 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 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 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 This feature can be configured on a per-repository basis via
657 repository’s gitweb.grep configuration variable (boolean).
658 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 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 This feature can be configured on a per-repository basis by setting
670 repository’s gitweb.pickaxe configuration variable (boolean).
671 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 This feature can be configured on a per-repository basis via
679 repository’s gitweb.showSizes configuration variable (boolean).
680 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 This feature can be configured on a per-repository basis via
691 repository’s gitweb.patches configuration variable (integer).
692 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 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 This feature can be configured on a per-repository basis via
705 repository’s gitweb.avatar configuration variable.
706 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 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 This feature can be configured on a per-repository basis via
721 repository’s gitweb.highlight configuration variable (boolean).
722 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 This feature can be configured on a per-repository basis via
731 repository’s gitweb.remote_heads configuration variable (boolean).
732 The remaining features cannot be overridden on a per project basis.
734 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 Project specific override is not supported.
742 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 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 Project specific override is not supported.
758 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 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 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 $feature{'actions'}{'default'} =
776 [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
777 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 Project specific override is not supported.
783 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 Project specific override is not supported.
792 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 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 Typical gitweb config files will only change starting (default)
806 time zone, and leave other elements at their default values:
807 $feature{'javascript-timezone'}{'default'}[0] = "utc";
809 The example configuration presented here is guaranteed to be
811 backwards and forward compatible.
812 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 Project specific override is not supported.
819 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 $feature{'extra-branch-refs'}{'default'} =
829 ['sandbox', 'wip', 'other'];
830 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 [gitweb]
837 extraBranchRefs = sandbox wip other
838 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 [gitweb]
844 extraBranchRefs = sandbox
845 extraBranchRefs = wip other
846 It is an error to specify a ref that does not pass "git
848 check-ref-format" scrutiny. Duplicated values are filtered.
849
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 $feature{'blame'}{'default'} = [1];
856 $feature{'blame'}{'override'} = 1;
857 $feature{'pickaxe'}{'default'} = [1];
859 $feature{'pickaxe'}{'override'} = 1;
860 $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
862 $feature{'snapshot'}{'override'} = 1;
863 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 $known_snapshot_formats{'zip'}{'disabled'} = 1;
873 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
874
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
882 The location of per-instance and system-wide configuration files can be
883 overridden using the following environment variables:
884 GITWEB_CONFIG
886 Sets location of per-instance configuration file.
887 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 GITWEB_CONFIG_COMMON
893 Sets location of common system-wide configuration file.
894
896 gitweb_config.perl
897 This is default name of per-instance configuration file. The format
898 of this file is described above.
899 /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 /etc/gitweb-common.conf
906 This is default name of common system-wide configuration file.
907
909 gitweb(1), git-instaweb(1)
910 gitweb/README, gitweb/INSTALL
912
914 Part of the git(1) suite
915Git 2.24.1 12/10/2019 GITWEB.CONF(5)