Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GITWEB.CONF(5)			  Git Manual			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 gitweb(1) manpage.

DISCUSSION
       Gitweb reads configuration data from the	following sources in the
       following order:

       o   built-in values (some set during build stage),

       o   common system-wide configuration file (defaults to
	   /etc/gitweb-common.conf),

       o   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	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 gitweb(1) manpage.

       $strict_export
	   Only	allow viewing of repositories also shown on the	overview page.
	   This	for example makes $gitweb_export_ok file 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. 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 as "image/png" type. Web browsers that support favicons
	   (website icons) may display them in the browser's URL bar and next
	   to the site name in bookmarks. Relative to the base URI of gitweb.
	   Can be adjusted at build time using GITWEB_FAVICON variable.	By
	   default set to static/git-favicon.png.

       $javascript
	   Points to the location where	you put	gitweb.js on your web server,
	   or to be more generic the URI of JavaScript code used by gitweb.
	   Relative to the base	URI of gitweb. Can be set at build time	using
	   the GITWEB_JS build-time configuration variable.

	   The default value is	either static/gitweb.js, or
	   static/gitweb.min.js	if the JSMIN build variable was	defined, i.e.
	   if JavaScript minifier was used at build time.  Note	that this
	   single file is generated from multiple individual JavaScript
	   "modules".

       $home_link
	   Target of the home link on the top of all pages (the	first part of
	   view	"breadcrumbs").	By default it is set to	the absolute URI of a
	   current page	(to the	value of $my_uri variable, or to "/" if
	   $my_uri is undefined	or is an empty string).

       $home_link_str
	   Label for the "home link" at	the top	of all pages, leading to
	   $home_link (usually the main	gitweb page, which contains the
	   projects list). It is 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. 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, https://git-scm.com; in the past, they
	   pointed to Git documentation	at https://www.kernel.org.

   Changing gitweb's look
       You can adjust how pages	generated by gitweb look using the variables
       described below.	You can	change the site	name, add common headers and
       footers for all pages, and add a	description of this gitweb
       installation on its main	page (which is the projects list page),	etc.

       $site_name
	   Name	of your	site or	organization, to appear	in page	titles.	Set it
	   to something	descriptive for	clearer	bookmarks etc. If this
	   variable is not set or is, then gitweb uses the value of the
	   SERVER_NAMECGI environment variable,	setting	site name to
	   "$SERVER_NAME Git", or "Untitled Git" if this variable is not set
	   (e.g. if running gitweb as standalone script).

	   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. Can be
	   set using GITWEB_SITE_HEADER	at build time. No default value.

       $site_footer
	   Name	of a file with HTML to be included at the bottom of each page.
	   Relative to the directory containing	the gitweb.cgi script. Can be
	   set using GITWEB_SITE_FOOTER	at build time. No default value.

       $home_text
	   Name	of a HTML file which, if it exists, is included	on the gitweb
	   projects overview page ("projects_list" view). Relative to the
	   directory containing	the gitweb.cgi script. Default value can be
	   adjusted during build time using GITWEB_HOMETEXT variable. By
	   default set to indextext.html.

       $projects_list_description_width
	   The width (in characters) of	the "Description" column of the
	   projects list. Longer descriptions will be truncated	(trying	to cut
	   at word boundary); the full description is available	in the title
	   attribute (usually shown on mouseover). The default is 25, which
	   might be too	small if you use long project descriptions.

       $default_projects_order
	   Default value of ordering of	projects on projects list page,	which
	   means the ordering used if you don't	explicitly sort	projects list
	   (if there is	no "o" CGI query parameter in the URL).	Valid values
	   are "none" (unsorted), "project" (projects are by project name,
	   i.e.	path to	repository relative to $projectroot), "descr" (project
	   description), "owner", and "age" (by	date of	most current commit).

	   Default value is "project". Unknown value means unsorted.

   Changing gitweb's behavior
       These configuration variables control internal gitweb behavior.

       $default_blob_plain_mimetype
	   Default mimetype for	the blob_plain (raw) view, if mimetype
	   checking doesn't result in some other type; by default
	   "text/plain". Gitweb	guesses	mimetype of a file to display based on
	   extension of	its filename, using $mimetypes_file (if	set and	file
	   exists) and /etc/mime.types files (see mime.types(5)	manpage; only
	   filename extension rules are	supported by gitweb).

       $default_text_plain_charset
	   Default charset for text files. If this is not set, the web server
	   configuration will be used. Unset by	default.

       $fallback_encoding
	   Gitweb assumes this charset when a line contains non-UTF-8
	   characters. The fallback decoding is	used without error checking,
	   so it can be	even "utf-8". The value	must be	a valid	encoding; see
	   the Encoding::Supported(3pm)	man page for a list. The default is
	   "latin1", aka. "iso-8859-1".

       @diff_opts
	   Rename detection options for	git-diff and git-diff-tree. The
	   default is ('-M'); set it to	('-C') or ('-C', '-C') to also detect
	   copies, or set it to	() i.e.	empty list if you don't	want to	have
	   renames detection.

	   Note	that rename and	especially copy	detection can be quite
	   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').

   Some	optional features and policies
       Most of features	are configured via %feature hash; however some of
       extra gitweb features can be turned on and configured using variables
       described below.	This list beside configuration variables that control
       how gitweb looks	does contain variables configuring administrative side
       of gitweb (e.g. cross-site scripting prevention;	admittedly this	as
       side effect 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
	   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 (for example one for git:// protocol, and
	   one for http:// protocol).

	   Note	that per repository configuration can be set in
	   $GIT_DIR/cloneurl file, or as values	of multi-value gitweb.url
	   configuration variable in project config. Per-repository
	   configuration takes precedence over value 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 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.

       $projects_list_group_categories
	   Whether to enable 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 each
	   repository's	configuration. Disabled	by default (set	to 0).

       $project_list_default_category
	   Default category for	projects for which none	is specified. If this
	   is set to the empty string, such projects will remain uncategorized
	   and listed at the top, above	categorized projects. Used only	if
	   project categories are enabled, which means if
	   $projects_list_group_categories is true. By default set to ""
	   (empty string).

       $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.
	   False by default (set to 0).

       $maxload
	   Used	to set the maximum load	that we	will still respond to gitweb
	   queries. If the server load exceeds this value then gitweb will
	   return "503 Service Unavailable" error. The server load is taken to
	   be 0	if gitweb cannot determine its value. Currently	it works only
	   on Linux, where it uses /proc/loadavg; the load there is the	number
	   of active tasks on the system -- processes that are actually
	   running -- averaged over the	last minute.

	   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. For example, one might use	the following code in a	gitweb
	   configuration file

	       our $per_request_config = sub {
		       $ENV{GL_USER} = $cgi->remote_user || "gitweb";
	       };

	   If $per_request_config is not a code	reference, it is interpreted
	   as boolean value. If	it is true gitweb will process config files
	   once	per request, and if it is false	gitweb will process config
	   files only once, each time it is executed. True by default (set to
	   1).

	   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.

	   This	variable matters only when using persistent web	environments
	   that	serve multiple requests	using single gitweb instance, like
	   mod_perl, FastCGI or	Plackup.

   Other variables
       Usually you should not need to change (adjust) any of configuration
       variables described below; they should be automatically set by gitweb
       to correct value.

       $version
	   Gitweb version, set automatically when creating gitweb.cgi from
	   gitweb.perl.	You might want to modify it if you are running
	   modified gitweb, for	example

	       our $version .= " with caching";

	   if you run modified version of gitweb with caching support. This
	   variable is purely informational, used e.g. in the "generator" meta
	   header in HTML header.

       $my_url,	$my_uri
	   Full	URL and	absolute URL of	the gitweb script; in earlier versions
	   of gitweb you might have need to set	those variables, but 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 _base href="$base_url"_ only for URLs with nonempty
	   PATH_INFO. 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 override it anyway.

CONFIGURING GITWEB FEATURES
       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.blame 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.

       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 hosting site set it to	the following to
	   enable graphical log	(using the third party tool 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.

EXAMPLES
       To enable blame,	pickaxe	search,	and snapshot support (allowing
       "tar.gz"	and "zip" snapshots), while allowing individual	projects to
       turn them off, put the following	in your	GITWEB_CONFIG file:

	   $feature{'blame'}{'default'}	= [1];
	   $feature{'blame'}{'override'} = 1;

	   $feature{'pickaxe'}{'default'} = [1];
	   $feature{'pickaxe'}{'override'} = 1;

	   $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
	   $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 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
       overridden using	the following environment variables:

       GITWEB_CONFIG
	   Sets	location of per-instance configuration file.

       GITWEB_CONFIG_SYSTEM
	   Sets	location of fallback system-wide configuration file. This file
	   is read only	if per-instance	one does not exist.

       GITWEB_CONFIG_COMMON
	   Sets	location of common system-wide configuration file.

FILES
       gitweb_config.perl
	   This	is default name	of per-instance	configuration file. The	format
	   of this file	is described above.

       /etc/gitweb.conf
	   This	is default name	of fallback system-wide	configuration file.
	   This	file is	used only if per-instance configuration	variable is
	   not found.

       /etc/gitweb-common.conf
	   This	is default name	of common system-wide configuration file.

SEE ALSO
       gitweb(1), git-instaweb(1)

       gitweb/README, gitweb/INSTALL

GIT
       Part of the git(1) suite

Git 2.13.2			  06/24/2017			GITWEB.CONF(5)

NAME | SYNOPSIS | DESCRIPTION | DISCUSSION | CONFIGURATION VARIABLES | CONFIGURING GITWEB FEATURES | EXAMPLES | BUGS | ENVIRONMENT | FILES | SEE ALSO | GIT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gitweb.conf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help