gitweb.conf(5) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | DISCUSSION | CONFIGURATION VARIABLES | CONFIGURING GITWEB FEATURES | EXAMPLES | BUGS | ENVIRONMENT | FILES | SEE ALSO | GIT | COLOPHON

GITWEB.CONF(5)                 Git Manual                 GITWEB.CONF(5)

NAME         top

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

SYNOPSIS         top

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

DESCRIPTION         top

       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         top

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

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

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

       •   either per-instance configuration file (defaults to
           gitweb_config.perl in the same directory as the installed
           gitweb), or if it does not exists 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         top

       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://www.andre-simon.de 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         top

       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.

       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
           http://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         top

       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         top

       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         top

       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         top

       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         top

       gitweb(1), git-instaweb(1)

       gitweb/README, gitweb/INSTALL

GIT         top

       Part of the git(1) suite

COLOPHON         top

       This page is part of the git (Git distributed version control
       system) project.  Information about the project can be found at
       ⟨http://git-scm.com/⟩.  If you have a bug report for this manual
       page, see ⟨http://git-scm.com/community⟩.  This page was obtained
       from the project's upstream Git repository
       ⟨https://github.com/git/git.git⟩ on 2021-04-01.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2021-03-30.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Git 2.31.1.163.ga65ce7         04/01/2021                 GITWEB.CONF(5)

Pages that refer to this page: git-config(1)gitweb(1)