From the git version 1.4.0 gitweb is bundled with git.
-How to configure gitweb for your local system
----------------------------------------------
-
-See also the "Build time configuration" section in the INSTALL
-file for gitweb (in gitweb/INSTALL).
-
-You can specify the following configuration variables when building GIT:
- * GIT_BINDIR
- Points where to find the git executable. You should set it up to
- the place where the git binary was installed (usually /usr/bin) if you
- don't install git from sources together with gitweb. [Default: $(bindir)]
- * GITWEB_SITENAME
- Shown in the title of all generated pages, defaults to the server name
- (SERVER_NAME CGI environment variable) if not set. [No default]
- * GITWEB_PROJECTROOT
- The root directory for all projects shown by gitweb. Must be set
- correctly for gitweb to find repositories to display. See also
- "Gitweb repositories" in the INSTALL file for gitweb. [Default: /pub/git]
- * GITWEB_PROJECT_MAXDEPTH
- The filesystem traversing limit for getting the project list; the number
- is taken as depth relative to the projectroot. It is used when
- GITWEB_LIST is a directory (or is not set; then project root is used).
- This is meant to speed up project listing on large work trees by limiting
- search depth. [Default: 2007]
- * GITWEB_LIST
- Points to a directory to scan for projects (defaults to project root
- if not set / if empty) or to a file with explicit listing of projects
- (together with projects' ownership). See "Generating projects list
- using gitweb" in INSTALL file for gitweb to find out how to generate
- such file from scan of a directory. [No default, which means use root
- directory for projects]
- * GITWEB_EXPORT_OK
- Show repository only if this file exists (in repository). Only
- effective if this variable evaluates to true. [No default / Not set]
- * GITWEB_STRICT_EXPORT
- Only allow viewing of repositories also shown on the overview page.
- This for example makes GITWEB_EXPORT_OK to decide if repository is
- available and not only if it is shown. If GITWEB_LIST points to
- file with list of project, only those repositories listed would be
- available for gitweb. [No default]
- * GITWEB_HOMETEXT
- Points to an .html file which is included on the gitweb project
- overview page ('projects_list' view), if it exists. Relative to
- gitweb.cgi script. [Default: indextext.html]
- * GITWEB_SITE_HEADER
- Filename of html text to include at top of each page. Relative to
- gitweb.cgi script. [No default]
- * GITWEB_SITE_FOOTER
- Filename of html text to include at bottom of each page. Relative to
- gitweb.cgi script. [No default]
- * GITWEB_HOME_LINK_STR
- String of the home link on top of all pages, leading to $home_link
- (usually main gitweb page, which means projects list). Used as first
- part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
- [Default: projects]
- * GITWEB_SITENAME
- Name of your site or organization to appear in page titles. Set it
- to something descriptive for clearer bookmarks etc. If not set
- (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if
- SERVER_NAME CGI environment variable is not set (e.g. if running
- gitweb as standalone script). [No default]
- * GITWEB_BASE_URL
- Git base URLs used for URL to where fetch project from, i.e. full
- URL is "$git_base_url/$project". Shown on projects summary page.
- Repository URL for project can be also configured per repository; this
- takes precedence over URLs composed from base URL and a project name.
- Note that you can setup multiple base URLs (for example one for
- git:// protocol access, another for http:// access) from the gitweb
- config file. [No default]
- * GITWEB_CSS
- Points to the location where you put gitweb.css on your web server
- (or to be more generic, the URI of gitweb stylesheet). Relative to the
- base URI of gitweb. Note that you can setup multiple stylesheets from
- the gitweb config file. [Default: static/gitweb.css (or
- static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier
- is used)]
- * GITWEB_LOGO
- Points to the location where you put git-logo.png on your web server
- (or to be more generic URI of logo, 72x27 size, displayed in top right
- corner of each gitweb page, and used as logo for Atom feed). Relative
- to base URI of gitweb. [Default: static/git-logo.png]
- * GITWEB_FAVICON
- Points to the location where you put git-favicon.png on your web server
- (or to be more generic URI of favicon, assumed to be image/png type;
- web browsers that support favicons (website icons) may display them
- in the browser's URL bar and next to site name in bookmarks). Relative
- to base URI of gitweb. [Default: static/git-favicon.png]
- * GITWEB_JS
- Points to the location where you put gitweb.js on your web server
- (or to be more generic URI of JavaScript code used by gitweb).
- Relative to base URI of gitweb. [Default: static/gitweb.js (or
- static/gitweb.min.js if JSMIN build variable is defined / JavaScript
- minifier is used)]
- * GITWEB_CONFIG
- This Perl file will be loaded using 'do' and can be used to override any
- of the options above as well as some other options -- see the "Runtime
- gitweb configuration" section below, and top of 'gitweb.cgi' for their
- full list and description. If the environment variable GITWEB_CONFIG
- is set when gitweb.cgi is executed, then the file specified in the
- environment variable will be loaded instead of the file specified
- when gitweb.cgi was created. [Default: gitweb_config.perl]
- * GITWEB_CONFIG_SYSTEM
- This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG
- does not exist. If the environment variable GITWEB_CONFIG_SYSTEM is set
- when gitweb.cgi is executed, then the file specified in the environment
- variable will be loaded instead of the file specified when gitweb.cgi was
- created. [Default: /etc/gitweb.conf]
- * HIGHLIGHT_BIN
- Path to the highlight executable to use (must be the one from
- http://www.andre-simon.de due to assumptions about parameters and output).
- Useful if highlight is not installed on your webserver's PATH.
- [Default: highlight]
-
-
Runtime gitweb configuration
----------------------------
-You can adjust gitweb behaviour using the file specified in `GITWEB_CONFIG`
-(defaults to 'gitweb_config.perl' in the same directory as the CGI), and
-as a fallback `GITWEB_CONFIG_SYSTEM` (defaults to /etc/gitweb.conf).
+Gitweb obtains configuration data from the following sources in the
+following order:
+
+1. built-in values (some set during build stage),
+2. common system-wide configuration file (`GITWEB_CONFIG_COMMON`,
+ defaults to '/etc/gitweb-common.conf'),
+3. either per-instance configuration file (`GITWEB_CONFIG`, defaults to
+ 'gitweb_config.perl' in the same directory as the installed gitweb),
+ or if it does not exists then system-wide configuration file
+ (`GITWEB_CONFIG_SYSTEM`, defaults to '/etc/gitweb.conf').
+
+Values obtained in later configuration files override values obtained earlier
+in above sequence.
+
+You can read defaults in system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG
+by adding
+
+ read_config_file($GITWEB_CONFIG_SYSTEM);
+
+at very beginning of per-instance GITWEB_CONFIG file. In this case
+settings in said per-instance file will override settings from
+system-wide configuration file. Note that read_config_file checks
+itself that the $GITWEB_CONFIG_SYSTEM file exists.
+
The most notable thing that is not configurable at compile time are the
optional features, stored in the '%features' variable.
in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
as comments inside 'gitweb.cgi'.
-See also the "Gitweb config file" (with an example of config file), and
-the "Gitweb repositories" sections in INSTALL file for gitweb.
-
-
-The gitweb config file is a fragment of perl code. You can set variables
-using "our $variable = value"; text from "#" character until the end
-of a line is ignored. See perlsyn(1) man page for details.
-
-Below is the list of variables which you might want to set in gitweb config.
-See the top of 'gitweb.cgi' for the full list of variables and their
-descriptions.
-
-Gitweb config file variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can set, among others, the following variables in gitweb config files
-(with the exception of $projectroot and $projects_list this list does
-not include variables usually directly set during build):
- * $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 from binary
- package, set this to "/usr/bin/git". This can just be "git" if your
- webserver has a sensible PATH. If you have multiple git versions
- installed it can be used to choose which one to use.
- * $version
- Gitweb version, set automatically when creating gitweb.cgi from
- gitweb.perl. You might want to modify it if you are running modified
- gitweb.
- * $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 have to be
- set correctly for gitweb to find repositories.
- * $projects_list
- Source of projects list, either directory to scan, or text file
- with list of repositories (in the "<URI-encoded repository path> SP
- <URI-encoded repository owner>" line format; actually there can be
- any sequence of whitespace in place of space (SP)). Set to
- $GITWEB_LIST during installation. If empty, $projectroot is used
- to scan for repositories.
- * $my_url, $my_uri
- Full URL and absolute URL of gitweb script;
- in earlier versions of gitweb you might have need to set those
- variables, 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 only for URLs with nonempty PATH_INFO via
- <base href="$base_url">. 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 set it anyway.
- * $home_link
- Target of the home link on top of all pages (the first part of view
- "breadcrumbs"). By default set to absolute URI of a page ($my_uri).
- * @stylesheets
- List of URIs of stylesheets (relative to base URI of a page). You
- might specify more than one stylesheet, for example use gitweb.css
- as base, with site specific modifications in separate stylesheet
- to make it easier to upgrade gitweb. You can add 'site' stylesheet
- for example by using
- push @stylesheets, "gitweb-site.css";
- in the gitweb config file.
- * $logo_url, $logo_label
- URI and label (title) of GIT logo link (or your site logo, if you choose
- to use different logo image). By default they point to git homepage;
- in the past they pointed to git documentation at www.kernel.org.
- * $projects_list_description_width
- The width (in characters) of the projects list "Description" column.
- Longer descriptions will be cut (trying to cut at word boundary);
- full description is available as 'title' attribute (usually shown on
- mouseover). By default set to 25, which might be too small if you
- use long project descriptions.
- * $projects_list_group_categories
- Enables 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 its repository configuration.
- Disabled by default.
- * $project_list_default_category
- Default category for projects for which none is specified. If set
- to the empty string, such projects will remain uncategorized and
- listed at the top, above categorized projects.
- * @git_base_url_list
- List of git base URLs used for URL to where fetch project from, shown
- in project summary page. Full URL is "$git_base_url/$project".
- You can setup multiple base URLs (for example one for git:// protocol
- access, and one for http:// "dumb" protocol access). Note that per
- repository configuration in 'cloneurl' file, or as values of gitweb.url
- project config.
- * $default_blob_plain_mimetype
- Default mimetype for blob_plain (raw) view, if mimetype checking
- doesn't result in some other type; by default 'text/plain'.
- * $default_text_plain_charset
- Default charset for text files. If not set, web server configuration
- would be used.
- * $mimetypes_file
- File to use for (filename extension based) guessing of MIME types before
- trying /etc/mime.types. Path, if relative, is taken currently as
- relative to the current git repository.
- * $fallback_encoding
- Gitweb assumes this charset if line contains non-UTF-8 characters.
- Fallback decoding is used without error checking, so it can be even
- 'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man
- page for a list. By default 'latin1', aka. 'iso-8859-1'.
- * @diff_opts
- Rename detection options for git-diff and git-diff-tree. By default
- ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
- set it to () if you don't want to have renames detection.
- * $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. The default
- is false.
- * $maxload
- Used to set the maximum load that we will still respond to gitweb queries.
- If server load exceed this value then return "503 Service Unavailable" error.
- Server load is taken to be 0 if gitweb cannot determine its value. Set it to
- undefined value to turn it off. The default is 300.
- * $highlight_bin
- Path to the highlight executable to use (must be the one from
- http://www.andre-simon.de due to assumptions about parameters and output).
- Useful if highlight is not installed on your webserver's PATH.
- [Default: highlight]
- * $per_request_config
- If set to code reference, it would be run once per each request. You can
- set parts of configuration that change per session, e.g. by setting it to
- sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
- Otherwise it is treated as boolean value: if true gitweb would process
- config file once per request, if false it would process config file only
- once. 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. The default is true.
+See also gitweb.conf(5) manpage.
+
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~