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