10 cgitrc - runtime configuration for cgit
15 Cgitrc contains all runtime settings for cgit, including the list of git
16 repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
17 lines, and lines starting with '#', are ignored.
22 The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
23 runtime, cgit will consult the environment variable CGIT_CONFIG and, if
24 defined, use its value instead.
30 Specifies a command which will be invoked to format the content of
31 about pages (both top-level and for each repository). The command will
32 get the content of the about-file on its STDIN, and the STDOUT from the
33 command will be included verbatim on the about page. Default value:
34 none. See also: "FILTER API".
37 Specifies a path, relative to each repository path, which can be used
38 to specify the date and time of the youngest commit in the repository.
39 The first line in the file is used as input to the "parse_date"
40 function in libgit. Recommended timestamp-format is "yyyy-mm-dd
41 hh:mm:ss". Default value: "info/web/last-modified".
44 Path used to store the cgit cache entries. Default value:
45 "/var/cache/cgit". See also: "MACRO EXPANSION".
48 Number which specifies the time-to-live, in minutes, for the cached
49 version of repository pages accessed without a fixed SHA1. Default
53 Number which specifies the time-to-live, in minutes, for the cached
54 version of the repository summary page. Default value: "5".
57 Number which specifies the time-to-live, in minutes, for the cached
58 version of the repository index page. Default value: "5".
61 Number which specifies the time-to-live, in minutes, for the result
62 of scanning a path for git repositories. Default value: "15".
65 The maximum number of entries in the cgit cache. Default value: "0"
66 (i.e. caching is disabled).
69 Number which specifies the time-to-live, in minutes, for the cached
70 version of repository pages accessed with a fixed SHA1. Default value:
74 Space-separated list of common prefixes which, when combined with a
75 repository url, generates valid clone urls for the repository. This
76 setting is only used if `repo.clone-url` is unspecified. Default value:
80 Space-separated list of clone-url templates. This setting is only
81 used if `repo.clone-url` is unspecified. Default value: none. See
82 also: "MACRO EXPANSION", "FILTER API".
85 Specifies a command which will be invoked to format commit messages.
86 The command will get the message on its STDIN, and the STDOUT from the
87 command will be included verbatim as the commit message, i.e. this can
88 be used to implement bugtracker integration. Default value: none.
89 See also: "FILTER API".
92 Url which specifies the css document to include in all cgit pages.
93 Default value: "/cgit.css".
96 Flag which, when set to "1", will make cgit generate a html fragment
97 suitable for embedding in other html pages. Default value: none. See
100 enable-commit-graph::
101 Flag which, when set to "1", will make cgit print an ASCII-art commit
102 history graph to the left of the commit messages in the repository
103 log page. Default value: "0".
105 enable-filter-overrides::
106 Flag which, when set to "1", allows all filter settings to be
107 overridden in repository-specific cgitrc files. Default value: none.
110 If set to "1" and scan-path is enabled, we first check each repository
111 for the git config value "gitweb.description" to determine the owner.
112 Otherwise, the description is read from a file titled "description"
113 inside of the repository directory.
114 Default value: "1". See also: scan-path.
116 enable-gitweb-owner::
117 If set to "1" and scan-path is enabled, we first check each repository
118 for the git config value "gitweb.owner" to determine the owner.
119 Default value: "1". See also: scan-path.
122 If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
123 If you use an alternate way of serving git repositories, you may wish
124 to disable this. Default value: "1".
127 Flag which, when set to "1", will make cgit generate extra links for
128 each repo in the repository index (specifically, to the "summary",
129 "commit" and "tree" pages). Default value: "0".
131 enable-log-filecount::
132 Flag which, when set to "1", will make cgit print the number of
133 modified files for each commit on the repository log page. Default
136 enable-log-linecount::
137 Flag which, when set to "1", will make cgit print the number of added
138 and removed lines for each commit on the repository log page. Default
141 enable-remote-branches::
142 Flag which, when set to "1", will make cgit display remote branches
143 in the summary and refs views. Default value: "0". See also:
144 "repo.enable-remote-branches".
146 enable-subject-links::
147 Flag which, when set to "1", will make cgit use the subject of the
148 parent commit as link text when generating links to parent commits
149 in commit view. Default value: "0". See also:
150 "repo.enable-subject-links".
152 enable-tree-linenumbers::
153 Flag which, when set to "1", will make cgit generate linenumber links
154 for plaintext blobs printed in the tree view. Default value: "1".
157 Url used as link to a shortcut icon for cgit. If specified, it is
158 suggested to use the value "/favicon.ico" since certain browsers will
159 ignore other values. Default value: none.
162 The content of the file specified with this option will be included
163 verbatim at the bottom of all pages (i.e. it replaces the standard
164 "generated by..." message. Default value: none.
167 The content of the file specified with this option will be included
168 verbatim in the html HEAD section on all pages. Default value: none.
171 The content of the file specified with this option will be included
172 verbatim at the top of all pages. Default value: none.
175 Name of a configfile to include before the rest of the current config-
176 file is parsed. Default value: none. See also: "MACRO EXPANSION".
179 The content of the file specified with this option will be included
180 verbatim above the repository index. This setting is deprecated, and
181 will not be supported by cgit-1.0 (use root-readme instead). Default
185 The content of the file specified with this option will be included
186 verbatim below the heading on the repository index page. This setting
187 is deprecated, and will not be supported by cgit-1.0 (use root-desc
188 instead). Default value: none.
191 Flag which, if set to "1", makes cgit print commit and tag times in the
192 servers timezone. Default value: "0".
195 Url which specifies the source of an image which will be used as a logo
196 on all cgit pages. Default value: "/cgit.png".
199 Url loaded when clicking on the cgit logo image. If unspecified the
200 calculated url of the repository index page will be used. Default
204 Specifies the number of items to display in atom feeds view. Default
208 Specifies the number of entries to list per page in "log" view. Default
212 Specifies the maximum number of commit message characters to display in
213 "log" view. Default value: "80".
216 Specifies the number of entries to list per page on the repository
217 index page. Default value: "50".
219 max-repodesc-length::
220 Specifies the maximum number of repo description characters to display
221 on the repository index page. Default value: "80".
224 Specifies the maximum size of a blob to display HTML for in KBytes.
225 Default value: "0" (limit disabled).
228 Set the default maximum statistics period. Valid values are "week",
229 "month", "quarter" and "year". If unspecified, statistics are
230 disabled. Default value: none. See also: "repo.max-stats".
233 Set the mimetype for the specified filename extension. This is used
234 by the `plain` command when returning blob content.
237 Specifies the file to use for automatic mimetype lookup. If specified
238 then this field is used as a fallback when no "mimetype.<ext>" match is
239 found. If unspecified then no such lookup is performed. The typical file
240 to use on a Linux system is /etc/mime.types. Default value: none. See
241 also: "mimetype.<ext>". The format of the file must comply to:
242 - a comment line is an empty line or a line starting with a hash (#),
243 optionally preceded by whitespace
244 - a non-comment line starts with the mimetype (like image/png), followed
245 by one or more file extensions (like jpg), all separated by whitespace
248 Text which will be used as the formatstring for a hyperlink when a
249 submodule is printed in a directory listing. The arguments for the
250 formatstring are the path and SHA1 of the submodule commit. Default
254 If set to the value "1" caching will be disabled. This settings is
255 deprecated, and will not be honored starting with cgit-1.0. Default
259 If set to "1" showing full author email adresses will be disabled.
263 Flag which, when set to "1", will make cgit omit the standard header
264 on all pages. Default value: none. See also: "embedded".
267 A list of subdirectories inside of scan-path, relative to it, that
268 should loaded as git repositories. This must be defined prior to
269 scan-path. Default value: none. See also: scan-path, "MACRO
273 Text which will be used as default value for "repo.readme". Default
277 If set to "1" and scan-path is enabled, if any repositories are found
278 with a suffix of ".git", this suffix will be removed for the url and
279 name. Default value: "0". See also: scan-path.
282 Maximum number of files to consider when detecting renames. The value
283 "-1" uses the compiletime value in git (for further info, look at
284 `man git-diff`). Default value: "-1".
287 Legacy alias for "section". This option is deprecated and will not be
288 supported in cgit-1.0.
291 Text used as content for the "robots" meta-tag. Default value:
295 Text printed below the heading on the repository index page. Default
296 value: "a fast webinterface for the git dscm".
299 The content of the file specified with this option will be included
300 verbatim below the "about" link on the repository index page. Default
304 Text printed as heading on the repository index page. Default value:
305 "Git Repository Browser".
308 If set to "1" and scan-path is enabled, scan-path will recurse into
309 directories whose name starts with a period ('.'). Otherwise,
310 scan-path will stay away from such directories (considered as
311 "hidden"). Note that this does not apply to the ".git" directory in
312 non-bare repos. This must be defined prior to scan-path.
313 Default value: 0. See also: scan-path.
316 A path which will be scanned for repositories. If caching is enabled,
317 the result will be cached as a cgitrc include-file in the cache
318 directory. If project-list has been defined prior to scan-path,
319 scan-path loads only the directories listed in the file pointed to by
320 project-list. Be advised that only the global settings taken
321 before the scan-path directive will be applied to each repository.
322 Default value: none. See also: cache-scanrc-ttl, project-list,
326 The name of the current repository section - all repositories defined
327 after this option will inherit the current section name. Default value:
331 A number which, if specified before scan-path, specifies how many
332 path elements from each repo path to use as a default section name.
333 If negative, cgit will discard the specified number of path elements
334 above the repo directory. Default value: 0.
337 If set to "1" shows side-by-side diffs instead of unidiffs per
338 default. Default value: "0".
341 Text which specifies the default set of snapshot formats generated by
342 cgit. The value is a space-separated list of zero or more of the
343 values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
347 Specifies a command which will be invoked to format plaintext blobs
348 in the tree view. The command will get the blob content on its STDIN
349 and the name of the blob as its only command line argument. The STDOUT
350 from the command will be included verbatim as the blob contents, i.e.
351 this can be used to implement e.g. syntax highlighting. Default value:
352 none. See also: "FILTER API".
355 Specifies the number of branches to display in the repository "summary"
356 view. Default value: "10".
359 Specifies the number of log entries to display in the repository
360 "summary" view. Default value: "10".
363 Specifies the number of tags to display in the repository "summary"
364 view. Default value: "10".
367 Filename which, if specified, needs to be present within the repository
368 for cgit to allow access to that repository. This can be used to emulate
369 gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
370 repositories to match those exported by git-daemon. This option MUST come
374 Url which, if specified, will be used as root for all cgit links. It
375 will also cause cgit to generate 'virtual urls', i.e. urls like
376 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
378 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
379 same kind of virtual urls, so this option will probably be deprecated.
384 Override the default about-filter. Default value: none. See also:
385 "enable-filter-overrides". See also: "FILTER API".
388 A list of space-separated urls which can be used to clone this repo.
389 Default value: none. See also: "MACRO EXPANSION".
392 Override the default commit-filter. Default value: none. See also:
393 "enable-filter-overrides". See also: "FILTER API".
396 The name of the default branch for this repository. If no such branch
397 exists in the repository, the first branch name (when sorted) is used
398 as default instead. Default value: branch pointed to by HEAD, or
399 "master" if there is no suitable HEAD.
402 The value to show as repository description. Default value: none.
404 repo.enable-commit-graph::
405 A flag which can be used to disable the global setting
406 `enable-commit-graph'. Default value: none.
408 repo.enable-log-filecount::
409 A flag which can be used to disable the global setting
410 `enable-log-filecount'. Default value: none.
412 repo.enable-log-linecount::
413 A flag which can be used to disable the global setting
414 `enable-log-linecount'. Default value: none.
416 repo.enable-remote-branches::
417 Flag which, when set to "1", will make cgit display remote branches
418 in the summary and refs views. Default value: <enable-remote-branches>.
420 repo.enable-subject-links::
421 A flag which can be used to override the global setting
422 `enable-subject-links'. Default value: none.
425 Url which specifies the source of an image which will be used as a logo
426 on this repo's pages. Default value: global logo.
429 Url loaded when clicking on the cgit logo image. If unspecified the
430 calculated url of the repository index page will be used. Default
431 value: global logo-link.
434 Text which will be used as the formatstring for a hyperlink when a
435 submodule is printed in a directory listing. The arguments for the
436 formatstring are the path and SHA1 of the submodule commit. Default
439 repo.module-link.<path>::
440 Text which will be used as the formatstring for a hyperlink when a
441 submodule with the specified subdirectory path is printed in a
442 directory listing. The only argument for the formatstring is the SHA1
443 of the submodule commit. Default value: none.
446 Override the default maximum statistics period. Valid values are equal
447 to the values specified for the global "max-stats" setting. Default
451 The value to show as repository name. Default value: <repo.url>.
454 A value used to identify the owner of the repository. Default value:
458 An absolute path to the repository directory. For non-bare repositories
459 this is the .git-directory. Default value: none.
462 A path (relative to <repo.path>) which specifies a file to include
463 verbatim as the "About" page for this repo. You may also specify a
464 git refspec by head or by hash by prepending the refspec followed by
465 a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
468 A mask of allowed snapshot-formats for this repo, restricted by the
469 "snapshots" global setting. Default value: <snapshots>.
472 Override the current section name for this repository. Default value:
476 Override the default source-filter. Default value: none. See also:
477 "enable-filter-overrides". See also: "FILTER API".
480 The relative url used to access the repository. This must be the first
481 setting specified for each repo. Default value: none.
484 REPOSITORY-SPECIFIC CGITRC FILE
485 -------------------------------
486 When the option "scan-path" is used to auto-discover git repositories, cgit
487 will try to parse the file "cgitrc" within any found repository. Such a
488 repo-specific config file may contain any of the repo-specific options
489 described above, except "repo.url" and "repo.path". Additionally, the "filter"
490 options are only acknowledged in repo-specific config files when
491 "enable-filter-overrides" is set to "1".
493 Note: the "repo." prefix is dropped from the option names in repo-specific
494 config files, e.g. "repo.desc" becomes "desc".
500 This filter is given no arguments. The about text that is to be
501 filtered is available on standard input and the filtered text is
502 expected on standard output.
505 This filter is given no arguments. The commit message text that is to
506 be filtered is available on standard input and the filtered text is
507 expected on standard output.
510 This filter is given a single parameter: the filename of the source
511 file to filter. The filter can use the filename to determine (for
512 example) the syntax highlighting mode. The contents of the source
513 file that is to be filtered is available on standard input and the
514 filtered contents is expected on standard output.
516 Also, all filters are handed the following environment variables:
518 - CGIT_REPO_URL (from repo.url)
519 - CGIT_REPO_NAME (from repo.name)
520 - CGIT_REPO_PATH (from repo.path)
521 - CGIT_REPO_OWNER (from repo.owner)
522 - CGIT_REPO_DEFBRANCH (from repo.defbranch)
523 - CGIT_REPO_SECTION (from repo.section)
524 - CGIT_REPO_CLONE_URL (from repo.clone-url)
526 If a setting is not defined for a repository and the corresponding global
527 setting is also not defined (if applicable), then the corresponding
528 environment variable will be unset.
533 The following cgitrc options supports a simple macro expansion feature,
534 where tokens prefixed with "$" are replaced with the value of a similary
535 named environment variable:
542 Macro expansion will also happen on the content of $CGIT_CONFIG, if
545 One usage of this feature is virtual hosting, which in its simplest form
546 can be accomplished by adding the following line to /etc/cgitrc:
548 include=/etc/cgitrc.d/$HTTP_HOST
550 The following options are expanded during request processing, and support
551 the environment variables defined in "FILTER API":
561 # Enable caching of up to 1000 output entriess
565 # Specify some default clone urls using macro expansion
566 clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
568 # Specify the css url
572 # Show extra links for each repository on the index page
576 # Enable ASCII art commit history graph on the log pages
577 enable-commit-graph=1
580 # Show number of affected files per commit on the log pages
581 enable-log-filecount=1
584 # Show number of added/removed lines per commit on the log pages
585 enable-log-linecount=1
596 # Enable statistics per week, month and quarter
600 # Set the title and heading of the repository index page
601 root-title=example.com git repositories
604 # Set a subheading for the repository index page
605 root-desc=tracking the foobar development
608 # Include some more info about example.com on the index page
609 root-readme=/var/www/htdocs/about.html
612 # Allow download of tar.gz, tar.bz2 and zip-files
613 snapshots=tar.gz tar.bz2 zip
617 ## List of common mimetypes
620 mimetype.gif=image/gif
621 mimetype.html=text/html
622 mimetype.jpg=image/jpeg
623 mimetype.jpeg=image/jpeg
624 mimetype.pdf=application/pdf
625 mimetype.png=image/png
626 mimetype.svg=image/svg+xml
630 ## List of repositories.
631 ## PS: Any repositories listed when section is unset will not be
632 ## displayed under a section heading
633 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
634 ## and included like this:
635 ## include=/etc/cgitrepos
640 repo.path=/pub/git/foo.git
641 repo.desc=the master foo repository
642 repo.owner=fooman@example.com
643 repo.readme=info/web/about.html
647 repo.path=/pub/git/bar.git
648 repo.desc=the bars for your foo
649 repo.owner=barman@example.com
650 repo.readme=info/web/about.html
653 # The next repositories will be displayed under the 'extras' heading
658 repo.path=/pub/git/baz.git
659 repo.desc=a set of extensions for bar users
662 repo.path=/pub/git/wiz.git
663 repo.desc=the wizard of foo
666 # Add some mirrored repositories
671 repo.path=/pub/git/git.git
676 repo.path=/pub/git/linux.git
679 # Disable adhoc downloads of this repo
682 # Disable line-counts for this repo
683 repo.enable-log-linecount=0
685 # Restrict the max statistics period for this repo
692 Comments currently cannot appear on the same line as a setting; the comment
693 will be included as part of the value. E.g. this line:
695 robots=index # allow indexing
697 will generate the following html element:
699 <meta name='robots' content='index # allow indexing'/>
705 Lars Hjemli <hjemli@gmail.com>
706 Jason A. Donenfeld <Jason@zx2c4.com>