logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

gitweb.conf.5 (44247B)


  1. '\" t
  2. .\" Title: gitweb.conf
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GITWEB\&.CONF" "5" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. gitweb.conf \- Gitweb (Git web interface) configuration file
  32. .SH "SYNOPSIS"
  33. .sp
  34. /etc/gitweb\&.conf, /etc/gitweb\-common\&.conf, $GITWEBDIR/gitweb_config\&.perl
  35. .SH "DESCRIPTION"
  36. .sp
  37. 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 "\fBour\fR \fB$variable\fR \fB=\fR \fBvalue\fR"; text from a "#" character until the end of a line is ignored\&. See \fBperlsyn\fR(1) for details\&.
  38. .sp
  39. An example:
  40. .sp
  41. .if n \{\
  42. .RS 4
  43. .\}
  44. .nf
  45. # gitweb configuration file for http://git\&.example\&.org
  46. #
  47. our $projectroot = "/srv/git"; # FHS recommendation
  48. our $site_name = \*(AqExample\&.org >> Repos\*(Aq;
  49. .fi
  50. .if n \{\
  51. .RE
  52. .\}
  53. .sp
  54. The configuration file is used to override the default settings that were built into gitweb at the time the \fIgitweb\&.cgi\fR script was generated\&.
  55. .sp
  56. 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 \fIgitweb_config\&.perl\fR \(em allowing one to have multiple gitweb instances with different configurations by the use of symlinks\&.
  57. .sp
  58. Note that some configuration can be controlled on per\-repository rather than gitweb\-wide basis: see "Per\-repository gitweb configuration" subsection on \fBgitweb\fR(1) manpage\&.
  59. .SH "DISCUSSION"
  60. .sp
  61. Gitweb reads configuration data from the following sources in the following order:
  62. .sp
  63. .RS 4
  64. .ie n \{\
  65. \h'-04'\(bu\h'+03'\c
  66. .\}
  67. .el \{\
  68. .sp -1
  69. .IP \(bu 2.3
  70. .\}
  71. built\-in values (some set during build stage),
  72. .RE
  73. .sp
  74. .RS 4
  75. .ie n \{\
  76. \h'-04'\(bu\h'+03'\c
  77. .\}
  78. .el \{\
  79. .sp -1
  80. .IP \(bu 2.3
  81. .\}
  82. common system\-wide configuration file (defaults to
  83. \fB/etc/gitweb\-common\&.conf\fR),
  84. .RE
  85. .sp
  86. .RS 4
  87. .ie n \{\
  88. \h'-04'\(bu\h'+03'\c
  89. .\}
  90. .el \{\
  91. .sp -1
  92. .IP \(bu 2.3
  93. .\}
  94. either per\-instance configuration file (defaults to
  95. \fIgitweb_config\&.perl\fR
  96. in the same directory as the installed gitweb), or if it does not exist then fallback system\-wide configuration file (defaults to
  97. \fB/etc/gitweb\&.conf\fR)\&.
  98. .RE
  99. .sp
  100. Values obtained in later configuration files override values obtained earlier in the above sequence\&.
  101. .sp
  102. 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 \fBGITWEB_CONFIG_COMMON\fR, \fBGITWEB_CONFIG_SYSTEM\fR and \fBGITWEB_CONFIG\fR\&.
  103. .sp
  104. You can also override locations of gitweb configuration files during runtime by setting the following environment variables: \fBGITWEB_CONFIG_COMMON\fR, \fBGITWEB_CONFIG_SYSTEM\fR and \fBGITWEB_CONFIG\fR to a non\-empty value\&.
  105. .sp
  106. 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 \fBour\fR qualifier (as in "\fBour\fR \fB$variable\fR \fB=\fR \fI<value>\fR;") to avoid syntax errors if a new version of gitweb no longer uses a variable and therefore stops declaring it\&.
  107. .sp
  108. 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 \fB/etc/gitweb\-gitolite\&.conf\fR\&. To include it, put
  109. .sp
  110. .if n \{\
  111. .RS 4
  112. .\}
  113. .nf
  114. read_config_file("/etc/gitweb\-gitolite\&.conf");
  115. .fi
  116. .if n \{\
  117. .RE
  118. .\}
  119. .sp
  120. 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\&.
  121. .sp
  122. 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)\&.
  123. .SH "CONFIGURATION VARIABLES"
  124. .sp
  125. Some configuration variables have their default values (embedded in the CGI script) set during building gitweb \(em if that is the case, this fact is put in their description\&. See gitweb\(cqs \fIINSTALL\fR file for instructions on building and installing gitweb\&.
  126. .SS "Location of repositories"
  127. .sp
  128. The configuration variables described below control how gitweb finds Git repositories, and how repositories are displayed and accessed\&.
  129. .sp
  130. See also "Repositories" and later subsections in \fBgitweb\fR(1) manpage\&.
  131. .PP
  132. $projectroot
  133. .RS 4
  134. Absolute filesystem path which will be prepended to project path; the path to repository is
  135. \fB$projectroot/$project\fR\&. Set to
  136. \fB$GITWEB_PROJECTROOT\fR
  137. during installation\&. This variable has to be set correctly for gitweb to find repositories\&.
  138. .sp
  139. For example, if
  140. \fB$projectroot\fR
  141. is set to "/srv/git" by putting the following in gitweb config file:
  142. .sp
  143. .if n \{\
  144. .RS 4
  145. .\}
  146. .nf
  147. our $projectroot = "/srv/git";
  148. .fi
  149. .if n \{\
  150. .RE
  151. .\}
  152. .sp
  153. then
  154. .sp
  155. .if n \{\
  156. .RS 4
  157. .\}
  158. .nf
  159. http://git\&.example\&.com/gitweb\&.cgi?p=foo/bar\&.git
  160. .fi
  161. .if n \{\
  162. .RE
  163. .\}
  164. .sp
  165. and its path_info based equivalent
  166. .sp
  167. .if n \{\
  168. .RS 4
  169. .\}
  170. .nf
  171. http://git\&.example\&.com/gitweb\&.cgi/foo/bar\&.git
  172. .fi
  173. .if n \{\
  174. .RE
  175. .\}
  176. .sp
  177. will map to the path
  178. \fB/srv/git/foo/bar\&.git\fR
  179. on the filesystem\&.
  180. .RE
  181. .PP
  182. $projects_list
  183. .RS 4
  184. Name of a plain text file listing projects, or a name of directory to be scanned for projects\&.
  185. .sp
  186. Project list files should list one project per line, with each line having the following format
  187. .sp
  188. .if n \{\
  189. .RS 4
  190. .\}
  191. .nf
  192. <URI\-encoded filesystem path to repository> SP <URI\-encoded repository owner>
  193. .fi
  194. .if n \{\
  195. .RE
  196. .\}
  197. .sp
  198. The default value of this variable is determined by the
  199. \fBGITWEB_LIST\fR
  200. makefile variable at installation time\&. If this variable is empty, gitweb will fall back to scanning the
  201. \fB$projectroot\fR
  202. directory for repositories\&.
  203. .RE
  204. .PP
  205. $project_maxdepth
  206. .RS 4
  207. If
  208. \fB$projects_list\fR
  209. variable is unset, gitweb will recursively scan filesystem for Git repositories\&. The
  210. \fB$project_maxdepth\fR
  211. is used to limit traversing depth, relative to
  212. \fB$projectroot\fR
  213. (starting point); it means that directories which are further from
  214. \fB$projectroot\fR
  215. than
  216. \fB$project_maxdepth\fR
  217. will be skipped\&.
  218. .sp
  219. 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\&.
  220. .sp
  221. The default value of this variable is determined by the build\-time configuration variable
  222. \fBGITWEB_PROJECT_MAXDEPTH\fR, which defaults to 2007\&.
  223. .RE
  224. .PP
  225. $export_ok
  226. .RS 4
  227. 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
  228. \fBGITWEB_EXPORT_OK\fR\&. This path is relative to
  229. \fBGIT_DIR\fR\&. git\-daemon[1] uses
  230. \fIgit\-daemon\-export\-ok\fR, unless started with
  231. \fB\-\-export\-all\fR\&. By default this variable is not set, which means that this feature is turned off\&.
  232. .RE
  233. .PP
  234. $export_auth_hook
  235. .RS 4
  236. 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:
  237. .sp
  238. .if n \{\
  239. .RS 4
  240. .\}
  241. .nf
  242. our $export_auth_hook = sub { return \-e "$_[0]/git\-daemon\-export\-ok"; };
  243. .fi
  244. .if n \{\
  245. .RE
  246. .\}
  247. .sp
  248. though the above might be done by using
  249. \fB$export_ok\fR
  250. instead
  251. .sp
  252. .if n \{\
  253. .RS 4
  254. .\}
  255. .nf
  256. our $export_ok = "git\-daemon\-export\-ok";
  257. .fi
  258. .if n \{\
  259. .RE
  260. .\}
  261. .sp
  262. If not set (default), it means that this feature is disabled\&.
  263. .sp
  264. See also more involved example in "Controlling access to Git repositories" subsection on
  265. \fBgitweb\fR(1)
  266. manpage\&.
  267. .RE
  268. .PP
  269. $strict_export
  270. .RS 4
  271. Only allow viewing of repositories also shown on the overview page\&. This for example makes
  272. \fB$export_ok\fR
  273. file decide if repository is available and not only if it is shown\&. If
  274. \fB$projects_list\fR
  275. points to file with list of project, only those repositories listed would be available for gitweb\&. Can be set during building gitweb via
  276. \fBGITWEB_STRICT_EXPORT\fR\&. 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)\&.
  277. .RE
  278. .SS "Finding files"
  279. .sp
  280. The following configuration variables tell gitweb where to find files\&. The values of these variables are paths on the filesystem\&.
  281. .PP
  282. $GIT
  283. .RS 4
  284. Core git executable to use\&. By default set to
  285. \fB$GIT_BINDIR/git\fR, which in turn is by default set to
  286. \fB$\fR(\fBbindir\fR)\fB/git\fR\&. 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\&.
  287. .RE
  288. .PP
  289. $mimetypes_file
  290. .RS 4
  291. File to use for (filename extension based) guessing of MIME types before trying
  292. \fB/etc/mime\&.types\fR\&.
  293. \fBNOTE\fR
  294. that this path, if relative, is taken as relative to the current Git repository, not to CGI script\&. If unset, only
  295. \fB/etc/mime\&.types\fR
  296. is used (if present on filesystem)\&. If no mimetypes file is found, mimetype guessing based on extension of file is disabled\&. Unset by default\&.
  297. .RE
  298. .PP
  299. $highlight_bin
  300. .RS 4
  301. Path to the highlight executable to use (it must be the one from
  302. \m[blue]\fBhttp://andre\-simon\&.de/zip/download\&.php\fR\m[]
  303. due to assumptions about parameters and output)\&. By default set to
  304. \fIhighlight\fR; set it to full path to highlight executable if it is not installed on your web server\(cqs PATH\&. Note that
  305. \fIhighlight\fR
  306. feature must be set for gitweb to actually use syntax highlighting\&.
  307. .sp
  308. \fBNOTE\fR: 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
  309. \fB\-\-syntax\fR
  310. \fI<syntax>\fR
  311. to "highlight"\&. The last priority is the "highlight" configuration of
  312. \fBShebang\fR
  313. 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\&.
  314. .sp
  315. 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:
  316. .sp
  317. .if n \{\
  318. .RS 4
  319. .\}
  320. .nf
  321. our %highlight_ext;
  322. $highlight_ext{\*(Aqphtml\*(Aq} = \*(Aqphp\*(Aq;
  323. .fi
  324. .if n \{\
  325. .RE
  326. .\}
  327. .RE
  328. .SS "Links and their targets"
  329. .sp
  330. 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 \fB@stylesheets\fR variable\&.
  331. .PP
  332. @stylesheets
  333. .RS 4
  334. 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
  335. \fBsite\fR
  336. stylesheet by putting
  337. .sp
  338. .if n \{\
  339. .RS 4
  340. .\}
  341. .nf
  342. push @stylesheets, "gitweb\-site\&.css";
  343. .fi
  344. .if n \{\
  345. .RE
  346. .\}
  347. .sp
  348. in the gitweb config file\&. Those values that are relative paths are relative to base URI of gitweb\&.
  349. .sp
  350. This list should contain the URI of gitweb\(cqs standard stylesheet\&. The default URI of gitweb stylesheet can be set at build time using the
  351. \fBGITWEB_CSS\fR
  352. makefile variable\&. Its default value is
  353. \fBstatic/gitweb\&.css\fR
  354. (or
  355. \fBstatic/gitweb\&.min\&.css\fR
  356. if the
  357. \fBCSSMIN\fR
  358. variable is defined, i\&.e\&. if CSS minifier is used during build)\&.
  359. .sp
  360. \fBNote\fR: there is also a legacy
  361. \fB$stylesheet\fR
  362. configuration variable, which was used by older gitweb\&. If
  363. \fB$stylesheet\fR
  364. variable is defined, only CSS stylesheet given by this variable is used by gitweb\&.
  365. .RE
  366. .PP
  367. $logo
  368. .RS 4
  369. Points to the location where you put
  370. \fIgit\-logo\&.png\fR
  371. 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
  372. \fBGITWEB_LOGO\fR
  373. variable By default set to
  374. \fBstatic/git\-logo\&.png\fR\&.
  375. .RE
  376. .PP
  377. $favicon
  378. .RS 4
  379. Points to the location where you put
  380. \fIgit\-favicon\&.png\fR
  381. 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\(cqs URL bar and next to the site name in bookmarks\&. Relative to the base URI of gitweb\&. Can be adjusted at build time using
  382. \fBGITWEB_FAVICON\fR
  383. variable\&. By default set to
  384. \fBstatic/git\-favicon\&.png\fR\&.
  385. .RE
  386. .PP
  387. $javascript
  388. .RS 4
  389. Points to the location where you put
  390. \fIgitweb\&.js\fR
  391. 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
  392. \fBGITWEB_JS\fR
  393. build\-time configuration variable\&.
  394. .sp
  395. The default value is either
  396. \fBstatic/gitweb\&.js\fR, or
  397. \fBstatic/gitweb\&.min\&.js\fR
  398. if the
  399. \fBJSMIN\fR
  400. build variable was defined, i\&.e\&. if JavaScript minifier was used at build time\&.
  401. \fBNote\fR
  402. that this single file is generated from multiple individual JavaScript "modules"\&.
  403. .RE
  404. .PP
  405. $home_link
  406. .RS 4
  407. 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
  408. \fB$my_uri\fR
  409. variable, or to "/" if
  410. \fB$my_uri\fR
  411. is undefined or is an empty string)\&.
  412. .RE
  413. .PP
  414. $home_link_str
  415. .RS 4
  416. Label for the "home link" at the top of all pages, leading to
  417. \fB$home_link\fR
  418. (usually the main gitweb page, which contains the projects list)\&. It is used as the first component of gitweb\(cqs "breadcrumb trail":
  419. \fI<home\-link>\fR
  420. \fB/\fR
  421. \fI<project>\fR
  422. \fB/\fR
  423. \fI<action>\fR\&. Can be set at build time using the
  424. \fBGITWEB_HOME_LINK_STR\fR
  425. 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\&.
  426. .RE
  427. .PP
  428. @extra_breadcrumbs
  429. .RS 4
  430. 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
  431. \fB$home_link_str\fR) and element 1 is the target URL (equivalent to
  432. \fB$home_link\fR)\&.
  433. .sp
  434. For example, the following setting produces a breadcrumb trail like "home / dev / projects / \&...\:" where "projects" is the home link\&.
  435. .sp
  436. .if n \{\
  437. .RS 4
  438. .\}
  439. .nf
  440. our @extra_breadcrumbs = (
  441. [ \*(Aqhome\*(Aq => \*(Aqhttps://www\&.example\&.org/\*(Aq ],
  442. [ \*(Aqdev\*(Aq => \*(Aqhttps://dev\&.example\&.org/\*(Aq ],
  443. );
  444. .fi
  445. .if n \{\
  446. .RE
  447. .\}
  448. .RE
  449. .PP
  450. $logo_url, $logo_label
  451. .RS 4
  452. 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,
  453. \m[blue]\fBhttps://git\-scm\&.com\fR\m[]; in the past, they pointed to Git documentation at
  454. \m[blue]\fBhttps://www\&.kernel\&.org\fR\m[]\&.
  455. .RE
  456. .SS "Changing gitweb\(cqs look"
  457. .sp
  458. 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\&.
  459. .PP
  460. $site_name
  461. .RS 4
  462. 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
  463. \fBSERVER_NAME\fR
  464. \fBCGI\fR
  465. 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)\&.
  466. .sp
  467. Can be set using the
  468. \fBGITWEB_SITENAME\fR
  469. at build time\&. Unset by default\&.
  470. .RE
  471. .PP
  472. $site_html_head_string
  473. .RS 4
  474. HTML snippet to be included in the <head> section of each page\&. Can be set using
  475. \fBGITWEB_SITE_HTML_HEAD_STRING\fR
  476. at build time\&. No default value\&.
  477. .RE
  478. .PP
  479. $site_header
  480. .RS 4
  481. Name of a file with HTML to be included at the top of each page\&. Relative to the directory containing the
  482. \fIgitweb\&.cgi\fR
  483. script\&. Can be set using
  484. \fBGITWEB_SITE_HEADER\fR
  485. at build time\&. No default value\&.
  486. .RE
  487. .PP
  488. $site_footer
  489. .RS 4
  490. Name of a file with HTML to be included at the bottom of each page\&. Relative to the directory containing the
  491. \fIgitweb\&.cgi\fR
  492. script\&. Can be set using
  493. \fBGITWEB_SITE_FOOTER\fR
  494. at build time\&. No default value\&.
  495. .RE
  496. .PP
  497. $home_text
  498. .RS 4
  499. 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
  500. \fBGITWEB_HOMETEXT\fR
  501. variable\&. By default set to
  502. \fIindextext\&.html\fR\&.
  503. .RE
  504. .PP
  505. $projects_list_description_width
  506. .RS 4
  507. 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
  508. \fItitle\fR
  509. attribute (usually shown on mouseover)\&. The default is 25, which might be too small if you use long project descriptions\&.
  510. .RE
  511. .PP
  512. $default_projects_order
  513. .RS 4
  514. Default value of ordering of projects on projects list page, which means the ordering used if you don\(cqt 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
  515. \fB$projectroot\fR), "descr" (project description), "owner", and "age" (by date of most current commit)\&.
  516. .sp
  517. Default value is "project"\&. Unknown value means unsorted\&.
  518. .RE
  519. .SS "Changing gitweb\(cqs behavior"
  520. .sp
  521. These configuration variables control \fIinternal\fR gitweb behavior\&.
  522. .PP
  523. $default_blob_plain_mimetype
  524. .RS 4
  525. Default mimetype for the blob_plain (raw) view, if mimetype checking doesn\(cqt result in some other type; by default "text/plain"\&. Gitweb guesses mimetype of a file to display based on extension of its filename, using
  526. \fB$mimetypes_file\fR
  527. (if set and file exists) and
  528. \fB/etc/mime\&.types\fR
  529. files (see
  530. \fBmime\&.types\fR(5) manpage; only filename extension rules are supported by gitweb)\&.
  531. .RE
  532. .PP
  533. $default_text_plain_charset
  534. .RS 4
  535. Default charset for text files\&. If this is not set, the web server configuration will be used\&. Unset by default\&.
  536. .RE
  537. .PP
  538. $fallback_encoding
  539. .RS 4
  540. 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
  541. \fBEncoding::Supported\fR(3pm) man page for a list\&. The default is "latin1", aka\&. "iso\-8859\-1"\&.
  542. .RE
  543. .PP
  544. @diff_opts
  545. .RS 4
  546. Rename detection options for git\-diff and git\-diff\-tree\&. The default is (\*(Aq\-M\*(Aq); set it to (\*(Aq\-C\*(Aq) or (\*(Aq\-C\*(Aq, \*(Aq\-C\*(Aq) to also detect copies, or set it to () i\&.e\&. empty list if you don\(cqt want to have renames detection\&.
  547. .sp
  548. \fBNote\fR
  549. 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 (\*(Aq\-C\*(Aq) or criss\-cross renames (\*(Aq\-B\*(Aq)\&.
  550. .RE
  551. .SS "Some optional features and policies"
  552. .sp
  553. 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)\&.
  554. .PP
  555. @git_base_url_list
  556. .RS 4
  557. 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 "\fB$git_base_url/$project\fR", for each element of this list\&. You can set up multiple base URLs (for example one for
  558. \fBgit://\fR
  559. protocol, and one for
  560. \fBhttp://\fR
  561. protocol)\&.
  562. .sp
  563. Note that per repository configuration can be set in
  564. \fB$GIT_DIR/cloneurl\fR
  565. file, or as values of multi\-value
  566. \fBgitweb\&.url\fR
  567. configuration variable in project config\&. Per\-repository configuration takes precedence over value composed from
  568. \fB@git_base_url_list\fR
  569. elements and project name\&.
  570. .sp
  571. You can setup one single value (single entry/item in this list) at build time by setting the
  572. \fBGITWEB_BASE_URL\fR
  573. 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\&.
  574. .RE
  575. .PP
  576. $projects_list_group_categories
  577. .RS 4
  578. Whether to enable the grouping of projects by category on the project list page\&. The category of a project is determined by the
  579. \fB$GIT_DIR/category\fR
  580. file or the
  581. \fBgitweb\&.category\fR
  582. variable in each repository\(cqs configuration\&. Disabled by default (set to 0)\&.
  583. .RE
  584. .PP
  585. $project_list_default_category
  586. .RS 4
  587. 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
  588. \fB$projects_list_group_categories\fR
  589. is true\&. By default set to "" (empty string)\&.
  590. .RE
  591. .PP
  592. $prevent_xss
  593. .RS 4
  594. 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\(cqt trust the content of your repositories\&. False by default (set to 0)\&.
  595. .RE
  596. .PP
  597. $maxload
  598. .RS 4
  599. 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
  600. \fB/proc/loadavg\fR; the load there is the number of active tasks on the system \(em processes that are actually running \(em averaged over the last minute\&.
  601. .sp
  602. Set
  603. \fB$maxload\fR
  604. to undefined value (\fBundef\fR) to turn this feature off\&. The default value is 300\&.
  605. .RE
  606. .PP
  607. $omit_age_column
  608. .RS 4
  609. 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\&.
  610. .RE
  611. .PP
  612. $omit_owner
  613. .RS 4
  614. If true prevents displaying information about repository owner\&.
  615. .RE
  616. .PP
  617. $per_request_config
  618. .RS 4
  619. 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
  620. .sp
  621. .if n \{\
  622. .RS 4
  623. .\}
  624. .nf
  625. our $per_request_config = sub {
  626. $ENV{GL_USER} = $cgi\->remote_user || "gitweb";
  627. };
  628. .fi
  629. .if n \{\
  630. .RE
  631. .\}
  632. .sp
  633. If
  634. \fB$per_request_config\fR
  635. 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)\&.
  636. .sp
  637. \fBNOTE\fR:
  638. \fB$my_url\fR,
  639. \fB$my_uri\fR, and
  640. \fB$base_url\fR
  641. 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\&.
  642. .sp
  643. This variable matters only when using persistent web environments that serve multiple requests using single gitweb instance, like mod_perl, FastCGI or Plackup\&.
  644. .RE
  645. .SS "Other variables"
  646. .sp
  647. Usually you should not need to change (adjust) any of configuration variables described below; they should be automatically set by gitweb to correct value\&.
  648. .PP
  649. $version
  650. .RS 4
  651. 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
  652. .sp
  653. .if n \{\
  654. .RS 4
  655. .\}
  656. .nf
  657. our $version \&.= " with caching";
  658. .fi
  659. .if n \{\
  660. .RE
  661. .\}
  662. .sp
  663. 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\&.
  664. .RE
  665. .PP
  666. $my_url, $my_uri
  667. .RS 4
  668. 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
  669. \fB$per_request_config\fR
  670. if you need to set them still\&.
  671. .RE
  672. .PP
  673. $base_url
  674. .RS 4
  675. Base URL for relative URLs in pages generated by gitweb, (e\&.g\&.
  676. \fB$logo\fR,
  677. \fB$favicon\fR,
  678. \fB@stylesheets\fR
  679. if they are relative URLs), needed and used
  680. \fI<base href="$base_url">\fR
  681. 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
  682. \fB$per_request_config\fR
  683. if you need to override it anyway\&.
  684. .RE
  685. .SH "CONFIGURING GITWEB FEATURES"
  686. .sp
  687. Many gitweb features can be enabled (or disabled) and configured using the %feature hash\&. Names of gitweb features are keys of this hash\&.
  688. .sp
  689. Each %feature hash element is a hash reference and has the following structure:
  690. .sp
  691. .if n \{\
  692. .RS 4
  693. .\}
  694. .nf
  695. "<feature\-name>" => {
  696. "sub" => <feature\-sub\-(subroutine)>,
  697. "override" => <allow\-override\-(boolean)>,
  698. "default" => [ <options>\&.\&.\&. ]
  699. },
  700. .fi
  701. .if n \{\
  702. .RE
  703. .\}
  704. .sp
  705. Some features cannot be overridden per project\&. For those features the structure of appropriate %feature hash element has a simpler form:
  706. .sp
  707. .if n \{\
  708. .RS 4
  709. .\}
  710. .nf
  711. "<feature\-name>" => {
  712. "override" => 0,
  713. "default" => [ <options>\&.\&.\&. ]
  714. },
  715. .fi
  716. .if n \{\
  717. .RE
  718. .\}
  719. .sp
  720. As one can see it lacks the \*(Aqsub\*(Aq element\&.
  721. .sp
  722. The meaning of each part of feature configuration is described below:
  723. .PP
  724. default
  725. .RS 4
  726. List (array reference) of feature parameters (if there are any), used also to toggle (enable or disable) given feature\&.
  727. .sp
  728. Note that it is currently
  729. \fBalways\fR
  730. an array reference, even if feature doesn\(cqt accept any configuration parameters, and \*(Aqdefault\*(Aq is used only to turn it on or off\&. In such case you turn feature on by setting this element to [\fB1\fR], and torn it off by setting it to [\fB0\fR]\&. See also the passage about the "blame" feature in the "Examples" section\&.
  731. .sp
  732. To disable features that accept parameters (are configurable), you need to set this element to empty list i\&.e\&. []\&.
  733. .RE
  734. .PP
  735. override
  736. .RS 4
  737. 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\&.
  738. .sp
  739. Usually given "<feature>" is configurable via the
  740. \fBgitweb\&.\fR\fI<feature>\fR
  741. config variable in the per\-repository Git configuration file\&.
  742. .sp
  743. \fBNote\fR
  744. that no feature is overridable by default\&.
  745. .RE
  746. .PP
  747. sub
  748. .RS 4
  749. 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\&.
  750. .sp
  751. You wouldn\(cqt need to ever change it in gitweb config file\&.
  752. .RE
  753. .SS "Features in %feature"
  754. .sp
  755. 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\&.
  756. .PP
  757. blame
  758. .RS 4
  759. Enable the "blame" and "blame_incremental" blob views, showing for each line the last commit that modified it; see
  760. \fBgit-blame\fR(1)\&. This can be very CPU\-intensive and is therefore disabled by default\&.
  761. .sp
  762. This feature can be configured on a per\-repository basis via repository\(cqs
  763. \fBgitweb\&.blame\fR
  764. configuration variable (boolean)\&.
  765. .RE
  766. .PP
  767. snapshot
  768. .RS 4
  769. Enable and configure the "snapshot" action, which allows user to download a compressed archive of any tree or commit, as produced by
  770. \fBgit-archive\fR(1)
  771. and possibly additionally compressed\&. This can potentially generate high traffic if you have large project\&.
  772. .sp
  773. The value of \*(Aqdefault\*(Aq 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\&.
  774. .sp
  775. This feature can be configured on a per\-repository basis via repository\(cqs
  776. \fBgitweb\&.snapshot\fR
  777. configuration variable, which contains a comma separated list of formats or "none" to disable snapshots\&. Unknown values are ignored\&.
  778. .RE
  779. .PP
  780. grep
  781. .RS 4
  782. Enable grep search, which lists the files in currently selected tree (directory) containing the given string; see
  783. \fBgit-grep\fR(1)\&. This can be potentially CPU\-intensive, of course\&. Enabled by default\&.
  784. .sp
  785. This feature can be configured on a per\-repository basis via repository\(cqs
  786. \fBgitweb\&.grep\fR
  787. configuration variable (boolean)\&.
  788. .RE
  789. .PP
  790. pickaxe
  791. .RS 4
  792. 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\&.
  793. .sp
  794. The pickaxe search is described in
  795. \fBgit-log\fR(1)
  796. (the description of
  797. \fB\-S\fR\fI<string>\fR
  798. option, which refers to pickaxe entry in
  799. \fBgitdiffcore\fR(7)
  800. for more details)\&.
  801. .sp
  802. This feature can be configured on a per\-repository basis by setting repository\(cqs
  803. \fBgitweb\&.pickaxe\fR
  804. configuration variable (boolean)\&.
  805. .RE
  806. .PP
  807. show\-sizes
  808. .RS 4
  809. Enable showing size of blobs (ordinary files) in a "tree" view, in a separate column, similar to what
  810. \fBls\fR
  811. \fB\-l\fR
  812. does; see description of
  813. \fB\-l\fR
  814. option in
  815. \fBgit-ls-tree\fR(1)
  816. manpage\&. This costs a bit of I/O\&. Enabled by default\&.
  817. .sp
  818. This feature can be configured on a per\-repository basis via repository\(cqs
  819. \fBgitweb\&.showSizes\fR
  820. configuration variable (boolean)\&.
  821. .RE
  822. .PP
  823. patches
  824. .RS 4
  825. Enable and configure "patches" view, which displays list of commits in email (plain text) output format; see also
  826. \fBgit-format-patch\fR(1)\&. The value is the maximum number of patches in a patchset generated in "patches" view\&. Set the
  827. \fIdefault\fR
  828. 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\&.
  829. .sp
  830. This feature can be configured on a per\-repository basis via repository\(cqs
  831. \fBgitweb\&.patches\fR
  832. configuration variable (integer)\&.
  833. .RE
  834. .PP
  835. avatar
  836. .RS 4
  837. 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\&.
  838. .sp
  839. Currently available providers are
  840. \fB"gravatar"\fR
  841. and
  842. \fB"picon"\fR\&. Only one provider at a time can be selected (\fIdefault\fR
  843. is one element list)\&. If an unknown provider is specified, the feature is disabled\&.
  844. \fBNote\fR
  845. that some providers might require extra Perl packages to be installed; see
  846. \fBgitweb/INSTALL\fR
  847. for more details\&.
  848. .sp
  849. This feature can be configured on a per\-repository basis via repository\(cqs
  850. \fBgitweb\&.avatar\fR
  851. configuration variable\&.
  852. .sp
  853. 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
  854. \fB@stylesheets\fR), it may be appropriate to change these values\&.
  855. .RE
  856. .PP
  857. email\-privacy
  858. .RS 4
  859. Redact e\-mail addresses from the generated HTML, etc\&. content\&. This obscures e\-mail addresses retrieved from the author/committer and comment sections of the Git log\&. It is meant to hinder web crawlers that harvest and abuse addresses\&. Such crawlers may not respect robots\&.txt\&. Note that users and user tools also see the addresses as redacted\&. If Gitweb is not the final step in a workflow then subsequent steps may misbehave because of the redacted information they receive\&. Disabled by default\&.
  860. .RE
  861. .PP
  862. highlight
  863. .RS 4
  864. Server\-side syntax highlight support in "blob" view\&. It requires
  865. \fB$highlight_bin\fR
  866. program to be available (see the description of this variable in the "Configuration variables" section above), and therefore is disabled by default\&.
  867. .sp
  868. This feature can be configured on a per\-repository basis via repository\(cqs
  869. \fBgitweb\&.highlight\fR
  870. configuration variable (boolean)\&.
  871. .RE
  872. .PP
  873. remote_heads
  874. .RS 4
  875. 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\&.
  876. \fBgit-instaweb\fR(1), which is usually used to browse local repositories, enables and uses this feature\&.
  877. .sp
  878. This feature can be configured on a per\-repository basis via repository\(cqs
  879. \fBgitweb\&.remote_heads\fR
  880. configuration variable (boolean)\&.
  881. .RE
  882. .sp
  883. The remaining features cannot be overridden on a per project basis\&.
  884. .PP
  885. search
  886. .RS 4
  887. Enable text search, which will list the commits which match author, committer or commit text to a given string; see the description of
  888. \fB\-\-author\fR,
  889. \fB\-\-committer\fR
  890. and
  891. \fB\-\-grep\fR
  892. options in
  893. \fBgit-log\fR(1)
  894. manpage\&. Enabled by default\&.
  895. .sp
  896. Project specific override is not supported\&.
  897. .RE
  898. .PP
  899. forks
  900. .RS 4
  901. If this feature is enabled, gitweb considers projects in subdirectories of project root (basename) to be forks of existing projects\&. For each project
  902. \fB$projname\&.git\fR, projects in the
  903. \fB$projname/\fR
  904. directory and its subdirectories will not be shown in the main projects list\&. Instead, a \*(Aq+\*(Aq mark is shown next to
  905. \fB$projname\fR, which links to a "forks" view that lists all the forks (all projects in
  906. \fB$projname/\fR
  907. subdirectory)\&. Additionally a "forks" view for a project is linked from project summary page\&.
  908. .sp
  909. If the project list is taken from a file (\fB$projects_list\fR
  910. points to a file), forks are only recognized if they are listed after the main project in that file\&.
  911. .sp
  912. Project specific override is not supported\&.
  913. .RE
  914. .PP
  915. actions
  916. .RS 4
  917. Insert custom links to the action bar of all project pages\&. This allows you to link to third\-party scripts integrating into gitweb\&.
  918. .sp
  919. The "default" value consists of a list of triplets in the form ("\fI<label>\fR", "\fI<link>\fR", "\fI<position>\fR") 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 (\*(Aqh\*(Aq gitweb parameter) and %b to the current hash base (\*(Aqhb\*(Aq gitweb parameter); %% expands to \*(Aq%\*(Aq\&.
  920. .sp
  921. For example, at the time this page was written, the
  922. \m[blue]\fBhttps://repo\&.or\&.cz\fR\m[]
  923. Git hosting site set it to the following to enable graphical log (using the third party tool
  924. \fBgit\-browser\fR):
  925. .sp
  926. .if n \{\
  927. .RS 4
  928. .\}
  929. .nf
  930. $feature{\*(Aqactions\*(Aq}{\*(Aqdefault\*(Aq} =
  931. [ (\*(Aqgraphiclog\*(Aq, \*(Aq/git\-browser/by\-commit\&.html?r=%n\*(Aq, \*(Aqsummary\*(Aq)];
  932. .fi
  933. .if n \{\
  934. .RE
  935. .\}
  936. .sp
  937. This adds a link titled "graphiclog" after the "summary" link, leading to
  938. \fBgit\-browser\fR
  939. script, passing
  940. \fBr=\fR\fI<project>\fR
  941. as a query parameter\&.
  942. .sp
  943. Project specific override is not supported\&.
  944. .RE
  945. .PP
  946. timed
  947. .RS 4
  948. 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\&.
  949. .sp
  950. Project specific override is not supported\&.
  951. .RE
  952. .PP
  953. javascript\-timezone
  954. .RS 4
  955. 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\&.
  956. .sp
  957. The value is a list of three values: a default time zone (for if the client hasn\(cqt 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: []\&.
  958. .sp
  959. Typical gitweb config files will only change starting (default) time zone, and leave other elements at their default values:
  960. .sp
  961. .if n \{\
  962. .RS 4
  963. .\}
  964. .nf
  965. $feature{\*(Aqjavascript\-timezone\*(Aq}{\*(Aqdefault\*(Aq}[0] = "utc";
  966. .fi
  967. .if n \{\
  968. .RE
  969. .\}
  970. .sp
  971. The example configuration presented here is guaranteed to be backwards and forward compatible\&.
  972. .sp
  973. 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"\&.
  974. .sp
  975. Project specific override is not supported\&.
  976. .RE
  977. .PP
  978. extra\-branch\-refs
  979. .RS 4
  980. 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:
  981. .sp
  982. .if n \{\
  983. .RS 4
  984. .\}
  985. .nf
  986. $feature{\*(Aqextra\-branch\-refs\*(Aq}{\*(Aqdefault\*(Aq} =
  987. [\*(Aqsandbox\*(Aq, \*(Aqwip\*(Aq, \*(Aqother\*(Aq];
  988. .fi
  989. .if n \{\
  990. .RE
  991. .\}
  992. .sp
  993. This feature can be configured on per\-repository basis after setting $feature{\fIextra\-branch\-refs\fR}{\fIoverride\fR} to true, via repository\(cqs
  994. \fBgitweb\&.extraBranchRefs\fR
  995. configuration variable, which contains a space separated list of refs\&. An example:
  996. .sp
  997. .if n \{\
  998. .RS 4
  999. .\}
  1000. .nf
  1001. [gitweb]
  1002. extraBranchRefs = sandbox wip other
  1003. .fi
  1004. .if n \{\
  1005. .RE
  1006. .\}
  1007. .sp
  1008. 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:
  1009. .sp
  1010. .if n \{\
  1011. .RS 4
  1012. .\}
  1013. .nf
  1014. [gitweb]
  1015. extraBranchRefs = sandbox
  1016. extraBranchRefs = wip other
  1017. .fi
  1018. .if n \{\
  1019. .RE
  1020. .\}
  1021. .sp
  1022. It is an error to specify a ref that does not pass "git check\-ref\-format" scrutiny\&. Duplicated values are filtered\&.
  1023. .RE
  1024. .SH "EXAMPLES"
  1025. .sp
  1026. 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:
  1027. .sp
  1028. .if n \{\
  1029. .RS 4
  1030. .\}
  1031. .nf
  1032. $feature{\*(Aqblame\*(Aq}{\*(Aqdefault\*(Aq} = [1];
  1033. $feature{\*(Aqblame\*(Aq}{\*(Aqoverride\*(Aq} = 1;
  1034. $feature{\*(Aqpickaxe\*(Aq}{\*(Aqdefault\*(Aq} = [1];
  1035. $feature{\*(Aqpickaxe\*(Aq}{\*(Aqoverride\*(Aq} = 1;
  1036. $feature{\*(Aqsnapshot\*(Aq}{\*(Aqdefault\*(Aq} = [\*(Aqzip\*(Aq, \*(Aqtgz\*(Aq];
  1037. $feature{\*(Aqsnapshot\*(Aq}{\*(Aqoverride\*(Aq} = 1;
  1038. .fi
  1039. .if n \{\
  1040. .RE
  1041. .\}
  1042. .sp
  1043. 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 \fBgzip\fR(1) to run at level 6 by adding the following lines to your gitweb configuration file:
  1044. .sp
  1045. .if n \{\
  1046. .RS 4
  1047. .\}
  1048. .nf
  1049. $known_snapshot_formats{\*(Aqzip\*(Aq}{\*(Aqdisabled\*(Aq} = 1;
  1050. $known_snapshot_formats{\*(Aqtgz\*(Aq}{\*(Aqcompressor\*(Aq} = [\*(Aqgzip\*(Aq,\*(Aq\-6\*(Aq];
  1051. .fi
  1052. .if n \{\
  1053. .RE
  1054. .\}
  1055. .SH "BUGS"
  1056. .sp
  1057. Debugging would be easier if the fallback configuration file (\fB/etc/gitweb\&.conf\fR) and environment variable to override its location (\fIGITWEB_CONFIG_SYSTEM\fR) had names reflecting their "fallback" role\&. The current names are kept to avoid breaking working setups\&.
  1058. .SH "ENVIRONMENT"
  1059. .sp
  1060. The location of per\-instance and system\-wide configuration files can be overridden using the following environment variables:
  1061. .PP
  1062. GITWEB_CONFIG
  1063. .RS 4
  1064. Sets location of per\-instance configuration file\&.
  1065. .RE
  1066. .PP
  1067. GITWEB_CONFIG_SYSTEM
  1068. .RS 4
  1069. Sets location of fallback system\-wide configuration file\&. This file is read only if per\-instance one does not exist\&.
  1070. .RE
  1071. .PP
  1072. GITWEB_CONFIG_COMMON
  1073. .RS 4
  1074. Sets location of common system\-wide configuration file\&.
  1075. .RE
  1076. .SH "FILES"
  1077. .PP
  1078. gitweb_config\&.perl
  1079. .RS 4
  1080. This is default name of per\-instance configuration file\&. The format of this file is described above\&.
  1081. .RE
  1082. .PP
  1083. /etc/gitweb\&.conf
  1084. .RS 4
  1085. This is default name of fallback system\-wide configuration file\&. This file is used only if per\-instance configuration variable is not found\&.
  1086. .RE
  1087. .PP
  1088. /etc/gitweb\-common\&.conf
  1089. .RS 4
  1090. This is default name of common system\-wide configuration file\&.
  1091. .RE
  1092. .SH "SEE ALSO"
  1093. .sp
  1094. \fBgitweb\fR(1), \fBgit-instaweb\fR(1)
  1095. .sp
  1096. \fIgitweb/README\fR, \fIgitweb/INSTALL\fR
  1097. .SH "GIT"
  1098. .sp
  1099. Part of the \fBgit\fR(1) suite