search..
No manual entry for -- in section 5
GITWEB.CONF(5)			   Git Manual			 GITWEB.CONF(5)

NAME
       gitweb.conf - Gitweb (Git web interface) configuration file

SYNOPSIS
       /etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl

DESCRIPTION
       The gitweb CGI script for viewing Git repositories over the web uses a
       perl script fragment as its configuration file. You can set variables
       using "our $variable = value"; text from a "#" character until the end
       of a line is ignored. See perlsyn(1) for details.

       An example:

	   # gitweb configuration file for http://git.example.org
	   #
	   our $projectroot = "/srv/git"; # FHS recommendation
	   our $site_name = 'Example.org >> Repos';

       The configuration file is used to override the default settings that
       were built into gitweb at the time the gitweb.cgi script was generated.

       While one could just alter the configuration settings in the gitweb CGI
       itself, those changes would be lost upon upgrade. Configuration settings
       might also be placed into a file in the same directory as the CGI script
       with the default name gitweb_config.perl -- allowing one to have
       multiple gitweb instances with different configurations by the use of
       symlinks.

       Note that some configuration can be controlled on per-repository rather
       than gitweb-wide basis: see "Per-repository gitweb configuration"
       subsection on gitweb(1) manpage.

DISCUSSION
       Gitweb reads configuration data from the following sources in the
       following order:

       o   built-in values (some set during build stage),

       o   common system-wide configuration file (defaults to
	   /etc/gitweb-common.conf),

       o   either per-instance configuration file (defaults to
	   gitweb_config.perl in the same directory as the installed gitweb),
	   or if it does not exist then fallback system-wide configuration file
	   (defaults to /etc/gitweb.conf).

       Values obtained in later configuration files override values obtained
       earlier in the above sequence.

       Locations of the common system-wide configuration file, the fallback
       system-wide configuration file and the per-instance configuration file
       are defined at compile time using build-time Makefile configuration
       variables, respectively GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and
       GITWEB_CONFIG.

       You can also override locations of gitweb configuration files during
       runtime by setting the following environment variables:
       GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG to a
       non-empty value.

       The syntax of the configuration files is that of Perl, since these files
       are handled by sourcing them as fragments of Perl code (the language
       that gitweb itself is written in). Variables are typically set using the
       our qualifier (as in "our $variable = <value>;") to avoid syntax errors
       if a new version of gitweb no longer uses a variable and therefore stops
       declaring it.

       You can include other configuration file using read_config_file()
       subroutine. For example, one might want to put gitweb configuration
       related to access control for viewing repositories via Gitolite (one of
       Git repository management tools) in a separate file, e.g. in
       /etc/gitweb-gitolite.conf. To include it, put

	   read_config_file("/etc/gitweb-gitolite.conf");

       somewhere in gitweb configuration file used, e.g. in per-installation
       gitweb configuration file. Note that read_config_file() checks itself
       that the file it reads exists, and does nothing if it is not found. It
       also handles errors in included file.

       The default configuration with no configuration file at all may work
       perfectly well for some installations. Still, a configuration file is
       useful for customizing or tweaking the behavior of gitweb in many ways,
       and some optional features will not be present unless explicitly enabled
       using the configurable %features variable (see also "Configuring gitweb
       features" section below).

CONFIGURATION VARIABLES
       Some configuration variables have their default values (embedded in the
       CGI script) set during building gitweb -- if that is the case, this fact
       is put in their description. See gitweb's INSTALL file for instructions
       on building and installing gitweb.

   Location of repositories
       The configuration variables described below control how gitweb finds Git
       repositories, and how repositories are displayed and accessed.

       See also "Repositories" and later subsections in gitweb(1) manpage.

       $projectroot
	   Absolute filesystem path which will be prepended to project path;
	   the path to repository is $projectroot/$project. Set to
	   $GITWEB_PROJECTROOT during installation. This variable has to be set
	   correctly for gitweb to find repositories.

	   For example, if $projectroot is set to "/srv/git" by putting the
	   following in gitweb config file:

	       our $projectroot = "/srv/git";

	   then

	       http://git.example.com/gitweb.cgi?p=foo/bar.git

	   and its path_info based equivalent

	       http://git.example.com/gitweb.cgi/foo/bar.git

	   will map to the path /srv/git/foo/bar.git on the filesystem.

       $projects_list
	   Name of a plain text file listing projects, or a name of directory
	   to be scanned for projects.

	   Project list files should list one project per line, with each line
	   having the following format

	       <URI-encoded filesystem path to repository> SP <URI-encoded repository owner>

	   The default value of this variable is determined by the GITWEB_LIST
	   makefile variable at installation time. If this variable is empty,
	   gitweb will fall back to scanning the $projectroot directory for
	   repositories.

       $project_maxdepth
	   If $projects_list variable is unset, gitweb will recursively scan
	   filesystem for Git repositories. The $project_maxdepth is used to
	   limit traversing depth, relative to $projectroot (starting point);
	   it means that directories which are further from $projectroot than
	   $project_maxdepth will be skipped.

	   It is purely performance optimization, originally intended for MacOS
	   X, where recursive directory traversal is slow. Gitweb follows
	   symbolic links, but it detects cycles, ignoring any duplicate files
	   and directories.

	   The default value of this variable is determined by the build-time
	   configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to
	   2007.

       $export_ok
	   Show repository only if this file exists (in repository). Only
	   effective if this variable evaluates to true. Can be set when
	   building gitweb by setting GITWEB_EXPORT_OK. This path is relative
	   to GIT_DIR. git-daemon[1] uses git-daemon-export-ok, unless started
	   with --export-all. By default this variable is not set, which means
	   that this feature is turned off.

       $export_auth_hook
	   Function used to determine which repositories should be shown. This
	   subroutine should take one parameter, the full path to a project,
	   and if it returns true, that project will be included in the
	   projects list and can be accessed through gitweb as long as it
	   fulfills the other requirements described by $export_ok,
	   $projects_list, and $projects_maxdepth. Example:

	       our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };

	   though the above might be done by using $export_ok instead

	       our $export_ok = "git-daemon-export-ok";

	   If not set (default), it means that this feature is disabled.

	   See also more involved example in "Controlling access to Git
	   repositories" subsection on gitweb(1) manpage.

       $strict_export
	   Only allow viewing of repositories also shown on the overview page.
	   This for example makes $export_ok file decide if repository is
	   available and not only if it is shown. If $projects_list points to
	   file with list of project, only those repositories listed would be
	   available for gitweb. Can be set during building gitweb via
	   GITWEB_STRICT_EXPORT. By default this variable is not set, which
	   means that you can directly access those repositories that are
	   hidden from projects list page (e.g. the are not listed in the
	   $projects_list file).

   Finding files
       The following configuration variables tell gitweb where to find files.
       The values of these variables are paths on the filesystem.

       $GIT
	   Core git executable to use. By default set to $GIT_BINDIR/git, which
	   in turn is by default set to $(bindir)/git. If you use Git installed
	   from a binary package, you should usually set this to
	   "/usr/bin/git". This can just be "git" if your web server has a
	   sensible PATH; from security point of view it is better to use
	   absolute path to git binary. If you have multiple Git versions
	   installed it can be used to choose which one to use. Must be
	   (correctly) set for gitweb to be able to work.

       $mimetypes_file
	   File to use for (filename extension based) guessing of MIME types
	   before trying /etc/mime.types.  NOTE that this path, if relative, is
	   taken as relative to the current Git repository, not to CGI script.
	   If unset, only /etc/mime.types is used (if present on filesystem).
	   If no mimetypes file is found, mimetype guessing based on extension
	   of file is disabled. Unset by default.

       $highlight_bin
	   Path to the highlight executable to use (it must be the one from
	   http://andre-simon.de/zip/download.php due to assumptions about
	   parameters and output). By default set to highlight; set it to full
	   path to highlight executable if it is not installed on your web
	   server's PATH. Note that highlight feature must be set for gitweb to
	   actually use syntax highlighting.

	   NOTE: for a file to be highlighted, its syntax type must be detected
	   and that syntax must be supported by "highlight". The default syntax
	   detection is minimal, and there are many supported syntax types with
	   no detection by default. There are three options for adding syntax
	   detection. The first and second priority are %highlight_basename and
	   %highlight_ext, which detect based on basename (the full filename,
	   for example "Makefile") and extension (for example "sh"). The keys
	   of these hashes are the basename and extension, respectively, and
	   the value for a given key is the name of the syntax to be passed via
	   --syntax <syntax> to "highlight". The last priority is the
	   "highlight" configuration of Shebang regular expressions to detect
	   the language based on the first line in the file, (for example,
	   matching the line "#!/bin/bash"). See the highlight documentation
	   and the default config at /etc/highlight/filetypes.conf for more
	   details.

	   For example if repositories you are hosting use "phtml" extension
	   for PHP files, and you want to have correct syntax-highlighting for
	   those files, you can add the following to gitweb configuration:

	       our %highlight_ext;
	       $highlight_ext{'phtml'} = 'php';

   Links and their targets
       The configuration variables described below configure some of gitweb
       links: their target and their look (text or image), and where to find
       page prerequisites (stylesheet, favicon, images, scripts). Usually they
       are left at their default values, with the possible exception of
       @stylesheets variable.

       @stylesheets
	   List of URIs of stylesheets (relative to the base URI of a page).
	   You might specify more than one stylesheet, for example to use
	   "gitweb.css" as base with site specific modifications in a separate
	   stylesheet to make it easier to upgrade gitweb. For example, you can
	   add a site stylesheet by putting

	       push @stylesheets, "gitweb-site.css";

	   in the gitweb config file. Those values that are relative paths are
	   relative to base URI of gitweb.

	   This list should contain the URI of gitweb's standard stylesheet.
	   The default URI of gitweb stylesheet can be set at build time using
	   the GITWEB_CSS makefile variable. Its default value is
	   static/gitweb.css (or static/gitweb.min.css if the CSSMIN variable
	   is defined, i.e. if CSS minifier is used during build).

	   Note: there is also a legacy $stylesheet configuration variable,
	   which was used by older gitweb. If $stylesheet variable is defined,
	   only CSS stylesheet given by this variable is used by gitweb.

       $logo
	   Points to the location where you put git-logo.png on your web
	   server, or to be more the generic URI of logo, 72x27 size). This
	   image is displayed in the top right corner of each gitweb page and
	   used as a logo for the Atom feed. Relative to the base URI of gitweb
	   (as a path). Can be adjusted when building gitweb using GITWEB_LOGO
	   variable By default set to static/git-logo.png.

       $favicon
	   Points to the location where you put git-favicon.png on your web
	   server, or to be more the generic URI of favicon, which will be
	   served as "image/png" type. Web browsers that support favicons
	   (website icons) may display them in the browser's URL bar and next
	   to the site name in bookmarks. Relative to the base URI of gitweb.
	   Can be adjusted at build time using GITWEB_FAVICON variable. By
	   default set to static/git-favicon.png.

       $javascript
	   Points to the location where you put gitweb.js on your web server,
	   or to be more generic the URI of JavaScript code used by gitweb.
	   Relative to the base URI of gitweb. Can be set at build time using
	   the GITWEB_JS build-time configuration variable.

	   The default value is either static/gitweb.js, or
	   static/gitweb.min.js if the JSMIN build variable was defined, i.e.
	   if JavaScript minifier was used at build time.  Note that this
	   single file is generated from multiple individual JavaScript
	   "modules".

       $home_link
	   Target of the home link on the top of all pages (the first part of
	   view "breadcrumbs"). By default it is set to the absolute URI of a
	   current page (to the value of $my_uri variable, or to "/" if $my_uri
	   is undefined or is an empty string).

       $home_link_str
	   Label for the "home link" at the top of all pages, leading to
	   $home_link (usually the main gitweb page, which contains the
	   projects list). It is used as the first component of gitweb's
	   "breadcrumb trail": <home-link> / <project> / <action>. Can be set
	   at build time using the GITWEB_HOME_LINK_STR variable. By default it
	   is set to "projects", as this link leads to the list of projects.
	   Another popular choice is to set it to the name of site. Note that
	   it is treated as raw HTML so it should not be set from untrusted
	   sources.

       @extra_breadcrumbs
	   Additional links to be added to the start of the breadcrumb trail
	   before the home link, to pages that are logically "above" the gitweb
	   projects list, such as the organization and department which host
	   the gitweb server. Each element of the list is a reference to an
	   array, in which element 0 is the link text (equivalent to
	   $home_link_str) and element 1 is the target URL (equivalent to
	   $home_link).

	   For example, the following setting produces a breadcrumb trail like
	   "home / dev / projects / ..." where "projects" is the home link.

		   our @extra_breadcrumbs = (
		     [ 'home' => 'https://www.example.org/' ],
		     [ 'dev'  => 'https://dev.example.org/' ],
		   );

       $logo_url, $logo_label
	   URI and label (title) for the Git logo link (or your site logo, if
	   you chose to use different logo image). By default, these both refer
	   to Git homepage, https://git-scm.com; in the past, they pointed to
	   Git documentation at https://www.kernel.org.

   Changing gitweb's look
       You can adjust how pages generated by gitweb look using the variables
       described below. You can change the site name, add common headers and
       footers for all pages, and add a description of this gitweb installation
       on its main page (which is the projects list page), etc.

       $site_name
	   Name of your site or organization, to appear in page titles. Set it
	   to something descriptive for clearer bookmarks etc. If this variable
	   is not set or is, then gitweb uses the value of the SERVER_NAME CGI
	   environment variable, setting site name to "$SERVER_NAME Git", or
	   "Untitled Git" if this variable is not set (e.g. if running gitweb
	   as standalone script).

	   Can be set using the GITWEB_SITENAME at build time. Unset by
	   default.

       $site_html_head_string
	   HTML snippet to be included in the <head> section of each page. Can
	   be set using GITWEB_SITE_HTML_HEAD_STRING at build time. No default
	   value.

       $site_header
	   Name of a file with HTML to be included at the top of each page.
	   Relative to the directory containing the gitweb.cgi script. Can be
	   set using GITWEB_SITE_HEADER at build time. No default value.

       $site_footer
	   Name of a file with HTML to be included at the bottom of each page.
	   Relative to the directory containing the gitweb.cgi script. Can be
	   set using GITWEB_SITE_FOOTER at build time. No default value.

       $home_text
	   Name of a HTML file which, if it exists, is included on the gitweb
	   projects overview page ("projects_list" view). Relative to the
	   directory containing the gitweb.cgi script. Default value can be
	   adjusted during build time using GITWEB_HOMETEXT variable. By
	   default set to indextext.html.

       $projects_list_description_width
	   The width (in characters) of the "Description" column of the
	   projects list. Longer descriptions will be truncated (trying to cut
	   at word boundary); the full description is available in the title
	   attribute (usually shown on mouseover). The default is 25, which
	   might be too small if you use long project descriptions.

       $default_projects_order
	   Default value of ordering of projects on projects list page, which
	   means the ordering used if you don't explicitly sort projects list
	   (if there is no "o" CGI query parameter in the URL). Valid values
	   are "none" (unsorted), "project" (projects are by project name, i.e.
	   path to repository relative to $projectroot), "descr" (project
	   description), "owner", and "age" (by date of most current commit).

	   Default value is "project". Unknown value means unsorted.

   Changing gitweb's behavior
       These configuration variables control internal gitweb behavior.

       $default_blob_plain_mimetype
	   Default mimetype for the blob_plain (raw) view, if mimetype checking
	   doesn't result in some other type; by default "text/plain". Gitweb
	   guesses mimetype of a file to display based on extension of its
	   filename, using $mimetypes_file (if set and file exists) and
	   /etc/mime.types files (see mime.types(5) manpage; only filename
	   extension rules are supported by gitweb).

       $default_text_plain_charset
	   Default charset for text files. If this is not set, the web server
	   configuration will be used. Unset by default.

       $fallback_encoding
	   Gitweb assumes this charset when a line contains non-UTF-8
	   characters. The fallback decoding is used without error checking, so
	   it can be even "utf-8". The value must be a valid encoding; see the
	   Encoding::Supported(3pm) man page for a list. The default is
	   "latin1", aka. "iso-8859-1".

       @diff_opts
	   Rename detection options for git-diff and git-diff-tree. The default
	   is ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies,
	   or set it to () i.e. empty list if you don't want to have renames
	   detection.

	   Note that rename and especially copy detection can be quite
	   CPU-intensive. Note also that non Git tools can have problems with
	   patches generated with options mentioned above, especially when they
	   involve file copies ('-C') or criss-cross renames ('-B').

   Some optional features and policies
       Most of features are configured via %feature hash; however some of extra
       gitweb features can be turned on and configured using variables
       described below. This list beside configuration variables that control
       how gitweb looks does contain variables configuring administrative side
       of gitweb (e.g. cross-site scripting prevention; admittedly this as side
       effect affects how "summary" pages look like, or load limiting).

       @git_base_url_list
	   List of Git base URLs. These URLs are used to generate URLs
	   describing from where to fetch a project, which are shown on project
	   summary page. The full fetch URL is "$git_base_url/$project", for
	   each element of this list. You can set up multiple base URLs (for
	   example one for git:// protocol, and one for http:// protocol).

	   Note that per repository configuration can be set in
	   $GIT_DIR/cloneurl file, or as values of multi-value gitweb.url
	   configuration variable in project config. Per-repository
	   configuration takes precedence over value composed from
	   @git_base_url_list elements and project name.

	   You can setup one single value (single entry/item in this list) at
	   build time by setting the GITWEB_BASE_URL build-time configuration
	   variable. By default it is set to (), i.e. an empty list. This means
	   that gitweb would not try to create project URL (to fetch) from
	   project name.

       $projects_list_group_categories
	   Whether to enable the grouping of projects by category on the
	   project list page. The category of a project is determined by the
	   $GIT_DIR/category file or the gitweb.category variable in each
	   repository's configuration. Disabled by default (set to 0).

       $project_list_default_category
	   Default category for projects for which none is specified. If this
	   is set to the empty string, such projects will remain uncategorized
	   and listed at the top, above categorized projects. Used only if
	   project categories are enabled, which means if
	   $projects_list_group_categories is true. By default set to "" (empty
	   string).

       $prevent_xss
	   If true, some gitweb features are disabled to prevent content in
	   repositories from launching cross-site scripting (XSS) attacks. Set
	   this to true if you don't trust the content of your repositories.
	   False by default (set to 0).

       $maxload
	   Used to set the maximum load that we will still respond to gitweb
	   queries. If the server load exceeds this value then gitweb will
	   return "503 Service Unavailable" error. The server load is taken to
	   be 0 if gitweb cannot determine its value. Currently it works only
	   on Linux, where it uses /proc/loadavg; the load there is the number
	   of active tasks on the system -- processes that are actually running
	   -- averaged over the last minute.

	   Set $maxload to undefined value (undef) to turn this feature off.
	   The default value is 300.

       $omit_age_column
	   If true, omit the column with date of the most current commit on the
	   projects list page. It can save a bit of I/O and a fork per
	   repository.

       $omit_owner
	   If true prevents displaying information about repository owner.

       $per_request_config
	   If this is set to code reference, it will be run once for each
	   request. You can set parts of configuration that change per session
	   this way. For example, one might use the following code in a gitweb
	   configuration file

	       our $per_request_config = sub {
		       $ENV{GL_USER} = $cgi->remote_user || "gitweb";
	       };

	   If $per_request_config is not a code reference, it is interpreted as
	   boolean value. If it is true gitweb will process config files once
	   per request, and if it is false gitweb will process config files
	   only once, each time it is executed. True by default (set to 1).

	   NOTE: $my_url, $my_uri, and $base_url are overwritten with their
	   default values before every request, so if you want to change them,
	   be sure to set this variable to true or a code reference effecting
	   the desired changes.

	   This variable matters only when using persistent web environments
	   that serve multiple requests using single gitweb instance, like
	   mod_perl, FastCGI or Plackup.

   Other variables
       Usually you should not need to change (adjust) any of configuration
       variables described below; they should be automatically set by gitweb to
       correct value.

       $version
	   Gitweb version, set automatically when creating gitweb.cgi from
	   gitweb.perl. You might want to modify it if you are running modified
	   gitweb, for example

	       our $version .= " with caching";

	   if you run modified version of gitweb with caching support. This
	   variable is purely informational, used e.g. in the "generator" meta
	   header in HTML header.

       $my_url, $my_uri
	   Full URL and absolute URL of the gitweb script; in earlier versions
	   of gitweb you might have need to set those variables, but now there
	   should be no need to do it. See $per_request_config if you need to
	   set them still.

       $base_url
	   Base URL for relative URLs in pages generated by gitweb, (e.g.
	   $logo, $favicon, @stylesheets if they are relative URLs), needed and
	   used <base href="$base_url"> only for URLs with nonempty PATH_INFO.
	   Usually gitweb sets its value correctly, and there is no need to set
	   this variable, e.g. to $my_uri or "/". See $per_request_config if
	   you need to override it anyway.

CONFIGURING GITWEB FEATURES
       Many gitweb features can be enabled (or disabled) and configured using
       the %feature hash. Names of gitweb features are keys of this hash.

       Each %feature hash element is a hash reference and has the following
       structure:

	   "<feature-name>" => {
		   "sub" => <feature-sub-(subroutine)>,
		   "override" => <allow-override-(boolean)>,
		   "default" => [ <options>... ]
	   },

       Some features cannot be overridden per project. For those features the
       structure of appropriate %feature hash element has a simpler form:

	   "<feature-name>" => {
		   "override" => 0,
		   "default" => [ <options>... ]
	   },

       As one can see it lacks the 'sub' element.

       The meaning of each part of feature configuration is described below:

       default
	   List (array reference) of feature parameters (if there are any),
	   used also to toggle (enable or disable) given feature.

	   Note that it is currently always an array reference, even if feature
	   doesn't accept any configuration parameters, and 'default' is used
	   only to turn it on or off. In such case you turn feature on by
	   setting this element to [1], and torn it off by setting it to [0].
	   See also the passage about the "blame" feature in the "Examples"
	   section.

	   To disable features that accept parameters (are configurable), you
	   need to set this element to empty list i.e.	[].

       override
	   If this field has a true value then the given feature is
	   overridable, which means that it can be configured (or
	   enabled/disabled) on a per-repository basis.

	   Usually given "<feature>" is configurable via the gitweb.<feature>
	   config variable in the per-repository Git configuration file.

	   Note that no feature is overridable by default.

       sub
	   Internal detail of implementation. What is important is that if this
	   field is not present then per-repository override for given feature
	   is not supported.

	   You wouldn't need to ever change it in gitweb config file.

   Features in %feature
       The gitweb features that are configurable via %feature hash are listed
       below. This should be a complete list, but ultimately the authoritative
       and complete list is in gitweb.cgi source code, with features described
       in the comments.

       blame
	   Enable the "blame" and "blame_incremental" blob views, showing for
	   each line the last commit that modified it; see git-blame(1). This
	   can be very CPU-intensive and is therefore disabled by default.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.blame configuration variable (boolean).

       snapshot
	   Enable and configure the "snapshot" action, which allows user to
	   download a compressed archive of any tree or commit, as produced by
	   git-archive(1) and possibly additionally compressed. This can
	   potentially generate high traffic if you have large project.

	   The value of 'default' is a list of names of snapshot formats,
	   defined in %known_snapshot_formats hash, that you wish to offer.
	   Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
	   compressed tar archive) and "zip"; please consult gitweb sources for
	   a definitive list. By default only "tgz" is offered.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.snapshot configuration variable, which contains
	   a comma separated list of formats or "none" to disable snapshots.
	   Unknown values are ignored.

       grep
	   Enable grep search, which lists the files in currently selected tree
	   (directory) containing the given string; see git-grep(1). This can
	   be potentially CPU-intensive, of course. Enabled by default.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.grep configuration variable (boolean).

       pickaxe
	   Enable the so called pickaxe search, which will list the commits
	   that introduced or removed a given string in a file. This can be
	   practical and quite faster alternative to "blame" action, but it is
	   still potentially CPU-intensive. Enabled by default.

	   The pickaxe search is described in git-log(1) (the description of
	   -S<string> option, which refers to pickaxe entry in gitdiffcore(7)
	   for more details).

	   This feature can be configured on a per-repository basis by setting
	   repository's gitweb.pickaxe configuration variable (boolean).

       show-sizes
	   Enable showing size of blobs (ordinary files) in a "tree" view, in a
	   separate column, similar to what ls -l does; see description of -l
	   option in git-ls-tree(1) manpage. This costs a bit of I/O. Enabled
	   by default.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.showSizes configuration variable (boolean).

       patches
	   Enable and configure "patches" view, which displays list of commits
	   in email (plain text) output format; see also git-format-patch(1).
	   The value is the maximum number of patches in a patchset generated
	   in "patches" view. Set the default field to a list containing single
	   item of or to an empty list to disable patch view, or to a list
	   containing a single negative number to remove any limit. Default
	   value is 16.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.patches configuration variable (integer).

       avatar
	   Avatar support. When this feature is enabled, views such as
	   "shortlog" or "commit" will display an avatar associated with the
	   email of each committer and author.

	   Currently available providers are "gravatar" and "picon". Only one
	   provider at a time can be selected (default is one element list). If
	   an unknown provider is specified, the feature is disabled.  Note
	   that some providers might require extra Perl packages to be
	   installed; see gitweb/INSTALL for more details.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.avatar configuration variable.

	   See also %avatar_size with pixel sizes for icons and avatars
	   ("default" is used for one-line like "log" and "shortlog", "double"
	   is used for two-line like "commit", "commitdiff" or "tag"). If the
	   default font sizes or lineheights are changed (e.g. via adding extra
	   CSS stylesheet in @stylesheets), it may be appropriate to change
	   these values.

       email-privacy
	   Redact e-mail addresses from the generated HTML, etc. content. This
	   obscures e-mail addresses retrieved from the author/committer and
	   comment sections of the Git log. It is meant to hinder web crawlers
	   that harvest and abuse addresses. Such crawlers may not respect
	   robots.txt. Note that users and user tools also see the addresses as
	   redacted. If Gitweb is not the final step in a workflow then
	   subsequent steps may misbehave because of the redacted information
	   they receive. Disabled by default.

       highlight
	   Server-side syntax highlight support in "blob" view. It requires
	   $highlight_bin program to be available (see the description of this
	   variable in the "Configuration variables" section above), and
	   therefore is disabled by default.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.highlight configuration variable (boolean).

       remote_heads
	   Enable displaying remote heads (remote-tracking branches) in the
	   "heads" list. In most cases the list of remote-tracking branches is
	   an unnecessary internal private detail, and this feature is
	   therefore disabled by default.  git-instaweb(1), which is usually
	   used to browse local repositories, enables and uses this feature.

	   This feature can be configured on a per-repository basis via
	   repository's gitweb.remote_heads configuration variable (boolean).

       The remaining features cannot be overridden on a per project basis.

       search
	   Enable text search, which will list the commits which match author,
	   committer or commit text to a given string; see the description of
	   --author, --committer and --grep options in git-log(1) manpage.
	   Enabled by default.

	   Project specific override is not supported.

       forks
	   If this feature is enabled, gitweb considers projects in
	   subdirectories of project root (basename) to be forks of existing
	   projects. For each project $projname.git, projects in the $projname/
	   directory and its subdirectories will not be shown in the main
	   projects list. Instead, a '+' mark is shown next to $projname, which
	   links to a "forks" view that lists all the forks (all projects in
	   $projname/ subdirectory). Additionally a "forks" view for a project
	   is linked from project summary page.

	   If the project list is taken from a file ($projects_list points to a
	   file), forks are only recognized if they are listed after the main
	   project in that file.

	   Project specific override is not supported.

       actions
	   Insert custom links to the action bar of all project pages. This
	   allows you to link to third-party scripts integrating into gitweb.

	   The "default" value consists of a list of triplets in the form
	   `("<label>", "<link>", "<position>")` where "position" is the label
	   after which to insert the link, "link" is a format string where %n
	   expands to the project name, %f to the project path within the
	   filesystem (i.e. "$projectroot/$project"), %h to the current hash
	   ('h' gitweb parameter) and `%b` to the current hash base ('hb'
	   gitweb parameter); `%%` expands to '%'.

	   For example, at the time this page was written, the
	   https://repo.or.cz Git hosting site set it to the following to
	   enable graphical log (using the third party tool git-browser):

	       $feature{'actions'}{'default'} =
		       [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];

	   This adds a link titled "graphiclog" after the "summary" link,
	   leading to git-browser script, passing r=<project> as a query
	   parameter.

	   Project specific override is not supported.

       timed
	   Enable displaying how much time and how many Git commands it took to
	   generate and display each page in the page footer (at the bottom of
	   page). For example the footer might contain: "This page took 6.53325
	   seconds and 13 Git commands to generate." Disabled by default.

	   Project specific override is not supported.

       javascript-timezone
	   Enable and configure the ability to change a common time zone for
	   dates in gitweb output via JavaScript. Dates in gitweb output
	   include authordate and committerdate in "commit", "commitdiff" and
	   "log" views, and taggerdate in "tag" view. Enabled by default.

	   The value is a list of three values: a default time zone (for if the
	   client hasn't selected some other time zone and saved it in a
	   cookie), a name of cookie where to store selected time zone, and a
	   CSS class used to mark up dates for manipulation. If you want to
	   turn this feature off, set "default" to empty list: [].

	   Typical gitweb config files will only change starting (default) time
	   zone, and leave other elements at their default values:

	       $feature{'javascript-timezone'}{'default'}[0] = "utc";

	   The example configuration presented here is guaranteed to be
	   backwards and forward compatible.

	   Time zone values can be "local" (for local time zone that browser
	   uses), "utc" (what gitweb uses when JavaScript or this feature is
	   disabled), or numerical time zones in the form of "+/-HHMM", such as
	   "+0200".

	   Project specific override is not supported.

       extra-branch-refs
	   List of additional directories under "refs" which are going to be
	   used as branch refs. For example if you have a gerrit setup where
	   all branches under refs/heads/ are official, push-after-review ones
	   and branches under refs/sandbox/, refs/wip and refs/other are user
	   ones where permissions are much wider, then you might want to set
	   this variable as follows:

	       $feature{'extra-branch-refs'}{'default'} =
		       ['sandbox', 'wip', 'other'];

	   This feature can be configured on per-repository basis after setting
	   $feature{extra-branch-refs}{override} to true, via repository's
	   gitweb.extraBranchRefs configuration variable, which contains a
	   space separated list of refs. An example:

	       [gitweb]
		       extraBranchRefs = sandbox wip other

	   The gitweb.extraBranchRefs is actually a multi-valued configuration
	   variable, so following example is also correct and the result is the
	   same as of the snippet above:

	       [gitweb]
		       extraBranchRefs = sandbox
		       extraBranchRefs = wip other

	   It is an error to specify a ref that does not pass "git
	   check-ref-format" scrutiny. Duplicated values are filtered.

EXAMPLES
       To enable blame, pickaxe search, and snapshot support (allowing "tar.gz"
       and "zip" snapshots), while allowing individual projects to turn them
       off, put the following in your GITWEB_CONFIG file:

	   $feature{'blame'}{'default'} = [1];
	   $feature{'blame'}{'override'} = 1;

	   $feature{'pickaxe'}{'default'} = [1];
	   $feature{'pickaxe'}{'override'} = 1;

	   $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
	   $feature{'snapshot'}{'override'} = 1;

       If you allow overriding for the snapshot feature, you can specify which
       snapshot formats are globally disabled. You can also add any
       command-line options you want (such as setting the compression level).
       For instance, you can disable Zip compressed snapshots and set gzip(1)
       to run at level 6 by adding the following lines to your gitweb
       configuration file:

	   $known_snapshot_formats{'zip'}{'disabled'} = 1;
	   $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];

BUGS
       Debugging would be easier if the fallback configuration file
       (/etc/gitweb.conf) and environment variable to override its location
       (GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. The
       current names are kept to avoid breaking working setups.

ENVIRONMENT
       The location of per-instance and system-wide configuration files can be
       overridden using the following environment variables:

       GITWEB_CONFIG
	   Sets location of per-instance configuration file.

       GITWEB_CONFIG_SYSTEM
	   Sets location of fallback system-wide configuration file. This file
	   is read only if per-instance one does not exist.

       GITWEB_CONFIG_COMMON
	   Sets location of common system-wide configuration file.

FILES
       gitweb_config.perl
	   This is default name of per-instance configuration file. The format
	   of this file is described above.

       /etc/gitweb.conf
	   This is default name of fallback system-wide configuration file.
	   This file is used only if per-instance configuration variable is not
	   found.

       /etc/gitweb-common.conf
	   This is default name of common system-wide configuration file.

SEE ALSO
       gitweb(1), git-instaweb(1)

       gitweb/README, gitweb/INSTALL

GIT
       Part of the git(1) suite

Git 2.47.3			   07/30/2025			 GITWEB.CONF(5)