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