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
26 were built into gitweb at the time the gitweb.cgi script was generated.
27 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 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
40 Gitweb reads configuration data from the following sources in the
41 following order:
42 • built-in values (some set during build stage),
44 • common system-wide configuration file (defaults to
46 /etc/gitweb-common.conf),
47 • 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 Values obtained in later configuration files override values obtained
54 earlier in the above sequence.
55 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 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 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 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 read_config_file("/etc/gitweb-gitolite.conf");
81 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 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
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 Location of repositories
101 The configuration variables described below control how gitweb finds
102 Git repositories, and how repositories are displayed and accessed.
103 See also "Repositories" and later subsections in gitweb(1) manpage.
105 $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 For example, if $projectroot is set to "/srv/git" by putting the
113 following in gitweb config file:
114 our $projectroot = "/srv/git";
116 then
118 http://git.example.com/gitweb.cgi?p=foo/bar.git
120 and its path_info based equivalent
122 http://git.example.com/gitweb.cgi/foo/bar.git
124 will map to the path /srv/git/foo/bar.git on the filesystem.
126 $projects_list
128 Name of a plain text file listing projects, or a name of directory
129 to be scanned for projects.
130 Project list files should list one project per line, with each line
132 having the following format
133 <URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
135 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 $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 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 The default value of this variable is determined by the build-time
154 configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to
155 2007.
156 $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 $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 our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
174 though the above might be done by using $export_ok instead
176 our $export_ok = "git-daemon-export-ok";
178 If not set (default), it means that this feature is disabled.
180 See also more involved example in "Controlling access to Git
182 repositories" subsection on gitweb(1) manpage.
183 $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 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 $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 $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 $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 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 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 our %highlight_ext;
246 $highlight_ext{'phtml'} = 'php';
247 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 @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 push @stylesheets, "gitweb-site.css";
263 in the gitweb config file. Those values that are relative paths are
265 relative to base URI of gitweb.
266 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 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 $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 $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 $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 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 $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 $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 @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 For example, the following setting produces a breadcrumb trail like
333 "home / dev / projects / ..." where "projects" is the home link.
334 our @extra_breadcrumbs = (
336 [ 'home' => 'https://www.example.org/' ],
337 [ 'dev' => 'https://dev.example.org/' ],
338 );
339 $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 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 $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 Can be set using the GITWEB_SITENAME at build time. Unset by
361 default.
362 $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 $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 $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 $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 $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 $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 Default value is "project". Unknown value means unsorted.
401 Changing gitweb’s behavior
403 These configuration variables control internal gitweb behavior.
404 $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 $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 $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 @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 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 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 @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 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 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 $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 $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 $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 $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 Set $maxload to undefined value (undef) to turn this feature off.
493 The default value is 300.
494 $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 $omit_owner
501 If true prevents displaying information about repository owner.
502 $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 our $per_request_config = sub {
510 $ENV{GL_USER} = $cgi->remote_user || "gitweb";
511 };
512 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 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 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 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 $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 our $version .= " with caching";
539 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 $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 $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
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 Each %feature hash element is a hash reference and has the following
563 structure:
564 "<feature_name>" => {
566 "sub" => <feature-sub (subroutine)>,
567 "override" => <allow-override (boolean)>,
568 "default" => [ <options>... ]
569 },
570 Some features cannot be overridden per project. For those features the
572 structure of appropriate %feature hash element has a simpler form:
573 "<feature_name>" => {
575 "override" => 0,
576 "default" => [ <options>... ]
577 },
578 As one can see it lacks the 'sub' element.
580 The meaning of each part of feature configuration is described below:
582 default
584 List (array reference) of feature parameters (if there are any),
585 used also to toggle (enable or disable) given feature.
586 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 To disable features that accept parameters (are configurable), you
595 need to set this element to empty list i.e. [].
596 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 Usually given "<feature>" is configurable via the gitweb.<feature>
603 config variable in the per-repository Git configuration file.
604 Note that no feature is overridable by default.
606 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 You wouldn’t need to ever change it in gitweb config file.
613 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 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 This feature can be configured on a per-repository basis via
626 repository’s gitweb.blame configuration variable (boolean).
627 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 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 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 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 This feature can be configured on a per-repository basis via
651 repository’s gitweb.grep configuration variable (boolean).
652 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 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 This feature can be configured on a per-repository basis by setting
664 repository’s gitweb.pickaxe configuration variable (boolean).
665 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 This feature can be configured on a per-repository basis via
673 repository’s gitweb.showSizes configuration variable (boolean).
674 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 This feature can be configured on a per-repository basis via
685 repository’s gitweb.patches configuration variable (integer).
686 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 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 This feature can be configured on a per-repository basis via
699 repository’s gitweb.avatar configuration variable.
700 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 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 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 This feature can be configured on a per-repository basis via
725 repository’s gitweb.highlight configuration variable (boolean).
726 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 This feature can be configured on a per-repository basis via
735 repository’s gitweb.remote_heads configuration variable (boolean).
736 The remaining features cannot be overridden on a per project basis.
738 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 Project specific override is not supported.
746 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 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 Project specific override is not supported.
762 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 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 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 $feature{'actions'}{'default'} =
780 [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
781 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 Project specific override is not supported.
787 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 Project specific override is not supported.
796 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 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 Typical gitweb config files will only change starting (default)
810 time zone, and leave other elements at their default values:
811 $feature{'javascript-timezone'}{'default'}[0] = "utc";
813 The example configuration presented here is guaranteed to be
815 backwards and forward compatible.
816 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 Project specific override is not supported.
823 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 $feature{'extra-branch-refs'}{'default'} =
833 ['sandbox', 'wip', 'other'];
834 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 [gitweb]
841 extraBranchRefs = sandbox wip other
842 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 [gitweb]
848 extraBranchRefs = sandbox
849 extraBranchRefs = wip other
850 It is an error to specify a ref that does not pass "git
852 check-ref-format" scrutiny. Duplicated values are filtered.
853
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 $feature{'blame'}{'default'} = [1];
860 $feature{'blame'}{'override'} = 1;
861 $feature{'pickaxe'}{'default'} = [1];
863 $feature{'pickaxe'}{'override'} = 1;
864 $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
866 $feature{'snapshot'}{'override'} = 1;
867 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 $known_snapshot_formats{'zip'}{'disabled'} = 1;
876 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
877
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
885 The location of per-instance and system-wide configuration files can be
886 overridden using the following environment variables:
887 GITWEB_CONFIG
889 Sets location of per-instance configuration file.
890 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 GITWEB_CONFIG_COMMON
896 Sets location of common system-wide configuration file.
897
899 gitweb_config.perl
900 This is default name of per-instance configuration file. The format
901 of this file is described above.
902 /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 /etc/gitweb-common.conf
909 This is default name of common system-wide configuration file.
910
912 gitweb(1), git-instaweb(1)
913 gitweb/README, gitweb/INSTALL
915
917 Part of the git(1) suite
918Git 2.39.1 2023-01-13 GITWEB.CONF(5)