path: root/Documentation/gitweb.conf.txt

gitweb.conf(5)
==============

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

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

DESCRIPTION
-----------

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
linkgit:gitweb[1] manpage.


DISCUSSION
----------
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
-----------------------
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 linkgit: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 linkgit: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