1GITWEB.CONF(5) Git Manual GITWEB.CONF(5)
2
3
4
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
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
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
83 somewhere in gitweb configuration file used, e.g. in per-installation
84 gitweb configuration file. Note that read_config_file() checks itself
85 that the file it reads exists, and does nothing if it is not found. It
86 also handles errors in included file.
87
88 The default configuration with no configuration file at all may work
89 perfectly well for some installations. Still, a configuration file is
90 useful for customizing or tweaking the behavior of gitweb in many ways,
91 and some optional features will not be present unless explicitly
92 enabled using the configurable %features variable (see also
93 "Configuring gitweb features" section below).
94
96 Some configuration variables have their default values (embedded in the
97 CGI script) set during building gitweb — if that is the case, this fact
98 is put in their description. See gitweb’s INSTALL file for instructions
99 on building and installing gitweb.
100
101 Location of repositories
102 The configuration variables described below control how gitweb finds
103 Git repositories, and how repositories are displayed and accessed.
104
105 See also "Repositories" and later subsections in gitweb(1) manpage.
106
107 $projectroot
108 Absolute filesystem path which will be prepended to project path;
109 the path to repository is $projectroot/$project. Set to
110 $GITWEB_PROJECTROOT during installation. This variable has to be
111 set correctly for gitweb to find repositories.
112
113 For example, if $projectroot is set to "/srv/git" by putting the
114 following in gitweb config file:
115
116 our $projectroot = "/srv/git";
117
118 then
119
120 http://git.example.com/gitweb.cgi?p=foo/bar.git
121
122 and its path_info based equivalent
123
124 http://git.example.com/gitweb.cgi/foo/bar.git
125
126 will map to the path /srv/git/foo/bar.git on the filesystem.
127
128 $projects_list
129 Name of a plain text file listing projects, or a name of directory
130 to be scanned for projects.
131
132 Project list files should list one project per line, with each line
133 having the following format
134
135 <URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
136
137 The default value of this variable is determined by the GITWEB_LIST
138 makefile variable at installation time. If this variable is empty,
139 gitweb will fall back to scanning the $projectroot directory for
140 repositories.
141
142 $project_maxdepth
143 If $projects_list variable is unset, gitweb will recursively scan
144 filesystem for Git repositories. The $project_maxdepth is used to
145 limit traversing depth, relative to $projectroot (starting point);
146 it means that directories which are further from $projectroot than
147 $project_maxdepth will be skipped.
148
149 It is purely performance optimization, originally intended for
150 MacOS X, where recursive directory traversal is slow. Gitweb
151 follows symbolic links, but it detects cycles, ignoring any
152 duplicate files and directories.
153
154 The default value of this variable is determined by the build-time
155 configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to
156 2007.
157
158 $export_ok
159 Show repository only if this file exists (in repository). Only
160 effective if this variable evaluates to true. Can be set when
161 building gitweb by setting GITWEB_EXPORT_OK. This path is relative
162 to GIT_DIR. git-daemon[1] uses git-daemon-export-ok, unless started
163 with --export-all. By default this variable is not set, which means
164 that this feature is turned off.
165
166 $export_auth_hook
167 Function used to determine which repositories should be shown. This
168 subroutine should take one parameter, the full path to a project,
169 and if it returns true, that project will be included in the
170 projects list and can be accessed through gitweb as long as it
171 fulfills the other requirements described by $export_ok,
172 $projects_list, and $projects_maxdepth. Example:
173
174 our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
175
176 though the above might be done by using $export_ok instead
177
178 our $export_ok = "git-daemon-export-ok";
179
180 If not set (default), it means that this feature is disabled.
181
182 See also more involved example in "Controlling access to Git
183 repositories" subsection on gitweb(1) manpage.
184
185 $strict_export
186 Only allow viewing of repositories also shown on the overview page.
187 This for example makes $gitweb_export_ok file decide if repository
188 is available and not only if it is shown. If $gitweb_list points to
189 file with list of project, only those repositories listed would be
190 available for gitweb. Can be set during building gitweb via
191 GITWEB_STRICT_EXPORT. By default this variable is not set, which
192 means that you can directly access those repositories that are
193 hidden from projects list page (e.g. the are not listed in the
194 $projects_list file).
195
196 Finding files
197 The following configuration variables tell gitweb where to find files.
198 The values of these variables are paths on the filesystem.
199
200 $GIT
201 Core git executable to use. By default set to $GIT_BINDIR/git,
202 which in turn is by default set to $(bindir)/git. If you use Git
203 installed from a binary package, you should usually set this to
204 "/usr/bin/git". This can just be "git" if your web server has a
205 sensible PATH; from security point of view it is better to use
206 absolute path to git binary. If you have multiple Git versions
207 installed it can be used to choose which one to use. Must be
208 (correctly) set for gitweb to be able to work.
209
210 $mimetypes_file
211 File to use for (filename extension based) guessing of MIME types
212 before trying /etc/mime.types. NOTE that this path, if relative,
213 is taken as relative to the current Git repository, not to CGI
214 script. If unset, only /etc/mime.types is used (if present on
215 filesystem). If no mimetypes file is found, mimetype guessing based
216 on extension of file is disabled. Unset by default.
217
218 $highlight_bin
219 Path to the highlight executable to use (it must be the one from
220 http://www.andre-simon.de due to assumptions about parameters and
221 output). By default set to highlight; set it to full path to
222 highlight executable if it is not installed on your web server’s
223 PATH. Note that highlight feature must be set for gitweb to
224 actually use syntax highlighting.
225
226 NOTE: if you want to add support for new file type (supported by
227 "highlight" but not used by gitweb), you need to modify
228 %highlight_ext or %highlight_basename, depending on whether you
229 detect type of file based on extension (for example "sh") or on its
230 basename (for example "Makefile"). The keys of these hashes are
231 extension and basename, respectively, and value for given key is
232 name of syntax to be passed via --syntax <syntax> to highlighter.
233
234 For example if repositories you are hosting use "phtml" extension
235 for PHP files, and you want to have correct syntax-highlighting for
236 those files, you can add the following to gitweb configuration:
237
238 our %highlight_ext;
239 $highlight_ext{'phtml'} = 'php';
240
241
242 Links and their targets
243 The configuration variables described below configure some of gitweb
244 links: their target and their look (text or image), and where to find
245 page prerequisites (stylesheet, favicon, images, scripts). Usually they
246 are left at their default values, with the possible exception of
247 @stylesheets variable.
248
249 @stylesheets
250 List of URIs of stylesheets (relative to the base URI of a page).
251 You might specify more than one stylesheet, for example to use
252 "gitweb.css" as base with site specific modifications in a separate
253 stylesheet to make it easier to upgrade gitweb. For example, you
254 can add a site stylesheet by putting
255
256 push @stylesheets, "gitweb-site.css";
257
258 in the gitweb config file. Those values that are relative paths are
259 relative to base URI of gitweb.
260
261 This list should contain the URI of gitweb’s standard stylesheet.
262 The default URI of gitweb stylesheet can be set at build time using
263 the GITWEB_CSS makefile variable. Its default value is
264 static/gitweb.css (or static/gitweb.min.css if the CSSMIN variable
265 is defined, i.e. if CSS minifier is used during build).
266
267 Note: there is also a legacy $stylesheet configuration variable,
268 which was used by older gitweb. If $stylesheet variable is defined,
269 only CSS stylesheet given by this variable is used by gitweb.
270
271 $logo
272 Points to the location where you put git-logo.png on your web
273 server, or to be more the generic URI of logo, 72x27 size). This
274 image is displayed in the top right corner of each gitweb page and
275 used as a logo for the Atom feed. Relative to the base URI of
276 gitweb (as a path). Can be adjusted when building gitweb using
277 GITWEB_LOGO variable By default set to static/git-logo.png.
278
279 $favicon
280 Points to the location where you put git-favicon.png on your web
281 server, or to be more the generic URI of favicon, which will be
282 served as "image/png" type. Web browsers that support favicons
283 (website icons) may display them in the browser’s URL bar and next
284 to the site name in bookmarks. Relative to the base URI of gitweb.
285 Can be adjusted at build time using GITWEB_FAVICON variable. By
286 default set to static/git-favicon.png.
287
288 $javascript
289 Points to the location where you put gitweb.js on your web server,
290 or to be more generic the URI of JavaScript code used by gitweb.
291 Relative to the base URI of gitweb. Can be set at build time using
292 the GITWEB_JS build-time configuration variable.
293
294 The default value is either static/gitweb.js, or
295 static/gitweb.min.js if the JSMIN build variable was defined, i.e.
296 if JavaScript minifier was used at build time. Note that this
297 single file is generated from multiple individual JavaScript
298 "modules".
299
300 $home_link
301 Target of the home link on the top of all pages (the first part of
302 view "breadcrumbs"). By default it is set to the absolute URI of a
303 current page (to the value of $my_uri variable, or to "/" if
304 $my_uri is undefined or is an empty string).
305
306 $home_link_str
307 Label for the "home link" at the top of all pages, leading to
308 $home_link (usually the main gitweb page, which contains the
309 projects list). It is used as the first component of gitweb’s
310 "breadcrumb trail": <home link> / <project> / <action>. Can be set
311 at build time using the GITWEB_HOME_LINK_STR variable. By default
312 it is set to "projects", as this link leads to the list of
313 projects. Other popular choice it to set it to the name of site.
314
315 $logo_url, $logo_label
316 URI and label (title) for the Git logo link (or your site logo, if
317 you chose to use different logo image). By default, these both
318 refer to Git homepage, http://git-scm.com; in the past, they
319 pointed to Git documentation at http://www.kernel.org.
320
321 Changing gitweb’s look
322 You can adjust how pages generated by gitweb look using the variables
323 described below. You can change the site name, add common headers and
324 footers for all pages, and add a description of this gitweb
325 installation on its main page (which is the projects list page), etc.
326
327 $site_name
328 Name of your site or organization, to appear in page titles. Set it
329 to something descriptive for clearer bookmarks etc. If this
330 variable is not set or is, then gitweb uses the value of the
331 SERVER_NAME CGI environment variable, setting site name to
332 "$SERVER_NAME Git", or "Untitled Git" if this variable is not set
333 (e.g. if running gitweb as standalone script).
334
335 Can be set using the GITWEB_SITENAME at build time. Unset by
336 default.
337
338 $site_html_head_string
339 HTML snippet to be included in the <head> section of each page. Can
340 be set using GITWEB_SITE_HTML_HEAD_STRING at build time. No default
341 value.
342
343 $site_header
344 Name of a file with HTML to be included at the top of each page.
345 Relative to the directory containing the gitweb.cgi script. Can be
346 set using GITWEB_SITE_HEADER at build time. No default value.
347
348 $site_footer
349 Name of a file with HTML to be included at the bottom of each page.
350 Relative to the directory containing the gitweb.cgi script. Can be
351 set using GITWEB_SITE_FOOTER at build time. No default value.
352
353 $home_text
354 Name of a HTML file which, if it exists, is included on the gitweb
355 projects overview page ("projects_list" view). Relative to the
356 directory containing the gitweb.cgi script. Default value can be
357 adjusted during build time using GITWEB_HOMETEXT variable. By
358 default set to indextext.html.
359
360 $projects_list_description_width
361 The width (in characters) of the "Description" column of the
362 projects list. Longer descriptions will be truncated (trying to cut
363 at word boundary); the full description is available in the title
364 attribute (usually shown on mouseover). The default is 25, which
365 might be too small if you use long project descriptions.
366
367 $default_projects_order
368 Default value of ordering of projects on projects list page, which
369 means the ordering used if you don’t explicitly sort projects list
370 (if there is no "o" CGI query parameter in the URL). Valid values
371 are "none" (unsorted), "project" (projects are by project name,
372 i.e. path to repository relative to $projectroot), "descr" (project
373 description), "owner", and "age" (by date of most current commit).
374
375 Default value is "project". Unknown value means unsorted.
376
377 Changing gitweb’s behavior
378 These configuration variables control internal gitweb behavior.
379
380 $default_blob_plain_mimetype
381 Default mimetype for the blob_plain (raw) view, if mimetype
382 checking doesn’t result in some other type; by default
383 "text/plain". Gitweb guesses mimetype of a file to display based on
384 extension of its filename, using $mimetypes_file (if set and file
385 exists) and /etc/mime.types files (see mime.types(5) manpage; only
386 filename extension rules are supported by gitweb).
387
388 $default_text_plain_charset
389 Default charset for text files. If this is not set, the web server
390 configuration will be used. Unset by default.
391
392 $fallback_encoding
393 Gitweb assumes this charset when a line contains non-UTF-8
394 characters. The fallback decoding is used without error checking,
395 so it can be even "utf-8". The value must be a valid encoding; see
396 the Encoding::Supported(3pm) man page for a list. The default is
397 "latin1", aka. "iso-8859-1".
398
399 @diff_opts
400 Rename detection options for git-diff and git-diff-tree. The
401 default is ('-M'); set it to ('-C') or ('-C', '-C') to also detect
402 copies, or set it to () i.e. empty list if you don’t want to have
403 renames detection.
404
405 Note that rename and especially copy detection can be quite
406 CPU-intensive. Note also that non Git tools can have problems with
407 patches generated with options mentioned above, especially when
408 they involve file copies ('-C') or criss-cross renames ('-B').
409
410 Some optional features and policies
411 Most of features are configured via %feature hash; however some of
412 extra gitweb features can be turned on and configured using variables
413 described below. This list beside configuration variables that control
414 how gitweb looks does contain variables configuring administrative side
415 of gitweb (e.g. cross-site scripting prevention; admittedly this as
416 side effect affects how "summary" pages look like, or load limiting).
417
418 @git_base_url_list
419 List of Git base URLs. These URLs are used to generate URLs
420 describing from where to fetch a project, which are shown on
421 project summary page. The full fetch URL is
422 "$git_base_url/$project", for each element of this list. You can
423 set up multiple base URLs (for example one for git:// protocol, and
424 one for http:// protocol).
425
426 Note that per repository configuration can be set in
427 $GIT_DIR/cloneurl file, or as values of multi-value gitweb.url
428 configuration variable in project config. Per-repository
429 configuration takes precedence over value composed from
430 @git_base_url_list elements and project name.
431
432 You can setup one single value (single entry/item in this list) at
433 build time by setting the GITWEB_BASE_URL built-time configuration
434 variable. By default it is set to (), i.e. an empty list. This
435 means that gitweb would not try to create project URL (to fetch)
436 from project name.
437
438 $projects_list_group_categories
439 Whether to enables the grouping of projects by category on the
440 project list page. The category of a project is determined by the
441 $GIT_DIR/category file or the gitweb.category variable in each
442 repository’s configuration. Disabled by default (set to 0).
443
444 $project_list_default_category
445 Default category for projects for which none is specified. If this
446 is set to the empty string, such projects will remain uncategorized
447 and listed at the top, above categorized projects. Used only if
448 project categories are enabled, which means if
449 $projects_list_group_categories is true. By default set to ""
450 (empty string).
451
452 $prevent_xss
453 If true, some gitweb features are disabled to prevent content in
454 repositories from launching cross-site scripting (XSS) attacks. Set
455 this to true if you don’t trust the content of your repositories.
456 False by default (set to 0).
457
458 $maxload
459 Used to set the maximum load that we will still respond to gitweb
460 queries. If the server load exceeds this value then gitweb will
461 return "503 Service Unavailable" error. The server load is taken to
462 be 0 if gitweb cannot determine its value. Currently it works only
463 on Linux, where it uses /proc/loadavg; the load there is the number
464 of active tasks on the system — processes that are actually running
465 — averaged over the last minute.
466
467 Set $maxload to undefined value (undef) to turn this feature off.
468 The default value is 300.
469
470 $omit_age_column
471 If true, omit the column with date of the most current commit on
472 the projects list page. It can save a bit of I/O and a fork per
473 repository.
474
475 $omit_owner
476 If true prevents displaying information about repository owner.
477
478 $per_request_config
479 If this is set to code reference, it will be run once for each
480 request. You can set parts of configuration that change per session
481 this way. For example, one might use the following code in a gitweb
482 configuration file
483
484 our $per_request_config = sub {
485 $ENV{GL_USER} = $cgi->remote_user || "gitweb";
486 };
487
488 If $per_request_config is not a code reference, it is interpreted
489 as boolean value. If it is true gitweb will process config files
490 once per request, and if it is false gitweb will process config
491 files only once, each time it is executed. True by default (set to
492 1).
493
494 NOTE: $my_url, $my_uri, and $base_url are overwritten with their
495 default values before every request, so if you want to change them,
496 be sure to set this variable to true or a code reference effecting
497 the desired changes.
498
499 This variable matters only when using persistent web environments
500 that serve multiple requests using single gitweb instance, like
501 mod_perl, FastCGI or Plackup.
502
503 Other variables
504 Usually you should not need to change (adjust) any of configuration
505 variables described below; they should be automatically set by gitweb
506 to correct value.
507
508 $version
509 Gitweb version, set automatically when creating gitweb.cgi from
510 gitweb.perl. You might want to modify it if you are running
511 modified gitweb, for example
512
513 our $version .= " with caching";
514
515 if you run modified version of gitweb with caching support. This
516 variable is purely informational, used e.g. in the "generator" meta
517 header in HTML header.
518
519 $my_url, $my_uri
520 Full URL and absolute URL of the gitweb script; in earlier versions
521 of gitweb you might have need to set those variables, but now there
522 should be no need to do it. See $per_request_config if you need to
523 set them still.
524
525 $base_url
526 Base URL for relative URLs in pages generated by gitweb, (e.g.
527 $logo, $favicon, @stylesheets if they are relative URLs), needed
528 and used <base href="$base_url"> only for URLs with nonempty
529 PATH_INFO. Usually gitweb sets its value correctly, and there is no
530 need to set this variable, e.g. to $my_uri or "/". See
531 $per_request_config if you need to override it anyway.
532
534 Many gitweb features can be enabled (or disabled) and configured using
535 the %feature hash. Names of gitweb features are keys of this hash.
536
537 Each %feature hash element is a hash reference and has the following
538 structure:
539
540 "<feature_name>" => {
541 "sub" => <feature-sub (subroutine)>,
542 "override" => <allow-override (boolean)>,
543 "default" => [ <options>... ]
544 },
545
546
547 Some features cannot be overridden per project. For those features the
548 structure of appropriate %feature hash element has a simpler form:
549
550 "<feature_name>" => {
551 "override" => 0,
552 "default" => [ <options>... ]
553 },
554
555
556 As one can see it lacks the 'sub' element.
557
558 The meaning of each part of feature configuration is described below:
559
560 default
561 List (array reference) of feature parameters (if there are any),
562 used also to toggle (enable or disable) given feature.
563
564 Note that it is currently always an array reference, even if
565 feature doesn’t accept any configuration parameters, and 'default'
566 is used only to turn it on or off. In such case you turn feature on
567 by setting this element to [1], and torn it off by setting it to
568 [0]. See also the passage about the "blame" feature in the
569 "Examples" section.
570
571 To disable features that accept parameters (are configurable), you
572 need to set this element to empty list i.e. [].
573
574 override
575 If this field has a true value then the given feature is
576 overriddable, which means that it can be configured (or
577 enabled/disabled) on a per-repository basis.
578
579 Usually given "<feature>" is configurable via the gitweb.<feature>
580 config variable in the per-repository Git configuration file.
581
582 Note that no feature is overriddable by default.
583
584 sub
585 Internal detail of implementation. What is important is that if
586 this field is not present then per-repository override for given
587 feature is not supported.
588
589 You wouldn’t need to ever change it in gitweb config file.
590
591 Features in %feature
592 The gitweb features that are configurable via %feature hash are listed
593 below. This should be a complete list, but ultimately the authoritative
594 and complete list is in gitweb.cgi source code, with features described
595 in the comments.
596
597 blame
598 Enable the "blame" and "blame_incremental" blob views, showing for
599 each line the last commit that modified it; see git-blame(1). This
600 can be very CPU-intensive and is therefore disabled by default.
601
602 This feature can be configured on a per-repository basis via
603 repository’s gitweb.blame configuration variable (boolean).
604
605 snapshot
606 Enable and configure the "snapshot" action, which allows user to
607 download a compressed archive of any tree or commit, as produced by
608 git-archive(1) and possibly additionally compressed. This can
609 potentially generate high traffic if you have large project.
610
611 The value of 'default' is a list of names of snapshot formats,
612 defined in %known_snapshot_formats hash, that you wish to offer.
613 Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
614 compressed tar archive) and "zip"; please consult gitweb sources
615 for a definitive list. By default only "tgz" is offered.
616
617 This feature can be configured on a per-repository basis via
618 repository’s gitweb.blame configuration variable, which contains a
619 comma separated list of formats or "none" to disable snapshots.
620 Unknown values are ignored.
621
622 grep
623 Enable grep search, which lists the files in currently selected
624 tree (directory) containing the given string; see git-grep(1). This
625 can be potentially CPU-intensive, of course. Enabled by default.
626
627 This feature can be configured on a per-repository basis via
628 repository’s gitweb.grep configuration variable (boolean).
629
630 pickaxe
631 Enable the so called pickaxe search, which will list the commits
632 that introduced or removed a given string in a file. This can be
633 practical and quite faster alternative to "blame" action, but it is
634 still potentially CPU-intensive. Enabled by default.
635
636 The pickaxe search is described in git-log(1) (the description of
637 -S<string> option, which refers to pickaxe entry in gitdiffcore(7)
638 for more details).
639
640 This feature can be configured on a per-repository basis by setting
641 repository’s gitweb.pickaxe configuration variable (boolean).
642
643 show-sizes
644 Enable showing size of blobs (ordinary files) in a "tree" view, in
645 a separate column, similar to what ls -l does; see description of
646 -l option in git-ls-tree(1) manpage. This costs a bit of I/O.
647 Enabled by default.
648
649 This feature can be configured on a per-repository basis via
650 repository’s gitweb.showsizes configuration variable (boolean).
651
652 patches
653 Enable and configure "patches" view, which displays list of commits
654 in email (plain text) output format; see also git-format-patch(1).
655 The value is the maximum number of patches in a patchset generated
656 in "patches" view. Set the default field to a list containing
657 single item of or to an empty list to disable patch view, or to a
658 list containing a single negative number to remove any limit.
659 Default value is 16.
660
661 This feature can be configured on a per-repository basis via
662 repository’s gitweb.patches configuration variable (integer).
663
664 avatar
665 Avatar support. When this feature is enabled, views such as
666 "shortlog" or "commit" will display an avatar associated with the
667 email of each committer and author.
668
669 Currently available providers are "gravatar" and "picon". Only one
670 provider at a time can be selected (default is one element list).
671 If an unknown provider is specified, the feature is disabled. Note
672 that some providers might require extra Perl packages to be
673 installed; see gitweb/INSTALL for more details.
674
675 This feature can be configured on a per-repository basis via
676 repository’s gitweb.avatar configuration variable.
677
678 See also %avatar_size with pixel sizes for icons and avatars
679 ("default" is used for one-line like "log" and "shortlog", "double"
680 is used for two-line like "commit", "commitdiff" or "tag"). If the
681 default font sizes or lineheights are changed (e.g. via adding
682 extra CSS stylesheet in @stylesheets), it may be appropriate to
683 change these values.
684
685 highlight
686 Server-side syntax highlight support in "blob" view. It requires
687 $highlight_bin program to be available (see the description of this
688 variable in the "Configuration variables" section above), and
689 therefore is disabled by default.
690
691 This feature can be configured on a per-repository basis via
692 repository’s gitweb.highlight configuration variable (boolean).
693
694 remote_heads
695 Enable displaying remote heads (remote-tracking branches) in the
696 "heads" list. In most cases the list of remote-tracking branches is
697 an unnecessary internal private detail, and this feature is
698 therefore disabled by default. git-instaweb(1), which is usually
699 used to browse local repositories, enables and uses this feature.
700
701 This feature can be configured on a per-repository basis via
702 repository’s gitweb.remote_heads configuration variable (boolean).
703
704 The remaining features cannot be overridden on a per project basis.
705
706 search
707 Enable text search, which will list the commits which match author,
708 committer or commit text to a given string; see the description of
709 --author, --committer and --grep options in git-log(1) manpage.
710 Enabled by default.
711
712 Project specific override is not supported.
713
714 forks
715 If this feature is enabled, gitweb considers projects in
716 subdirectories of project root (basename) to be forks of existing
717 projects. For each project $projname.git, projects in the
718 $projname/ directory and its subdirectories will not be shown in
719 the main projects list. Instead, a '+' mark is shown next to
720 $projname, which links to a "forks" view that lists all the forks
721 (all projects in $projname/ subdirectory). Additionally a "forks"
722 view for a project is linked from project summary page.
723
724 If the project list is taken from a file ($projects_list points to
725 a file), forks are only recognized if they are listed after the
726 main project in that file.
727
728 Project specific override is not supported.
729
730 actions
731 Insert custom links to the action bar of all project pages. This
732 allows you to link to third-party scripts integrating into gitweb.
733
734 The "default" value consists of a list of triplets in the form
735 ‘("<label>", "<link>", "<position>")` where "position" is the label
736 after which to insert the link, "link" is a format string where %n
737 expands to the project name, %f to the project path within the
738 filesystem (i.e. "$projectroot/$project"), %h to the current hash
739 ('h’ gitweb parameter) and ‘%b` to the current hash base ('hb’
740 gitweb parameter); ‘%%` expands to '%’.
741
742 For example, at the time this page was written, the
743 http://repo.or.cz Git hosting site set it to the following to
744 enable graphical log (using the third party tool git-browser):
745
746 $feature{'actions'}{'default'} =
747 [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
748
749 This adds a link titled "graphiclog" after the "summary" link,
750 leading to git-browser script, passing r=<project> as a query
751 parameter.
752
753 Project specific override is not supported.
754
755 timed
756 Enable displaying how much time and how many Git commands it took
757 to generate and display each page in the page footer (at the bottom
758 of page). For example the footer might contain: "This page took
759 6.53325 seconds and 13 Git commands to generate." Disabled by
760 default.
761
762 Project specific override is not supported.
763
764 javascript-timezone
765 Enable and configure the ability to change a common timezone for
766 dates in gitweb output via JavaScript. Dates in gitweb output
767 include authordate and committerdate in "commit", "commitdiff" and
768 "log" views, and taggerdate in "tag" view. Enabled by default.
769
770 The value is a list of three values: a default timezone (for if the
771 client hasn’t selected some other timezone and saved it in a
772 cookie), a name of cookie where to store selected timezone, and a
773 CSS class used to mark up dates for manipulation. If you want to
774 turn this feature off, set "default" to empty list: [].
775
776 Typical gitweb config files will only change starting (default)
777 timezone, and leave other elements at their default values:
778
779 $feature{'javascript-timezone'}{'default'}[0] = "utc";
780
781 The example configuration presented here is guaranteed to be
782 backwards and forward compatible.
783
784 Timezone values can be "local" (for local timezone that browser
785 uses), "utc" (what gitweb uses when JavaScript or this feature is
786 disabled), or numerical timezones in the form of "+/-HHMM", such as
787 "+0200".
788
789 Project specific override is not supported.
790
792 To enable blame, pickaxe search, and snapshot support (allowing
793 "tar.gz" and "zip" snapshots), while allowing individual projects to
794 turn them off, put the following in your GITWEB_CONFIG file:
795
796 $feature{'blame'}{'default'} = [1];
797 $feature{'blame'}{'override'} = 1;
798
799 $feature{'pickaxe'}{'default'} = [1];
800 $feature{'pickaxe'}{'override'} = 1;
801
802 $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
803 $feature{'snapshot'}{'override'} = 1;
804
805 If you allow overriding for the snapshot feature, you can specify which
806 snapshot formats are globally disabled. You can also add any command
807 line options you want (such as setting the compression level). For
808 instance, you can disable Zip compressed snapshots and set gzip(1) to
809 run at level 6 by adding the following lines to your gitweb
810 configuration file:
811
812 $known_snapshot_formats{'zip'}{'disabled'} = 1;
813 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
814
816 Debugging would be easier if the fallback configuration file
817 (/etc/gitweb.conf) and environment variable to override its location
818 (GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. The
819 current names are kept to avoid breaking working setups.
820
822 The location of per-instance and system-wide configuration files can be
823 overridden using the following environment variables:
824
825 GITWEB_CONFIG
826 Sets location of per-instance configuration file.
827
828 GITWEB_CONFIG_SYSTEM
829 Sets location of fallback system-wide configuration file. This file
830 is read only if per-instance one does not exist.
831
832 GITWEB_CONFIG_COMMON
833 Sets location of common system-wide configuration file.
834
836 gitweb_config.perl
837 This is default name of per-instance configuration file. The format
838 of this file is described above.
839
840 /etc/gitweb.conf
841 This is default name of fallback system-wide configuration file.
842 This file is used only if per-instance configuration variable is
843 not found.
844
845 /etc/gitweb-common.conf
846 This is default name of common system-wide configuration file.
847
849 gitweb(1), git-instaweb(1)
850
851 gitweb/README, gitweb/INSTALL
852
854 Part of the git(1) suite
855
856
857
858Git 1.8.3.1 11/19/2018 GITWEB.CONF(5)