NAME
----
-gitweb.conf - Gitweb (git web interface) configuration file
+gitweb.conf - Gitweb (Git web interface) configuration file
SYNOPSIS
--------
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
+linkgit:gitweb[1] manpage.
+
DISCUSSION
----------
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.
$projectroot::
Absolute filesystem path which will be prepended to project path;
$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"
+subsection on linkgit:gitweb[1] manpage.
$strict_export::
Only allow viewing of repositories also shown on the overview page.
$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.
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 hightlighting.
+ use syntax highlighting.
+
*NOTE*: if you want to add support for new file type (supported by
"highlight" but not used by gitweb), you need to modify `%highlight_ext`
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
+
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.
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
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` built-time configuration variable.
+ 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.
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.
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
I/O. Enabled by default.
+
This feature can be configured on a per-repository basis via
-repository's `gitweb.showsizes` configuration variable (boolean).
+repository's `gitweb.showSizes` configuration variable (boolean).
patches::
Enable and configure "patches" view, which displays list of commits in email
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
+ 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
+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.
+
(\'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
--------
$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
+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