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
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 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.
