@matheusbsbs / matheus-bagliano / commits / 6d3902b0d0

gitweb: Add gitweb.conf(5) manpage for gitweb configuration files

Much of what is in gitweb.conf.txt has been pulled directly from the README file of gitweb. The manpage was supplemented with description of missing gitweb config variables, and with description of gitweb's %features. There remains a bit of redundancy, which should be reduced if possible... but I think some of duplication of information is inevitable. [jn: Improved, extended, removed duplicate info from README] Signed-off-by: Drew Northup <drew.northup@maine.edu> Signed-off-by: Jakub Narebski <jnareb@gmail.com> Helped-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

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