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
http://repo.or.cz 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.
