NAME
----
-gitweb.conf - Gitweb (git web interface) configuration file
+gitweb.conf - Gitweb (Git web interface) configuration file
SYNOPSIS
--------
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
+of Git repository management tools) in a separate file, e.g. in
'/etc/gitweb-gitolite.conf'. To include it, put
--------------------------------------------------
Location of repositories
~~~~~~~~~~~~~~~~~~~~~~~~
The configuration variables described below control how gitweb finds
-git repositories, and how repositories are displayed and accessed.
+Git repositories, and how repositories are displayed and accessed.
See also "Repositories" and later subsections in linkgit:gitweb[1] manpage.
$project_maxdepth::
If `$projects_list` variable is unset, gitweb will recursively
- scan filesystem for git repositories. The `$project_maxdepth`
+ 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.
+
If not set (default), it means that this feature is disabled.
+
-See also more involved example in "Controlling access to git repositories"
+See also more involved example in "Controlling access to Git repositories"
subsection on linkgit:gitweb[1] manpage.
$strict_export::
$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
+ 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
+ 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,
+ 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.
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. Other popular choice it to
- set it to the name of site.
+ 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, http://git-scm.com[]; in the past, they pointed
- to git documentation at http://www.kernel.org[].
+ refer to Git homepage, http://git-scm.com[]; in the past, they pointed
+ to Git documentation at http://www.kernel.org[].
Changing gitweb's look
detection.
+
*Note* that rename and especially copy detection can be quite
-CPU-intensive. Note also that non git tools can have problems with
+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').
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
+ 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
override::
If this field has a true value then the given feature is
- overriddable, which means that it can be configured
+ 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.
+config variable in the per-repository Git configuration file.
+
-*Note* that no feature is overriddable by default.
+*Note* that no feature is overridable by default.
sub::
Internal detail of implementation. What is important is that
(\'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
+Git hosting site set it to the following to enable graphical log
(using the third party tool *git-browser*):
+
----------------------------------------------------------------------
Project specific override is not supported.
timed::
- Enable displaying how much time and how many git commands it took to
+ 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.
+ 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 timezone for dates
+ 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 timezone (for if the client
-hasn't selected some other timezone and saved it in a cookie), a name of cookie
-where to store selected timezone, and a CSS class used to mark up
+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) timezone,
+Typical gitweb config files will only change starting (default) time zone,
and leave other elements at their default values:
+
---------------------------------------------------------------------------
The example configuration presented here is guaranteed to be backwards
and forward compatible.
+
-Timezone values can be "local" (for local timezone that browser uses), "utc"
+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
-timezones in the form of "+/-HHMM", such as "+0200".
+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
--------
$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