]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/gitweb.conf.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / gitweb.conf.txt
CommitLineData
6d3902b0
DN
1gitweb.conf(5)
2==============
3
4NAME
5----
2de9b711 6gitweb.conf - Gitweb (Git web interface) configuration file
6d3902b0
DN
7
8SYNOPSIS
9--------
10/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl
11
12DESCRIPTION
13-----------
14
15The gitweb CGI script for viewing Git repositories over the web uses a
16perl script fragment as its configuration file. You can set variables
17using "`our $variable = value`"; text from a "#" character until the
18end of a line is ignored. See *perlsyn*(1) for details.
19
20An example:
21
9aab3fcf
AH
22------------------------------------------------
23# gitweb configuration file for http://git.example.org
24#
25our $projectroot = "/srv/git"; # FHS recommendation
26our $site_name = 'Example.org >> Repos';
27------------------------------------------------
6d3902b0
DN
28
29
30The configuration file is used to override the default settings that
31were built into gitweb at the time the 'gitweb.cgi' script was generated.
32
33While one could just alter the configuration settings in the gitweb
34CGI itself, those changes would be lost upon upgrade. Configuration
35settings might also be placed into a file in the same directory as the
36CGI script with the default name 'gitweb_config.perl' -- allowing
37one to have multiple gitweb instances with different configurations by
38the use of symlinks.
39
07ea4df2
JN
40Note that some configuration can be controlled on per-repository rather than
41gitweb-wide basis: see "Per-repository gitweb configuration" subsection on
42linkgit:gitweb[1] manpage.
43
6d3902b0
DN
44
45DISCUSSION
46----------
47Gitweb reads configuration data from the following sources in the
48following order:
49
50 * built-in values (some set during build stage),
51
52 * common system-wide configuration file (defaults to
68ed71b5 53 `/etc/gitweb-common.conf`),
6d3902b0
DN
54
55 * either per-instance configuration file (defaults to 'gitweb_config.perl'
56 in the same directory as the installed gitweb), or if it does not exists
68ed71b5 57 then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`).
6d3902b0
DN
58
59Values obtained in later configuration files override values obtained earlier
60in the above sequence.
61
62Locations of the common system-wide configuration file, the fallback
63system-wide configuration file and the per-instance configuration file
64are defined at compile time using build-time Makefile configuration
65variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`
66and `GITWEB_CONFIG`.
67
68You can also override locations of gitweb configuration files during
69runtime by setting the following environment variables:
70`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`
71to a non-empty value.
72
73
74The syntax of the configuration files is that of Perl, since these files are
75handled by sourcing them as fragments of Perl code (the language that
76gitweb itself is written in). Variables are typically set using the
77`our` qualifier (as in "`our $variable = <value>;`") to avoid syntax
78errors if a new version of gitweb no longer uses a variable and therefore
79stops declaring it.
80
81You can include other configuration file using read_config_file()
82subroutine. For example, one might want to put gitweb configuration
83related to access control for viewing repositories via Gitolite (one
2de9b711 84of Git repository management tools) in a separate file, e.g. in
68ed71b5 85`/etc/gitweb-gitolite.conf`. To include it, put
6d3902b0
DN
86
87--------------------------------------------------
88read_config_file("/etc/gitweb-gitolite.conf");
89--------------------------------------------------
90
91somewhere in gitweb configuration file used, e.g. in per-installation
92gitweb configuration file. Note that read_config_file() checks itself
93that the file it reads exists, and does nothing if it is not found.
94It also handles errors in included file.
95
96
97The default configuration with no configuration file at all may work
98perfectly well for some installations. Still, a configuration file is
99useful for customizing or tweaking the behavior of gitweb in many ways, and
100some optional features will not be present unless explicitly enabled using
101the configurable `%features` variable (see also "Configuring gitweb
102features" section below).
103
104
105CONFIGURATION VARIABLES
106-----------------------
107Some configuration variables have their default values (embedded in the CGI
108script) set during building gitweb -- if that is the case, this fact is put
109in their description. See gitweb's 'INSTALL' file for instructions on building
110and installing gitweb.
111
112
113Location of repositories
114~~~~~~~~~~~~~~~~~~~~~~~~
115The configuration variables described below control how gitweb finds
2de9b711 116Git repositories, and how repositories are displayed and accessed.
6d3902b0 117
07ea4df2
JN
118See also "Repositories" and later subsections in linkgit:gitweb[1] manpage.
119
6d3902b0
DN
120$projectroot::
121 Absolute filesystem path which will be prepended to project path;
122 the path to repository is `$projectroot/$project`. Set to
123 `$GITWEB_PROJECTROOT` during installation. This variable has to be
124 set correctly for gitweb to find repositories.
125+
126For example, if `$projectroot` is set to "/srv/git" by putting the following
127in gitweb config file:
128+
129----------------------------------------------------------------------------
130our $projectroot = "/srv/git";
131----------------------------------------------------------------------------
132+
133then
134+
135------------------------------------------------
136http://git.example.com/gitweb.cgi?p=foo/bar.git
137------------------------------------------------
138+
139and its path_info based equivalent
140+
141------------------------------------------------
142http://git.example.com/gitweb.cgi/foo/bar.git
143------------------------------------------------
144+
68ed71b5 145will map to the path `/srv/git/foo/bar.git` on the filesystem.
6d3902b0
DN
146
147$projects_list::
148 Name of a plain text file listing projects, or a name of directory
149 to be scanned for projects.
150+
151Project list files should list one project per line, with each line
152having the following format
153+
154-----------------------------------------------------------------------------
155<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
156-----------------------------------------------------------------------------
157+
158The default value of this variable is determined by the `GITWEB_LIST`
159makefile variable at installation time. If this variable is empty, gitweb
160will fall back to scanning the `$projectroot` directory for repositories.
161
162$project_maxdepth::
163 If `$projects_list` variable is unset, gitweb will recursively
2de9b711 164 scan filesystem for Git repositories. The `$project_maxdepth`
6d3902b0
DN
165 is used to limit traversing depth, relative to `$projectroot`
166 (starting point); it means that directories which are further
167 from `$projectroot` than `$project_maxdepth` will be skipped.
168+
169It is purely performance optimization, originally intended for MacOS X,
170where recursive directory traversal is slow. Gitweb follows symbolic
171links, but it detects cycles, ignoring any duplicate files and directories.
172+
173The default value of this variable is determined by the build-time
174configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to
1752007.
176
177$export_ok::
178 Show repository only if this file exists (in repository). Only
179 effective if this variable evaluates to true. Can be set when
180 building gitweb by setting `GITWEB_EXPORT_OK`. This path is
181 relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok',
182 unless started with `--export-all`. By default this variable is
183 not set, which means that this feature is turned off.
184
185$export_auth_hook::
186 Function used to determine which repositories should be shown.
187 This subroutine should take one parameter, the full path to
188 a project, and if it returns true, that project will be included
189 in the projects list and can be accessed through gitweb as long
190 as it fulfills the other requirements described by $export_ok,
191 $projects_list, and $projects_maxdepth. Example:
192+
193----------------------------------------------------------------------------
194our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
195----------------------------------------------------------------------------
196+
197though the above might be done by using `$export_ok` instead
198+
199----------------------------------------------------------------------------
200our $export_ok = "git-daemon-export-ok";
201----------------------------------------------------------------------------
202+
203If not set (default), it means that this feature is disabled.
07ea4df2 204+
2de9b711 205See also more involved example in "Controlling access to Git repositories"
07ea4df2 206subsection on linkgit:gitweb[1] manpage.
6d3902b0
DN
207
208$strict_export::
209 Only allow viewing of repositories also shown on the overview page.
f116ee21
DO
210 This for example makes `$export_ok` file decide if repository is
211 available and not only if it is shown. If `$projects_list` points to
6d3902b0
DN
212 file with list of project, only those repositories listed would be
213 available for gitweb. Can be set during building gitweb via
214 `GITWEB_STRICT_EXPORT`. By default this variable is not set, which
215 means that you can directly access those repositories that are hidden
216 from projects list page (e.g. the are not listed in the $projects_list
217 file).
218
219
220Finding files
221~~~~~~~~~~~~~
222The following configuration variables tell gitweb where to find files.
223The values of these variables are paths on the filesystem.
224
225$GIT::
226 Core git executable to use. By default set to `$GIT_BINDIR/git`, which
2de9b711 227 in turn is by default set to `$(bindir)/git`. If you use Git installed
6d3902b0
DN
228 from a binary package, you should usually set this to "/usr/bin/git".
229 This can just be "git" if your web server has a sensible PATH; from
230 security point of view it is better to use absolute path to git binary.
2de9b711 231 If you have multiple Git versions installed it can be used to choose
6d3902b0
DN
232 which one to use. Must be (correctly) set for gitweb to be able to
233 work.
234
235$mimetypes_file::
236 File to use for (filename extension based) guessing of MIME types before
68ed71b5 237 trying `/etc/mime.types`. *NOTE* that this path, if relative, is taken
2de9b711 238 as relative to the current Git repository, not to CGI script. If unset,
68ed71b5 239 only `/etc/mime.types` is used (if present on filesystem). If no mimetypes
6d3902b0
DN
240 file is found, mimetype guessing based on extension of file is disabled.
241 Unset by default.
242
243$highlight_bin::
244 Path to the highlight executable to use (it must be the one from
245 http://www.andre-simon.de[] due to assumptions about parameters and output).
246 By default set to 'highlight'; set it to full path to highlight
247 executable if it is not installed on your web server's PATH.
248 Note that 'highlight' feature must be set for gitweb to actually
b4ab1980 249 use syntax highlighting.
6d3902b0 250+
779a2066
IK
251*NOTE*: for a file to be highlighted, its syntax type must be detected
252and that syntax must be supported by "highlight". The default syntax
253detection is minimal, and there are many supported syntax types with no
254detection by default. There are three options for adding syntax
255detection. The first and second priority are `%highlight_basename` and
256`%highlight_ext`, which detect based on basename (the full filename, for
257example "Makefile") and extension (for example "sh"). The keys of these
258hashes are the basename and extension, respectively, and the value for a
259given key is the name of the syntax to be passed via `--syntax <syntax>`
260to "highlight". The last priority is the "highlight" configuration of
261`Shebang` regular expressions to detect the language based on the first
262line in the file, (for example, matching the line "#!/bin/bash"). See
263the highlight documentation and the default config at
264/etc/highlight/filetypes.conf for more details.
6d3902b0
DN
265+
266For example if repositories you are hosting use "phtml" extension for
267PHP files, and you want to have correct syntax-highlighting for those
268files, you can add the following to gitweb configuration:
269+
270---------------------------------------------------------
271our %highlight_ext;
272$highlight_ext{'phtml'} = 'php';
273---------------------------------------------------------
274
275
276Links and their targets
277~~~~~~~~~~~~~~~~~~~~~~~
278The configuration variables described below configure some of gitweb links:
279their target and their look (text or image), and where to find page
280prerequisites (stylesheet, favicon, images, scripts). Usually they are left
281at their default values, with the possible exception of `@stylesheets`
282variable.
283
284@stylesheets::
285 List of URIs of stylesheets (relative to the base URI of a page). You
286 might specify more than one stylesheet, for example to use "gitweb.css"
287 as base with site specific modifications in a separate stylesheet
288 to make it easier to upgrade gitweb. For example, you can add
289 a `site` stylesheet by putting
290+
291----------------------------------------------------------------------------
292push @stylesheets, "gitweb-site.css";
293----------------------------------------------------------------------------
294+
295in the gitweb config file. Those values that are relative paths are
296relative to base URI of gitweb.
297+
298This list should contain the URI of gitweb's standard stylesheet. The default
299URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS`
68ed71b5
CB
300makefile variable. Its default value is `static/gitweb.css`
301(or `static/gitweb.min.css` if the `CSSMIN` variable is defined,
6d3902b0
DN
302i.e. if CSS minifier is used during build).
303+
304*Note*: there is also a legacy `$stylesheet` configuration variable, which was
305used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet
306given by this variable is used by gitweb.
307
308$logo::
309 Points to the location where you put 'git-logo.png' on your web
310 server, or to be more the generic URI of logo, 72x27 size). This image
311 is displayed in the top right corner of each gitweb page and used as
312 a logo for the Atom feed. Relative to the base URI of gitweb (as a path).
313 Can be adjusted when building gitweb using `GITWEB_LOGO` variable
68ed71b5 314 By default set to `static/git-logo.png`.
6d3902b0
DN
315
316$favicon::
317 Points to the location where you put 'git-favicon.png' on your web
318 server, or to be more the generic URI of favicon, which will be served
319 as "image/png" type. Web browsers that support favicons (website icons)
320 may display them in the browser's URL bar and next to the site name in
321 bookmarks. Relative to the base URI of gitweb. Can be adjusted at
322 build time using `GITWEB_FAVICON` variable.
68ed71b5 323 By default set to `static/git-favicon.png`.
6d3902b0
DN
324
325$javascript::
326 Points to the location where you put 'gitweb.js' on your web server,
327 or to be more generic the URI of JavaScript code used by gitweb.
328 Relative to the base URI of gitweb. Can be set at build time using
329 the `GITWEB_JS` build-time configuration variable.
330+
68ed71b5 331The default value is either `static/gitweb.js`, or `static/gitweb.min.js` if
6d3902b0
DN
332the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used
333at build time. *Note* that this single file is generated from multiple
334individual JavaScript "modules".
335
336$home_link::
337 Target of the home link on the top of all pages (the first part of view
338 "breadcrumbs"). By default it is set to the absolute URI of a current page
339 (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined
340 or is an empty string).
341
342$home_link_str::
343 Label for the "home link" at the top of all pages, leading to `$home_link`
344 (usually the main gitweb page, which contains the projects list). It is
345 used as the first component of gitweb's "breadcrumb trail":
346 `<home link> / <project> / <action>`. Can be set at build time using
347 the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects",
ad9c2e22
TF
348 as this link leads to the list of projects. Another popular choice is to
349 set it to the name of site. Note that it is treated as raw HTML so it
350 should not be set from untrusted sources.
351
352@extra_breadcrumbs::
353 Additional links to be added to the start of the breadcrumb trail before
354 the home link, to pages that are logically "above" the gitweb projects
355 list, such as the organization and department which host the gitweb
356 server. Each element of the list is a reference to an array, in which
357 element 0 is the link text (equivalent to `$home_link_str`) and element
358 1 is the target URL (equivalent to `$home_link`).
359+
360For example, the following setting produces a breadcrumb trail like
361"home / dev / projects / ..." where "projects" is the home link.
9aab3fcf 362+
ad9c2e22
TF
363----------------------------------------------------------------------------
364 our @extra_breadcrumbs = (
365 [ 'home' => 'https://www.example.org/' ],
366 [ 'dev' => 'https://dev.example.org/' ],
367 );
368----------------------------------------------------------------------------
6d3902b0
DN
369
370$logo_url::
371$logo_label::
372 URI and label (title) for the Git logo link (or your site logo,
373 if you chose to use different logo image). By default, these both
e52a53df
JK
374 refer to Git homepage, https://git-scm.com[]; in the past, they pointed
375 to Git documentation at https://www.kernel.org[].
6d3902b0
DN
376
377
378Changing gitweb's look
379~~~~~~~~~~~~~~~~~~~~~~
380You can adjust how pages generated by gitweb look using the variables described
381below. You can change the site name, add common headers and footers for all
382pages, and add a description of this gitweb installation on its main page
383(which is the projects list page), etc.
384
385$site_name::
386 Name of your site or organization, to appear in page titles. Set it
387 to something descriptive for clearer bookmarks etc. If this variable
388 is not set or is, then gitweb uses the value of the `SERVER_NAME`
47d81b5c 389 `CGI` environment variable, setting site name to "$SERVER_NAME Git",
6d3902b0
DN
390 or "Untitled Git" if this variable is not set (e.g. if running gitweb
391 as standalone script).
392+
393Can be set using the `GITWEB_SITENAME` at build time. Unset by default.
394
c1355b7f
LH
395$site_html_head_string::
396 HTML snippet to be included in the <head> section of each page.
397 Can be set using `GITWEB_SITE_HTML_HEAD_STRING` at build time.
398 No default value.
399
6d3902b0
DN
400$site_header::
401 Name of a file with HTML to be included at the top of each page.
402 Relative to the directory containing the 'gitweb.cgi' script.
403 Can be set using `GITWEB_SITE_HEADER` at build time. No default
404 value.
405
406$site_footer::
407 Name of a file with HTML to be included at the bottom of each page.
408 Relative to the directory containing the 'gitweb.cgi' script.
409 Can be set using `GITWEB_SITE_FOOTER` at build time. No default
410 value.
411
412$home_text::
413 Name of a HTML file which, if it exists, is included on the
414 gitweb projects overview page ("projects_list" view). Relative to
415 the directory containing the gitweb.cgi script. Default value
416 can be adjusted during build time using `GITWEB_HOMETEXT` variable.
417 By default set to 'indextext.html'.
418
419$projects_list_description_width::
420 The width (in characters) of the "Description" column of the projects list.
421 Longer descriptions will be truncated (trying to cut at word boundary);
422 the full description is available in the 'title' attribute (usually shown on
423 mouseover). The default is 25, which might be too small if you
424 use long project descriptions.
425
426$default_projects_order::
427 Default value of ordering of projects on projects list page, which
428 means the ordering used if you don't explicitly sort projects list
429 (if there is no "o" CGI query parameter in the URL). Valid values
430 are "none" (unsorted), "project" (projects are by project name,
431 i.e. path to repository relative to `$projectroot`), "descr"
432 (project description), "owner", and "age" (by date of most current
433 commit).
434+
435Default value is "project". Unknown value means unsorted.
436
437
438Changing gitweb's behavior
439~~~~~~~~~~~~~~~~~~~~~~~~~~
440These configuration variables control _internal_ gitweb behavior.
441
442$default_blob_plain_mimetype::
443 Default mimetype for the blob_plain (raw) view, if mimetype checking
444 doesn't result in some other type; by default "text/plain".
445 Gitweb guesses mimetype of a file to display based on extension
446 of its filename, using `$mimetypes_file` (if set and file exists)
68ed71b5 447 and `/etc/mime.types` files (see *mime.types*(5) manpage; only
6d3902b0
DN
448 filename extension rules are supported by gitweb).
449
450$default_text_plain_charset::
451 Default charset for text files. If this is not set, the web server
452 configuration will be used. Unset by default.
453
454$fallback_encoding::
455 Gitweb assumes this charset when a line contains non-UTF-8 characters.
456 The fallback decoding is used without error checking, so it can be even
457 "utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm)
458 man page for a list. The default is "latin1", aka. "iso-8859-1".
459
460@diff_opts::
461 Rename detection options for git-diff and git-diff-tree. The default is
462 (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies,
463 or set it to () i.e. empty list if you don't want to have renames
464 detection.
465+
466*Note* that rename and especially copy detection can be quite
2de9b711 467CPU-intensive. Note also that non Git tools can have problems with
6d3902b0
DN
468patches generated with options mentioned above, especially when they
469involve file copies (\'-C') or criss-cross renames (\'-B').
470
471
472Some optional features and policies
473~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
474Most of features are configured via `%feature` hash; however some of extra
475gitweb features can be turned on and configured using variables described
476below. This list beside configuration variables that control how gitweb
477looks does contain variables configuring administrative side of gitweb
478(e.g. cross-site scripting prevention; admittedly this as side effect
479affects how "summary" pages look like, or load limiting).
480
481@git_base_url_list::
2de9b711 482 List of Git base URLs. These URLs are used to generate URLs
6d3902b0
DN
483 describing from where to fetch a project, which are shown on
484 project summary page. The full fetch URL is "`$git_base_url/$project`",
485 for each element of this list. You can set up multiple base URLs
486 (for example one for `git://` protocol, and one for `http://`
487 protocol).
488+
68ed71b5 489Note that per repository configuration can be set in `$GIT_DIR/cloneurl`
6d3902b0
DN
490file, or as values of multi-value `gitweb.url` configuration variable in
491project config. Per-repository configuration takes precedence over value
492composed from `@git_base_url_list` elements and project name.
493+
494You can setup one single value (single entry/item in this list) at build
d7bfb9ee 495time by setting the `GITWEB_BASE_URL` build-time configuration variable.
6d3902b0
DN
496By default it is set to (), i.e. an empty list. This means that gitweb
497would not try to create project URL (to fetch) from project name.
498
499$projects_list_group_categories::
270f0a8c 500 Whether to enable the grouping of projects by category on the project
6d3902b0
DN
501 list page. The category of a project is determined by the
502 `$GIT_DIR/category` file or the `gitweb.category` variable in each
503 repository's configuration. Disabled by default (set to 0).
504
505$project_list_default_category::
506 Default category for projects for which none is specified. If this is
507 set to the empty string, such projects will remain uncategorized and
508 listed at the top, above categorized projects. Used only if project
509 categories are enabled, which means if `$projects_list_group_categories`
510 is true. By default set to "" (empty string).
511
512$prevent_xss::
513 If true, some gitweb features are disabled to prevent content in
514 repositories from launching cross-site scripting (XSS) attacks. Set this
515 to true if you don't trust the content of your repositories.
516 False by default (set to 0).
517
518$maxload::
519 Used to set the maximum load that we will still respond to gitweb queries.
520 If the server load exceeds this value then gitweb will return
521 "503 Service Unavailable" error. The server load is taken to be 0
522 if gitweb cannot determine its value. Currently it works only on Linux,
68ed71b5 523 where it uses `/proc/loadavg`; the load there is the number of active
6d3902b0
DN
524 tasks on the system -- processes that are actually running -- averaged
525 over the last minute.
526+
527Set `$maxload` to undefined value (`undef`) to turn this feature off.
528The default value is 300.
529
5710be46
KK
530$omit_age_column::
531 If true, omit the column with date of the most current commit on the
532 projects list page. It can save a bit of I/O and a fork per repository.
533
0ebe7827
KK
534$omit_owner::
535 If true prevents displaying information about repository owner.
536
6d3902b0
DN
537$per_request_config::
538 If this is set to code reference, it will be run once for each request.
8d75a1d1 539 You can set parts of configuration that change per session this way.
6d3902b0
DN
540 For example, one might use the following code in a gitweb configuration
541 file
542+
543--------------------------------------------------------------------------------
544our $per_request_config = sub {
545 $ENV{GL_USER} = $cgi->remote_user || "gitweb";
546};
547--------------------------------------------------------------------------------
548+
549If `$per_request_config` is not a code reference, it is interpreted as boolean
550value. If it is true gitweb will process config files once per request,
551and if it is false gitweb will process config files only once, each time it
552is executed. True by default (set to 1).
553+
554*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default
555values before every request, so if you want to change them, be sure to set
556this variable to true or a code reference effecting the desired changes.
557+
558This variable matters only when using persistent web environments that
559serve multiple requests using single gitweb instance, like mod_perl,
560FastCGI or Plackup.
561
562
563Other variables
564~~~~~~~~~~~~~~~
565Usually you should not need to change (adjust) any of configuration
566variables described below; they should be automatically set by gitweb to
567correct value.
568
569
570$version::
571 Gitweb version, set automatically when creating gitweb.cgi from
572 gitweb.perl. You might want to modify it if you are running modified
573 gitweb, for example
574+
575---------------------------------------------------
576our $version .= " with caching";
577---------------------------------------------------
578+
579if you run modified version of gitweb with caching support. This variable
580is purely informational, used e.g. in the "generator" meta header in HTML
581header.
582
583$my_url::
584$my_uri::
585 Full URL and absolute URL of the gitweb script;
586 in earlier versions of gitweb you might have need to set those
587 variables, but now there should be no need to do it. See
588 `$per_request_config` if you need to set them still.
589
590$base_url::
591 Base URL for relative URLs in pages generated by gitweb,
592 (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),
593 needed and used '<base href="$base_url">' only for URLs with nonempty
594 PATH_INFO. Usually gitweb sets its value correctly,
595 and there is no need to set this variable, e.g. to $my_uri or "/".
596 See `$per_request_config` if you need to override it anyway.
597
598
599CONFIGURING GITWEB FEATURES
600---------------------------
601Many gitweb features can be enabled (or disabled) and configured using the
602`%feature` hash. Names of gitweb features are keys of this hash.
603
604Each `%feature` hash element is a hash reference and has the following
605structure:
606----------------------------------------------------------------------
607"<feature_name>" => {
608 "sub" => <feature-sub (subroutine)>,
609 "override" => <allow-override (boolean)>,
610 "default" => [ <options>... ]
611},
612----------------------------------------------------------------------
613Some features cannot be overridden per project. For those
614features the structure of appropriate `%feature` hash element has a simpler
615form:
616----------------------------------------------------------------------
617"<feature_name>" => {
618 "override" => 0,
619 "default" => [ <options>... ]
620},
621----------------------------------------------------------------------
622As one can see it lacks the \'sub' element.
623
624The meaning of each part of feature configuration is described
625below:
626
627default::
628 List (array reference) of feature parameters (if there are any),
629 used also to toggle (enable or disable) given feature.
630+
631Note that it is currently *always* an array reference, even if
632feature doesn't accept any configuration parameters, and \'default'
633is used only to turn it on or off. In such case you turn feature on
634by setting this element to `[1]`, and torn it off by setting it to
635`[0]`. See also the passage about the "blame" feature in the "Examples"
636section.
637+
638To disable features that accept parameters (are configurable), you
639need to set this element to empty list i.e. `[]`.
640
641override::
642 If this field has a true value then the given feature is
5fe8f49b 643 overridable, which means that it can be configured
6d3902b0
DN
644 (or enabled/disabled) on a per-repository basis.
645+
646Usually given "<feature>" is configurable via the `gitweb.<feature>`
2de9b711 647config variable in the per-repository Git configuration file.
6d3902b0 648+
5fe8f49b 649*Note* that no feature is overridable by default.
6d3902b0
DN
650
651sub::
652 Internal detail of implementation. What is important is that
653 if this field is not present then per-repository override for
654 given feature is not supported.
655+
656You wouldn't need to ever change it in gitweb config file.
657
658
659Features in `%feature`
660~~~~~~~~~~~~~~~~~~~~~~
661The gitweb features that are configurable via `%feature` hash are listed
662below. This should be a complete list, but ultimately the authoritative
663and complete list is in gitweb.cgi source code, with features described
664in the comments.
665
666blame::
667 Enable the "blame" and "blame_incremental" blob views, showing for
668 each line the last commit that modified it; see linkgit:git-blame[1].
669 This can be very CPU-intensive and is therefore disabled by default.
670+
671This feature can be configured on a per-repository basis via
672repository's `gitweb.blame` configuration variable (boolean).
673
674snapshot::
675 Enable and configure the "snapshot" action, which allows user to
676 download a compressed archive of any tree or commit, as produced
677 by linkgit:git-archive[1] and possibly additionally compressed.
678 This can potentially generate high traffic if you have large project.
679+
680The value of \'default' is a list of names of snapshot formats,
681defined in `%known_snapshot_formats` hash, that you wish to offer.
682Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
683compressed tar archive) and "zip"; please consult gitweb sources for
684a definitive list. By default only "tgz" is offered.
685+
686This feature can be configured on a per-repository basis via
112ea426 687repository's `gitweb.snapshot` configuration variable, which contains
6d3902b0
DN
688a comma separated list of formats or "none" to disable snapshots.
689Unknown values are ignored.
690
691grep::
692 Enable grep search, which lists the files in currently selected
693 tree (directory) containing the given string; see linkgit:git-grep[1].
694 This can be potentially CPU-intensive, of course. Enabled by default.
695+
696This feature can be configured on a per-repository basis via
697repository's `gitweb.grep` configuration variable (boolean).
698
699pickaxe::
700 Enable the so called pickaxe search, which will list the commits
701 that introduced or removed a given string in a file. This can be
702 practical and quite faster alternative to "blame" action, but it is
703 still potentially CPU-intensive. Enabled by default.
704+
705The pickaxe search is described in linkgit:git-log[1] (the
706description of `-S<string>` option, which refers to pickaxe entry in
707linkgit:gitdiffcore[7] for more details).
708+
709This feature can be configured on a per-repository basis by setting
710repository's `gitweb.pickaxe` configuration variable (boolean).
711
712show-sizes::
713 Enable showing size of blobs (ordinary files) in a "tree" view, in a
714 separate column, similar to what `ls -l` does; see description of
715 `-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of
716 I/O. Enabled by default.
717+
718This feature can be configured on a per-repository basis via
da0005b8 719repository's `gitweb.showSizes` configuration variable (boolean).
6d3902b0
DN
720
721patches::
722 Enable and configure "patches" view, which displays list of commits in email
723 (plain text) output format; see also linkgit:git-format-patch[1].
724 The value is the maximum number of patches in a patchset generated
725 in "patches" view. Set the 'default' field to a list containing single
726 item of or to an empty list to disable patch view, or to a list
727 containing a single negative number to remove any limit.
728 Default value is 16.
729+
730This feature can be configured on a per-repository basis via
731repository's `gitweb.patches` configuration variable (integer).
732
733avatar::
734 Avatar support. When this feature is enabled, views such as
735 "shortlog" or "commit" will display an avatar associated with
736 the email of each committer and author.
737+
738Currently available providers are *"gravatar"* and *"picon"*.
739Only one provider at a time can be selected ('default' is one element list).
740If an unknown provider is specified, the feature is disabled.
741*Note* that some providers might require extra Perl packages to be
68ed71b5 742installed; see `gitweb/INSTALL` for more details.
6d3902b0
DN
743+
744This feature can be configured on a per-repository basis via
745repository's `gitweb.avatar` configuration variable.
746+
747See also `%avatar_size` with pixel sizes for icons and avatars
748("default" is used for one-line like "log" and "shortlog", "double"
749is used for two-line like "commit", "commitdiff" or "tag"). If the
750default font sizes or lineheights are changed (e.g. via adding extra
751CSS stylesheet in `@stylesheets`), it may be appropriate to change
752these values.
753
754highlight::
755 Server-side syntax highlight support in "blob" view. It requires
756 `$highlight_bin` program to be available (see the description of
757 this variable in the "Configuration variables" section above),
758 and therefore is disabled by default.
759+
760This feature can be configured on a per-repository basis via
761repository's `gitweb.highlight` configuration variable (boolean).
762
763remote_heads::
764 Enable displaying remote heads (remote-tracking branches) in the "heads"
765 list. In most cases the list of remote-tracking branches is an
766 unnecessary internal private detail, and this feature is therefore
767 disabled by default. linkgit:git-instaweb[1], which is usually used
768 to browse local repositories, enables and uses this feature.
769+
770This feature can be configured on a per-repository basis via
771repository's `gitweb.remote_heads` configuration variable (boolean).
772
773
774The remaining features cannot be overridden on a per project basis.
775
776search::
777 Enable text search, which will list the commits which match author,
778 committer or commit text to a given string; see the description of
779 `--author`, `--committer` and `--grep` options in linkgit:git-log[1]
780 manpage. Enabled by default.
781+
782Project specific override is not supported.
783
784forks::
785 If this feature is enabled, gitweb considers projects in
786 subdirectories of project root (basename) to be forks of existing
6cf378f0
JK
787 projects. For each project +$projname.git+, projects in the
788 +$projname/+ directory and its subdirectories will not be
789 shown in the main projects list. Instead, a \'\+' mark is shown
790 next to +$projname+, which links to a "forks" view that lists all
791 the forks (all projects in +$projname/+ subdirectory). Additionally
6d3902b0
DN
792 a "forks" view for a project is linked from project summary page.
793+
6cf378f0 794If the project list is taken from a file (+$projects_list+ points to a
6d3902b0
DN
795file), forks are only recognized if they are listed after the main project
796in that file.
797+
798Project specific override is not supported.
799
800actions::
801 Insert custom links to the action bar of all project pages. This
802 allows you to link to third-party scripts integrating into gitweb.
803+
804The "default" value consists of a list of triplets in the form
805`("<label>", "<link>", "<position>")` where "position" is the label
806after which to insert the link, "link" is a format string where `%n`
807expands to the project name, `%f` to the project path within the
808filesystem (i.e. "$projectroot/$project"), `%h` to the current hash
809(\'h' gitweb parameter) and `%b` to the current hash base
810(\'hb' gitweb parameter); `%%` expands to \'%'.
811+
812For example, at the time this page was written, the http://repo.or.cz[]
2de9b711 813Git hosting site set it to the following to enable graphical log
6d3902b0
DN
814(using the third party tool *git-browser*):
815+
816----------------------------------------------------------------------
817$feature{'actions'}{'default'} =
818 [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
819----------------------------------------------------------------------
820+
821This adds a link titled "graphiclog" after the "summary" link, leading to
822`git-browser` script, passing `r=<project>` as a query parameter.
823+
824Project specific override is not supported.
825
826timed::
2de9b711 827 Enable displaying how much time and how many Git commands it took to
6d3902b0
DN
828 generate and display each page in the page footer (at the bottom of
829 page). For example the footer might contain: "This page took 6.53325
2de9b711 830 seconds and 13 Git commands to generate." Disabled by default.
6d3902b0
DN
831+
832Project specific override is not supported.
833
834javascript-timezone::
0ffa154b 835 Enable and configure the ability to change a common time zone for dates
6d3902b0
DN
836 in gitweb output via JavaScript. Dates in gitweb output include
837 authordate and committerdate in "commit", "commitdiff" and "log"
838 views, and taggerdate in "tag" view. Enabled by default.
839+
0ffa154b
JSJ
840The value is a list of three values: a default time zone (for if the client
841hasn't selected some other time zone and saved it in a cookie), a name of cookie
842where to store selected time zone, and a CSS class used to mark up
6d3902b0
DN
843dates for manipulation. If you want to turn this feature off, set "default"
844to empty list: `[]`.
845+
0ffa154b 846Typical gitweb config files will only change starting (default) time zone,
6d3902b0
DN
847and leave other elements at their default values:
848+
849---------------------------------------------------------------------------
850$feature{'javascript-timezone'}{'default'}[0] = "utc";
851---------------------------------------------------------------------------
852+
853The example configuration presented here is guaranteed to be backwards
854and forward compatible.
855+
0ffa154b 856Time zone values can be "local" (for local time zone that browser uses), "utc"
6d3902b0 857(what gitweb uses when JavaScript or this feature is disabled), or numerical
0ffa154b 858time zones in the form of "+/-HHMM", such as "+0200".
6d3902b0
DN
859+
860Project specific override is not supported.
861
8d646a9b
KN
862extra-branch-refs::
863 List of additional directories under "refs" which are going to
864 be used as branch refs. For example if you have a gerrit setup
865 where all branches under refs/heads/ are official,
866 push-after-review ones and branches under refs/sandbox/,
867 refs/wip and refs/other are user ones where permissions are
868 much wider, then you might want to set this variable as
869 follows:
870+
871--------------------------------------------------------------------------------
872$feature{'extra-branch-refs'}{'default'} =
873 ['sandbox', 'wip', 'other'];
874--------------------------------------------------------------------------------
875+
876This feature can be configured on per-repository basis after setting
877$feature{'extra-branch-refs'}{'override'} to true, via repository's
878`gitweb.extraBranchRefs` configuration variable, which contains a
879space separated list of refs. An example:
880+
881--------------------------------------------------------------------------------
882[gitweb]
883 extraBranchRefs = sandbox wip other
884--------------------------------------------------------------------------------
885+
886The gitweb.extraBranchRefs is actually a multi-valued configuration
887variable, so following example is also correct and the result is the
888same as of the snippet above:
889+
890--------------------------------------------------------------------------------
891[gitweb]
892 extraBranchRefs = sandbox
893 extraBranchRefs = wip other
894--------------------------------------------------------------------------------
895+
896It is an error to specify a ref that does not pass "git check-ref-format"
897scrutiny. Duplicated values are filtered.
898
6d3902b0
DN
899
900EXAMPLES
901--------
902
903To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
904"zip" snapshots), while allowing individual projects to turn them off, put
905the following in your GITWEB_CONFIG file:
906
9aab3fcf
AH
907--------------------------------------------------------------------------------
908$feature{'blame'}{'default'} = [1];
909$feature{'blame'}{'override'} = 1;
6d3902b0 910
9aab3fcf
AH
911$feature{'pickaxe'}{'default'} = [1];
912$feature{'pickaxe'}{'override'} = 1;
6d3902b0 913
9aab3fcf
AH
914$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
915$feature{'snapshot'}{'override'} = 1;
916--------------------------------------------------------------------------------
6d3902b0
DN
917
918If you allow overriding for the snapshot feature, you can specify which
06ab60c0 919snapshot formats are globally disabled. You can also add any command-line
6d3902b0
DN
920options you want (such as setting the compression level). For instance, you
921can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
922adding the following lines to your gitweb configuration file:
923
924 $known_snapshot_formats{'zip'}{'disabled'} = 1;
925 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
926
1a39b727
JN
927BUGS
928----
929Debugging would be easier if the fallback configuration file
930(`/etc/gitweb.conf`) and environment variable to override its location
931('GITWEB_CONFIG_SYSTEM') had names reflecting their "fallback" role.
932The current names are kept to avoid breaking working setups.
933
6d3902b0
DN
934ENVIRONMENT
935-----------
936The location of per-instance and system-wide configuration files can be
937overridden using the following environment variables:
938
939GITWEB_CONFIG::
940 Sets location of per-instance configuration file.
941GITWEB_CONFIG_SYSTEM::
942 Sets location of fallback system-wide configuration file.
943 This file is read only if per-instance one does not exist.
944GITWEB_CONFIG_COMMON::
945 Sets location of common system-wide configuration file.
946
947
948FILES
949-----
950gitweb_config.perl::
951 This is default name of per-instance configuration file. The
952 format of this file is described above.
953/etc/gitweb.conf::
954 This is default name of fallback system-wide configuration
955 file. This file is used only if per-instance configuration
956 variable is not found.
957/etc/gitweb-common.conf::
958 This is default name of common system-wide configuration
959 file.
960
961
962SEE ALSO
963--------
964linkgit:gitweb[1], linkgit:git-instaweb[1]
965
966'gitweb/README', 'gitweb/INSTALL'
967
968GIT
969---
970Part of the linkgit:git[1] suite