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