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