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