6 gitweb.conf - Gitweb (Git web interface) configuration file
10 /etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl
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.
22 # gitweb configuration file for http://git.example.org
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
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.
45 Gitweb reads configuration data from the following sources in the
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`
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`
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
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.
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 ----------------------------------------------------------------------------
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.
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.
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
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.
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.
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
220 The following configuration variables tell gitweb where to find files.
221 The values of these variables are paths on the filesystem.
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
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.
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*: for a file to be highlighted, its syntax type must be detected
250 and that syntax must be supported by "highlight". The default syntax
251 detection is minimal, and there are many supported syntax types with no
252 detection by default. There are three options for adding syntax
253 detection. The first and second priority are `%highlight_basename` and
254 `%highlight_ext`, which detect based on basename (the full filename, for
255 example "Makefile") and extension (for example "sh"). The keys of these
256 hashes are the basename and extension, respectively, and the value for a
257 given key is the name of the syntax to be passed via `--syntax <syntax>`
258 to "highlight". The last priority is the "highlight" configuration of
259 `Shebang` regular expressions to detect the language based on the first
260 line in the file, (for example, matching the line "#!/bin/bash"). See
261 the highlight documentation and the default config at
262 /etc/highlight/filetypes.conf for more details.
264 For example if repositories you are hosting use "phtml" extension for
265 PHP files, and you want to have correct syntax-highlighting for those
266 files, you can add the following to gitweb configuration:
268 ---------------------------------------------------------
270 $highlight_ext{'phtml'} = 'php';
271 ---------------------------------------------------------
274 Links and their targets
275 ~~~~~~~~~~~~~~~~~~~~~~~
276 The configuration variables described below configure some of gitweb links:
277 their target and their look (text or image), and where to find page
278 prerequisites (stylesheet, favicon, images, scripts). Usually they are left
279 at their default values, with the possible exception of `@stylesheets`
283 List of URIs of stylesheets (relative to the base URI of a page). You
284 might specify more than one stylesheet, for example to use "gitweb.css"
285 as base with site specific modifications in a separate stylesheet
286 to make it easier to upgrade gitweb. For example, you can add
287 a `site` stylesheet by putting
289 ----------------------------------------------------------------------------
290 push @stylesheets, "gitweb-site.css";
291 ----------------------------------------------------------------------------
293 in the gitweb config file. Those values that are relative paths are
294 relative to base URI of gitweb.
296 This list should contain the URI of gitweb's standard stylesheet. The default
297 URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS`
298 makefile variable. Its default value is 'static/gitweb.css'
299 (or 'static/gitweb.min.css' if the `CSSMIN` variable is defined,
300 i.e. if CSS minifier is used during build).
302 *Note*: there is also a legacy `$stylesheet` configuration variable, which was
303 used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet
304 given by this variable is used by gitweb.
307 Points to the location where you put 'git-logo.png' on your web
308 server, or to be more the generic URI of logo, 72x27 size). This image
309 is displayed in the top right corner of each gitweb page and used as
310 a logo for the Atom feed. Relative to the base URI of gitweb (as a path).
311 Can be adjusted when building gitweb using `GITWEB_LOGO` variable
312 By default set to 'static/git-logo.png'.
315 Points to the location where you put 'git-favicon.png' on your web
316 server, or to be more the generic URI of favicon, which will be served
317 as "image/png" type. Web browsers that support favicons (website icons)
318 may display them in the browser's URL bar and next to the site name in
319 bookmarks. Relative to the base URI of gitweb. Can be adjusted at
320 build time using `GITWEB_FAVICON` variable.
321 By default set to 'static/git-favicon.png'.
324 Points to the location where you put 'gitweb.js' on your web server,
325 or to be more generic the URI of JavaScript code used by gitweb.
326 Relative to the base URI of gitweb. Can be set at build time using
327 the `GITWEB_JS` build-time configuration variable.
329 The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if
330 the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used
331 at build time. *Note* that this single file is generated from multiple
332 individual JavaScript "modules".
335 Target of the home link on the top of all pages (the first part of view
336 "breadcrumbs"). By default it is set to the absolute URI of a current page
337 (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined
338 or is an empty string).
341 Label for the "home link" at the top of all pages, leading to `$home_link`
342 (usually the main gitweb page, which contains the projects list). It is
343 used as the first component of gitweb's "breadcrumb trail":
344 `<home link> / <project> / <action>`. Can be set at build time using
345 the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects",
346 as this link leads to the list of projects. Another popular choice is to
347 set it to the name of site. Note that it is treated as raw HTML so it
348 should not be set from untrusted sources.
351 Additional links to be added to the start of the breadcrumb trail before
352 the home link, to pages that are logically "above" the gitweb projects
353 list, such as the organization and department which host the gitweb
354 server. Each element of the list is a reference to an array, in which
355 element 0 is the link text (equivalent to `$home_link_str`) and element
356 1 is the target URL (equivalent to `$home_link`).
358 For example, the following setting produces a breadcrumb trail like
359 "home / dev / projects / ..." where "projects" is the home link.
360 ----------------------------------------------------------------------------
361 our @extra_breadcrumbs = (
362 [ 'home' => 'https://www.example.org/' ],
363 [ 'dev' => 'https://dev.example.org/' ],
365 ----------------------------------------------------------------------------
369 URI and label (title) for the Git logo link (or your site logo,
370 if you chose to use different logo image). By default, these both
371 refer to Git homepage, http://git-scm.com[]; in the past, they pointed
372 to Git documentation at http://www.kernel.org[].
375 Changing gitweb's look
376 ~~~~~~~~~~~~~~~~~~~~~~
377 You can adjust how pages generated by gitweb look using the variables described
378 below. You can change the site name, add common headers and footers for all
379 pages, and add a description of this gitweb installation on its main page
380 (which is the projects list page), etc.
383 Name of your site or organization, to appear in page titles. Set it
384 to something descriptive for clearer bookmarks etc. If this variable
385 is not set or is, then gitweb uses the value of the `SERVER_NAME`
386 `CGI` environment variable, setting site name to "$SERVER_NAME Git",
387 or "Untitled Git" if this variable is not set (e.g. if running gitweb
388 as standalone script).
390 Can be set using the `GITWEB_SITENAME` at build time. Unset by default.
392 $site_html_head_string::
393 HTML snippet to be included in the <head> section of each page.
394 Can be set using `GITWEB_SITE_HTML_HEAD_STRING` at build time.
398 Name of a file with HTML to be included at the top of each page.
399 Relative to the directory containing the 'gitweb.cgi' script.
400 Can be set using `GITWEB_SITE_HEADER` at build time. No default
404 Name of a file with HTML to be included at the bottom of each page.
405 Relative to the directory containing the 'gitweb.cgi' script.
406 Can be set using `GITWEB_SITE_FOOTER` at build time. No default
410 Name of a HTML file which, if it exists, is included on the
411 gitweb projects overview page ("projects_list" view). Relative to
412 the directory containing the gitweb.cgi script. Default value
413 can be adjusted during build time using `GITWEB_HOMETEXT` variable.
414 By default set to 'indextext.html'.
416 $projects_list_description_width::
417 The width (in characters) of the "Description" column of the projects list.
418 Longer descriptions will be truncated (trying to cut at word boundary);
419 the full description is available in the 'title' attribute (usually shown on
420 mouseover). The default is 25, which might be too small if you
421 use long project descriptions.
423 $default_projects_order::
424 Default value of ordering of projects on projects list page, which
425 means the ordering used if you don't explicitly sort projects list
426 (if there is no "o" CGI query parameter in the URL). Valid values
427 are "none" (unsorted), "project" (projects are by project name,
428 i.e. path to repository relative to `$projectroot`), "descr"
429 (project description), "owner", and "age" (by date of most current
432 Default value is "project". Unknown value means unsorted.
434 $frontpage_no_project_list::
435 If 0, the gitweb frontpage will contain the project list; if 1 instead,
436 it will contain just the index text, search form, tag cloud (if enabled)
437 and a link to the actual project list. The page is reduced, but all
438 projects still need to be scanned for the tag cloud construction (but
439 the project info cache is used if enabled, of course). If the
440 option is set to 2, not even the tag cloud will be shown; this is fastest.
441 This option is useful for sites with large amount of projects. The default
445 Changing gitweb's behavior
446 ~~~~~~~~~~~~~~~~~~~~~~~~~~
447 These configuration variables control _internal_ gitweb behavior.
449 $default_blob_plain_mimetype::
450 Default mimetype for the blob_plain (raw) view, if mimetype checking
451 doesn't result in some other type; by default "text/plain".
452 Gitweb guesses mimetype of a file to display based on extension
453 of its filename, using `$mimetypes_file` (if set and file exists)
454 and '/etc/mime.types' files (see *mime.types*(5) manpage; only
455 filename extension rules are supported by gitweb).
457 $default_text_plain_charset::
458 Default charset for text files. If this is not set, the web server
459 configuration will be used. Unset by default.
462 Gitweb assumes this charset when a line contains non-UTF-8 characters.
463 The fallback decoding is used without error checking, so it can be even
464 "utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm)
465 man page for a list. The default is "latin1", aka. "iso-8859-1".
468 Rename detection options for git-diff and git-diff-tree. The default is
469 (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies,
470 or set it to () i.e. empty list if you don't want to have renames
473 *Note* that rename and especially copy detection can be quite
474 CPU-intensive. Note also that non Git tools can have problems with
475 patches generated with options mentioned above, especially when they
476 involve file copies (\'-C') or criss-cross renames (\'-B').
478 These configuration variable control caching in gitweb. If you don't
479 run gitweb installation on busy site with large number of repositories
480 (projects) you probably don't need caching; by default caching is
483 $projlist_cache_lifetime::
484 Lifetime of in-gitweb cache for projects list page, in minutes.
485 By default set to 0, which means tha projects list caching is
489 The cached list version (cache of Perl structure, not of final
490 output) is stored in "$cache_dir/$projlist_cache_name". $cache_dir
491 should be writable only by processes with the same uid as gitweb
492 (usually web server uid); if $cache_dir does not exist gitweb will
495 $projlist_cache_name::
496 The cached list version (cache of Perl structure, not of final
497 output) is stored in "$cache_dir/$projlist_cache_name". Only single
498 gitweb project root per system is supported, unless gitweb instances
499 for different projects root have different configuration.
501 By default $cache_dir is set to "$TMPDIR/gitweb" if $TMPDIR
502 environment variable does exist, "/tmp/gitweb" otherwise.
503 Default name for $projlist_cache_name is 'gitweb.index.cache';
505 *Note* projects list cache file can be tweaked by other scripts
506 running with the same uid as gitweb; use this ONLY at secure
510 By default, $cache_grpshared is 0 and the cache file is accessible
511 only by the webserver uid; however, when it is set to 1, it will
512 also be set group-readable and group-writable. You can use that
513 to externally trigger cache re-generation before users may have
514 a chance to trigger it (and wait a long time). For example, you
515 could use this script:
517 ----------------------------------------------------------------------
518 REQUEST_METHOD=HEAD perl -e 'do "./gitweb.cgi"; END {
519 fill_project_list_info([], "rebuild-cache") }' >/dev/null 2>&1
520 ----------------------------------------------------------------------
522 (You need to run it in the directory of gitweb.cgi and, if
523 gitweb_config.perl is not located in that same directory, also
524 set GITWEB_CONFIG for getweb_config.perl to be loaded properly.)
527 Some optional features and policies
528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
529 Most of features are configured via `%feature` hash; however some of extra
530 gitweb features can be turned on and configured using variables described
531 below. This list beside configuration variables that control how gitweb
532 looks does contain variables configuring administrative side of gitweb
533 (e.g. cross-site scripting prevention; admittedly this as side effect
534 affects how "summary" pages look like, or load limiting).
537 List of Git base URLs. These URLs are used to generate URLs
538 describing from where to fetch a project, which are shown on
539 project summary page. The full fetch URL is "`$git_base_url/$project`",
540 for each element of this list. You can set up multiple base URLs
541 (for example one for `git://` protocol, and one for `http://`
544 Note that per repository configuration can be set in '$GIT_DIR/cloneurl'
545 file, or as values of multi-value `gitweb.url` configuration variable in
546 project config. Per-repository configuration takes precedence over value
547 composed from `@git_base_url_list` elements and project name.
549 You can setup one single value (single entry/item in this list) at build
550 time by setting the `GITWEB_BASE_URL` build-time configuration variable.
551 By default it is set to (), i.e. an empty list. This means that gitweb
552 would not try to create project URL (to fetch) from project name.
554 $projects_list_group_categories::
555 Whether to enable the grouping of projects by category on the project
556 list page. The category of a project is determined by the
557 `$GIT_DIR/category` file or the `gitweb.category` variable in each
558 repository's configuration. Disabled by default (set to 0).
560 $project_list_default_category::
561 Default category for projects for which none is specified. If this is
562 set to the empty string, such projects will remain uncategorized and
563 listed at the top, above categorized projects. Used only if project
564 categories are enabled, which means if `$projects_list_group_categories`
565 is true. By default set to "" (empty string).
568 If true, some gitweb features are disabled to prevent content in
569 repositories from launching cross-site scripting (XSS) attacks. Set this
570 to true if you don't trust the content of your repositories.
571 False by default (set to 0).
574 Used to set the maximum load that we will still respond to gitweb queries.
575 If the server load exceeds this value then gitweb will return
576 "503 Service Unavailable" error. The server load is taken to be 0
577 if gitweb cannot determine its value. Currently it works only on Linux,
578 where it uses '/proc/loadavg'; the load there is the number of active
579 tasks on the system -- processes that are actually running -- averaged
580 over the last minute.
582 Set `$maxload` to undefined value (`undef`) to turn this feature off.
583 The default value is 300.
586 If true, omit the column with date of the most current commit on the
587 projects list page. It can save a bit of I/O and a fork per repository.
590 If this is set to a pathname (relative to `$GIT_DIR`) and the file
591 exists and contains a date in either iso, iso-strict or raw format,
592 it will be used to calculate the age which can save quite a bit of I/O
593 and a fork per repository.
595 This is most useful if a hooks/post-update script is present that contains
598 ----------------------------------------------------------------------------
599 git for-each-ref --sort=-committerdate --format='%(committerdate:iso8601)' \
600 --count=1 refs/heads > info/lastactivity
601 ----------------------------------------------------------------------------
603 Then `$lastactivity_file` can be set to `"info/lastactivity"` and the age
604 column can be used without incurring the I/O penalty.
606 Note that if the `extra-branch-refs` feature is being used then the above
607 script will need to be adjusted to take those additional refs into
608 consideration otherwise they will not affect the value displayed in the age
609 column when this feature is used.
612 If true prevents displaying information about repository owner.
614 $per_request_config::
615 If this is set to code reference, it will be run once for each request.
616 You can set parts of configuration that change per session this way.
617 For example, one might use the following code in a gitweb configuration
620 --------------------------------------------------------------------------------
621 our $per_request_config = sub {
622 $ENV{GL_USER} = $cgi->remote_user || "gitweb";
624 --------------------------------------------------------------------------------
626 If `$per_request_config` is not a code reference, it is interpreted as boolean
627 value. If it is true gitweb will process config files once per request,
628 and if it is false gitweb will process config files only once, each time it
629 is executed. True by default (set to 1).
631 *NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default
632 values before every request, so if you want to change them, be sure to set
633 this variable to true or a code reference effecting the desired changes.
635 This variable matters only when using persistent web environments that
636 serve multiple requests using single gitweb instance, like mod_perl,
640 If true and STDIN has fileno 0 and getsockname succeeds and getpeername
641 fails with ENOTCONN, FCGI mode will be activated automatically just the
642 same way as though the '--fcgi' option was given.
647 Usually you should not need to change (adjust) any of configuration
648 variables described below; they should be automatically set by gitweb to
653 Gitweb version, set automatically when creating gitweb.cgi from
654 gitweb.perl. You might want to modify it if you are running modified
657 ---------------------------------------------------
658 our $version .= " with caching";
659 ---------------------------------------------------
661 if you run modified version of gitweb with caching support. This variable
662 is purely informational, used e.g. in the "generator" meta header in HTML
667 Full URL and absolute URL of the gitweb script;
668 in earlier versions of gitweb you might have need to set those
669 variables, but now there should be no need to do it. See
670 `$per_request_config` if you need to set them still.
673 Base URL for relative URLs in pages generated by gitweb,
674 (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),
675 needed and used '<base href="$base_url">' only for URLs with nonempty
676 PATH_INFO. Usually gitweb sets its value correctly,
677 and there is no need to set this variable, e.g. to $my_uri or "/".
678 See `$per_request_config` if you need to override it anyway.
681 CONFIGURING GITWEB FEATURES
682 ---------------------------
683 Many gitweb features can be enabled (or disabled) and configured using the
684 `%feature` hash. Names of gitweb features are keys of this hash.
686 Each `%feature` hash element is a hash reference and has the following
688 ----------------------------------------------------------------------
689 "<feature_name>" => {
690 "sub" => <feature-sub (subroutine)>,
691 "override" => <allow-override (boolean)>,
692 "default" => [ <options>... ]
694 ----------------------------------------------------------------------
695 Some features cannot be overridden per project. For those
696 features the structure of appropriate `%feature` hash element has a simpler
698 ----------------------------------------------------------------------
699 "<feature_name>" => {
701 "default" => [ <options>... ]
703 ----------------------------------------------------------------------
704 As one can see it lacks the \'sub' element.
706 The meaning of each part of feature configuration is described
710 List (array reference) of feature parameters (if there are any),
711 used also to toggle (enable or disable) given feature.
713 Note that it is currently *always* an array reference, even if
714 feature doesn't accept any configuration parameters, and \'default'
715 is used only to turn it on or off. In such case you turn feature on
716 by setting this element to `[1]`, and torn it off by setting it to
717 `[0]`. See also the passage about the "blame" feature in the "Examples"
720 To disable features that accept parameters (are configurable), you
721 need to set this element to empty list i.e. `[]`.
724 If this field has a true value then the given feature is
725 overridable, which means that it can be configured
726 (or enabled/disabled) on a per-repository basis.
728 Usually given "<feature>" is configurable via the `gitweb.<feature>`
729 config variable in the per-repository Git configuration file.
731 *Note* that no feature is overridable by default.
734 Internal detail of implementation. What is important is that
735 if this field is not present then per-repository override for
736 given feature is not supported.
738 You wouldn't need to ever change it in gitweb config file.
741 Features in `%feature`
742 ~~~~~~~~~~~~~~~~~~~~~~
743 The gitweb features that are configurable via `%feature` hash are listed
744 below. This should be a complete list, but ultimately the authoritative
745 and complete list is in gitweb.cgi source code, with features described
749 Enable the "blame" and "blame_incremental" blob views, showing for
750 each line the last commit that modified it; see linkgit:git-blame[1].
751 This can be very CPU-intensive and is therefore disabled by default.
753 This feature can be configured on a per-repository basis via
754 repository's `gitweb.blame` configuration variable (boolean).
757 Enable and configure the "snapshot" action, which allows user to
758 download a compressed archive of any tree or commit, as produced
759 by linkgit:git-archive[1] and possibly additionally compressed.
760 This can potentially generate high traffic if you have large project.
762 The value of \'default' is a list of names of snapshot formats,
763 defined in `%known_snapshot_formats` hash, that you wish to offer.
764 Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
765 compressed tar archive) and "zip"; please consult gitweb sources for
766 a definitive list. By default only "tgz" is offered.
768 This feature can be configured on a per-repository basis via
769 repository's `gitweb.blame` configuration variable, which contains
770 a comma separated list of formats or "none" to disable snapshots.
771 Unknown values are ignored.
774 Enable grep search, which lists the files in currently selected
775 tree (directory) containing the given string; see linkgit:git-grep[1].
776 This can be potentially CPU-intensive, of course. Enabled by default.
778 This feature can be configured on a per-repository basis via
779 repository's `gitweb.grep` configuration variable (boolean).
782 Enable the so called pickaxe search, which will list the commits
783 that introduced or removed a given string in a file. This can be
784 practical and quite faster alternative to "blame" action, but it is
785 still potentially CPU-intensive. Enabled by default.
787 The pickaxe search is described in linkgit:git-log[1] (the
788 description of `-S<string>` option, which refers to pickaxe entry in
789 linkgit:gitdiffcore[7] for more details).
791 This feature can be configured on a per-repository basis by setting
792 repository's `gitweb.pickaxe` configuration variable (boolean).
795 Enable showing size of blobs (ordinary files) in a "tree" view, in a
796 separate column, similar to what `ls -l` does; see description of
797 `-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of
798 I/O. Enabled by default.
800 This feature can be configured on a per-repository basis via
801 repository's `gitweb.showSizes` configuration variable (boolean).
804 Enable and configure "patches" view, which displays list of commits in email
805 (plain text) output format; see also linkgit:git-format-patch[1].
806 The value is the maximum number of patches in a patchset generated
807 in "patches" view. Set the 'default' field to a list containing single
808 item of or to an empty list to disable patch view, or to a list
809 containing a single negative number to remove any limit.
812 This feature can be configured on a per-repository basis via
813 repository's `gitweb.patches` configuration variable (integer).
816 Avatar support. When this feature is enabled, views such as
817 "shortlog" or "commit" will display an avatar associated with
818 the email of each committer and author.
820 Currently available providers are *"gravatar"* and *"picon"*.
821 Only one provider at a time can be selected ('default' is one element list).
822 If an unknown provider is specified, the feature is disabled.
823 *Note* that some providers might require extra Perl packages to be
824 installed; see 'gitweb/INSTALL' for more details.
826 This feature can be configured on a per-repository basis via
827 repository's `gitweb.avatar` configuration variable.
829 See also `%avatar_size` with pixel sizes for icons and avatars
830 ("default" is used for one-line like "log" and "shortlog", "double"
831 is used for two-line like "commit", "commitdiff" or "tag"). If the
832 default font sizes or lineheights are changed (e.g. via adding extra
833 CSS stylesheet in `@stylesheets`), it may be appropriate to change
837 Server-side syntax highlight support in "blob" view. It requires
838 `$highlight_bin` program to be available (see the description of
839 this variable in the "Configuration variables" section above),
840 and therefore is disabled by default.
842 This feature can be configured on a per-repository basis via
843 repository's `gitweb.highlight` configuration variable (boolean).
846 Enable displaying remote heads (remote-tracking branches) in the "heads"
847 list. In most cases the list of remote-tracking branches is an
848 unnecessary internal private detail, and this feature is therefore
849 disabled by default. linkgit:git-instaweb[1], which is usually used
850 to browse local repositories, enables and uses this feature.
852 This feature can be configured on a per-repository basis via
853 repository's `gitweb.remote_heads` configuration variable (boolean).
856 The remaining features cannot be overridden on a per project basis.
859 Enable text search, which will list the commits which match author,
860 committer or commit text to a given string; see the description of
861 `--author`, `--committer` and `--grep` options in linkgit:git-log[1]
862 manpage. Enabled by default.
864 Project specific override is not supported.
867 If this feature is enabled, gitweb considers projects in
868 subdirectories of project root (basename) to be forks of existing
869 projects. For each project +$projname.git+, projects in the
870 +$projname/+ directory and its subdirectories will not be
871 shown in the main projects list. Instead, a \'\+' mark is shown
872 next to +$projname+, which links to a "forks" view that lists all
873 the forks (all projects in +$projname/+ subdirectory). Additionally
874 a "forks" view for a project is linked from project summary page.
876 If the project list is taken from a file (+$projects_list+ points to a
877 file), forks are only recognized if they are listed after the main project
880 Project specific override is not supported.
883 Insert custom links to the action bar of all project pages. This
884 allows you to link to third-party scripts integrating into gitweb.
886 The "default" value consists of a list of triplets in the form
887 `("<label>", "<link>", "<position>")` where "position" is the label
888 after which to insert the link, "link" is a format string where `%n`
889 expands to the project name, `%f` to the project path within the
890 filesystem (i.e. "$projectroot/$project"), `%h` to the current hash
891 (\'h' gitweb parameter) and `%b` to the current hash base
892 (\'hb' gitweb parameter); `%%` expands to \'%'.
894 For example, at the time this page was written, the http://repo.or.cz[]
895 Git hosting site set it to the following to enable graphical log
896 (using the third party tool *git-browser*):
898 ----------------------------------------------------------------------
899 $feature{'actions'}{'default'} =
900 [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
901 ----------------------------------------------------------------------
903 This adds a link titled "graphiclog" after the "summary" link, leading to
904 `git-browser` script, passing `r=<project>` as a query parameter.
906 Project specific override is not supported.
909 Enable displaying how much time and how many Git commands it took to
910 generate and display each page in the page footer (at the bottom of
911 page). For example the footer might contain: "This page took 6.53325
912 seconds and 13 Git commands to generate." Disabled by default.
914 Project specific override is not supported.
916 javascript-timezone::
917 Enable and configure the ability to change a common time zone for dates
918 in gitweb output via JavaScript. Dates in gitweb output include
919 authordate and committerdate in "commit", "commitdiff" and "log"
920 views, and taggerdate in "tag" view. Enabled by default.
922 The value is a list of three values: a default time zone (for if the client
923 hasn't selected some other time zone and saved it in a cookie), a name of cookie
924 where to store selected time zone, and a CSS class used to mark up
925 dates for manipulation. If you want to turn this feature off, set "default"
928 Typical gitweb config files will only change starting (default) time zone,
929 and leave other elements at their default values:
931 ---------------------------------------------------------------------------
932 $feature{'javascript-timezone'}{'default'}[0] = "utc";
933 ---------------------------------------------------------------------------
935 The example configuration presented here is guaranteed to be backwards
936 and forward compatible.
938 Time zone values can be "local" (for local time zone that browser uses), "utc"
939 (what gitweb uses when JavaScript or this feature is disabled), or numerical
940 time zones in the form of "+/-HHMM", such as "+0200".
942 Project specific override is not supported.
945 List of additional directories under "refs" which are going to
946 be used as branch refs. For example if you have a gerrit setup
947 where all branches under refs/heads/ are official,
948 push-after-review ones and branches under refs/sandbox/,
949 refs/wip and refs/other are user ones where permissions are
950 much wider, then you might want to set this variable as
953 --------------------------------------------------------------------------------
954 $feature{'extra-branch-refs'}{'default'} =
955 ['sandbox', 'wip', 'other'];
956 --------------------------------------------------------------------------------
958 This feature can be configured on per-repository basis after setting
959 $feature{'extra-branch-refs'}{'override'} to true, via repository's
960 `gitweb.extraBranchRefs` configuration variable, which contains a
961 space separated list of refs. An example:
963 --------------------------------------------------------------------------------
965 extraBranchRefs = sandbox wip other
966 --------------------------------------------------------------------------------
968 The gitweb.extraBranchRefs is actually a multi-valued configuration
969 variable, so following example is also correct and the result is the
970 same as of the snippet above:
972 --------------------------------------------------------------------------------
974 extraBranchRefs = sandbox
975 extraBranchRefs = wip other
976 --------------------------------------------------------------------------------
978 It is an error to specify a ref that does not pass "git check-ref-format"
979 scrutiny. Duplicated values are filtered.
985 To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
986 "zip" snapshots), while allowing individual projects to turn them off, put
987 the following in your GITWEB_CONFIG file:
989 $feature{'blame'}{'default'} = [1];
990 $feature{'blame'}{'override'} = 1;
992 $feature{'pickaxe'}{'default'} = [1];
993 $feature{'pickaxe'}{'override'} = 1;
995 $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
996 $feature{'snapshot'}{'override'} = 1;
998 If you allow overriding for the snapshot feature, you can specify which
999 snapshot formats are globally disabled. You can also add any command-line
1000 options you want (such as setting the compression level). For instance, you
1001 can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
1002 adding the following lines to your gitweb configuration file:
1004 $known_snapshot_formats{'zip'}{'disabled'} = 1;
1005 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
1009 Debugging would be easier if the fallback configuration file
1010 (`/etc/gitweb.conf`) and environment variable to override its location
1011 ('GITWEB_CONFIG_SYSTEM') had names reflecting their "fallback" role.
1012 The current names are kept to avoid breaking working setups.
1016 The location of per-instance and system-wide configuration files can be
1017 overridden using the following environment variables:
1020 Sets location of per-instance configuration file.
1021 GITWEB_CONFIG_SYSTEM::
1022 Sets location of fallback system-wide configuration file.
1023 This file is read only if per-instance one does not exist.
1024 GITWEB_CONFIG_COMMON::
1025 Sets location of common system-wide configuration file.
1030 gitweb_config.perl::
1031 This is default name of per-instance configuration file. The
1032 format of this file is described above.
1034 This is default name of fallback system-wide configuration
1035 file. This file is used only if per-instance configuration
1036 variable is not found.
1037 /etc/gitweb-common.conf::
1038 This is default name of common system-wide configuration
1044 linkgit:gitweb[1], linkgit:git-instaweb[1]
1046 'gitweb/README', 'gitweb/INSTALL'
1050 Part of the linkgit:git[1] suite