327246c19a30fe7818bfcba23f97ad6c084e2724
   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