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 Specifies a command which will be invoked to format commit messages.
81 The command will get the message on its STDIN, and the STDOUT from the
82 command will be included verbatim as the commit message, i.e. this can
83 be used to implement bugtracker integration. Default value: none.
84 See also: "FILTER API".
87 Url which specifies the css document to include in all cgit pages.
88 Default value: "/cgit.css".
91 Flag which, when set to "1", will make cgit generate a html fragment
92 suitable for embedding in other html pages. Default value: none. See
96 Flag which, when set to "1", will make cgit print an ASCII-art commit
97 history graph to the left of the commit messages in the repository
98 log page. Default value: "0".
100 enable-filter-overrides::
101 Flag which, when set to "1", allows all filter settings to be
102 overridden in repository-specific cgitrc files. Default value: none.
104 enable-gitweb-owner::
105 If set to "1" and scan-path is enabled, we first check each repository
106 for the git config value "gitweb.owner" to determine the owner.
107 Default value: "1". See also: scan-path.
110 If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
111 If you use an alternate way of serving git repositories, you may wish
112 to disable this. Default value: "1".
115 Flag which, when set to "1", will make cgit generate extra links for
116 each repo in the repository index (specifically, to the "summary",
117 "commit" and "tree" pages). Default value: "0".
119 enable-log-filecount::
120 Flag which, when set to "1", will make cgit print the number of
121 modified files for each commit on the repository log page. Default
124 enable-log-linecount::
125 Flag which, when set to "1", will make cgit print the number of added
126 and removed lines for each commit on the repository log page. Default
129 enable-remote-branches::
130 Flag which, when set to "1", will make cgit display remote branches
131 in the summary and refs views. Default value: "0". See also:
132 "repo.enable-remote-branches".
134 enable-subject-links::
135 Flag which, when set to "1", will make cgit use the subject of the
136 parent commit as link text when generating links to parent commits
137 in commit view. Default value: "0". See also:
138 "repo.enable-subject-links".
140 enable-tree-linenumbers::
141 Flag which, when set to "1", will make cgit generate linenumber links
142 for plaintext blobs printed in the tree view. Default value: "1".
145 Url used as link to a shortcut icon for cgit. If specified, it is
146 suggested to use the value "/favicon.ico" since certain browsers will
147 ignore other values. Default value: none.
150 The content of the file specified with this option will be included
151 verbatim at the bottom of all pages (i.e. it replaces the standard
152 "generated by..." message. Default value: none.
155 The content of the file specified with this option will be included
156 verbatim in the html HEAD section on all pages. Default value: none.
159 The content of the file specified with this option will be included
160 verbatim at the top of all pages. Default value: none.
163 Name of a configfile to include before the rest of the current config-
164 file is parsed. Default value: none. See also: "MACRO EXPANSION".
167 The content of the file specified with this option will be included
168 verbatim above the repository index. This setting is deprecated, and
169 will not be supported by cgit-1.0 (use root-readme instead). Default
173 The content of the file specified with this option will be included
174 verbatim below the heading on the repository index page. This setting
175 is deprecated, and will not be supported by cgit-1.0 (use root-desc
176 instead). Default value: none.
179 Flag which, if set to "1", makes cgit print commit and tag times in the
180 servers timezone. Default value: "0".
183 Url which specifies the source of an image which will be used as a logo
184 on all cgit pages. Default value: "/cgit.png".
187 Url loaded when clicking on the cgit logo image. If unspecified the
188 calculated url of the repository index page will be used. Default
192 Specifies the number of items to display in atom feeds view. Default
196 Specifies the number of entries to list per page in "log" view. Default
200 Specifies the maximum number of commit message characters to display in
201 "log" view. Default value: "80".
204 Specifies the number of entries to list per page on the repository
205 index page. Default value: "50".
207 max-repodesc-length::
208 Specifies the maximum number of repo description characters to display
209 on the repository index page. Default value: "80".
212 Specifies the maximum size of a blob to display HTML for in KBytes.
213 Default value: "0" (limit disabled).
216 Set the default maximum statistics period. Valid values are "week",
217 "month", "quarter" and "year". If unspecified, statistics are
218 disabled. Default value: none. See also: "repo.max-stats".
221 Set the mimetype for the specified filename extension. This is used
222 by the `plain` command when returning blob content.
225 Text which will be used as the formatstring for a hyperlink when a
226 submodule is printed in a directory listing. The arguments for the
227 formatstring are the path and SHA1 of the submodule commit. Default
228 value: "./?repo=%s&page=commit&id=%s"
231 If set to the value "1" caching will be disabled. This settings is
232 deprecated, and will not be honored starting with cgit-1.0. Default
236 If set to "1" showing full author email adresses will be disabled.
240 Flag which, when set to "1", will make cgit omit the standard header
241 on all pages. Default value: none. See also: "embedded".
244 A list of subdirectories inside of scan-path, relative to it, that
245 should loaded as git repositories. This must be defined prior to
246 scan-path. Default value: none. See also: scan-path, "MACRO
250 Text which will be used as default value for "repo.readme". Default
254 If set to "1" and scan-path is enabled, if any repositories are found
255 with a suffix of ".git", this suffix will be removed for the url and
256 name. Default value: "0". See also: scan-path.
259 Maximum number of files to consider when detecting renames. The value
260 "-1" uses the compiletime value in git (for further info, look at
261 `man git-diff`). Default value: "-1".
264 Legacy alias for "section". This option is deprecated and will not be
265 supported in cgit-1.0.
268 Text used as content for the "robots" meta-tag. Default value:
272 Text printed below the heading on the repository index page. Default
273 value: "a fast webinterface for the git dscm".
276 The content of the file specified with this option will be included
277 verbatim below the "about" link on the repository index page. Default
281 Text printed as heading on the repository index page. Default value:
282 "Git Repository Browser".
285 If set to "1" and scan-path is enabled, scan-path will recurse into
286 directories whose name starts with a period ('.'). Otherwise,
287 scan-path will stay away from such directories (considered as
288 "hidden"). Note that this does not apply to the ".git" directory in
289 non-bare repos. This must be defined prior to scan-path.
290 Default value: 0. See also: scan-path.
293 A path which will be scanned for repositories. If caching is enabled,
294 the result will be cached as a cgitrc include-file in the cache
295 directory. If project-list has been defined prior to scan-path,
296 scan-path loads only the directories listed in the file pointed to by
297 project-list. Be advised that only the global settings taken
298 before the scan-path directive will be applied to each repository.
299 Default value: none. See also: cache-scanrc-ttl, project-list,
303 The name of the current repository section - all repositories defined
304 after this option will inherit the current section name. Default value:
308 A number which, if specified before scan-path, specifies how many
309 path elements from each repo path to use as a default section name.
310 If negative, cgit will discard the specified number of path elements
311 above the repo directory. Default value: 0.
314 If set to "1" shows side-by-side diffs instead of unidiffs per
315 default. Default value: "0".
318 Text which specifies the default set of snapshot formats generated by
319 cgit. The value is a space-separated list of zero or more of the
320 values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
324 Specifies a command which will be invoked to format plaintext blobs
325 in the tree view. The command will get the blob content on its STDIN
326 and the name of the blob as its only command line argument. The STDOUT
327 from the command will be included verbatim as the blob contents, i.e.
328 this can be used to implement e.g. syntax highlighting. Default value:
329 none. See also: "FILTER API".
332 Specifies the number of branches to display in the repository "summary"
333 view. Default value: "10".
336 Specifies the number of log entries to display in the repository
337 "summary" view. Default value: "10".
340 Specifies the number of tags to display in the repository "summary"
341 view. Default value: "10".
344 Filename which, if specified, needs to be present within the repository
345 for cgit to allow access to that repository. This can be used to emulate
346 gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
347 repositories to match those exported by git-daemon. This option MUST come
351 Url which, if specified, will be used as root for all cgit links. It
352 will also cause cgit to generate 'virtual urls', i.e. urls like
353 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
355 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
356 same kind of virtual urls, so this option will probably be deprecated.
361 Override the default about-filter. Default value: none. See also:
362 "enable-filter-overrides". See also: "FILTER API".
365 A list of space-separated urls which can be used to clone this repo.
369 Override the default commit-filter. Default value: none. See also:
370 "enable-filter-overrides". See also: "FILTER API".
373 The name of the default branch for this repository. If no such branch
374 exists in the repository, the first branch name (when sorted) is used
375 as default instead. Default value: "master".
378 The value to show as repository description. Default value: none.
380 repo.enable-commit-graph::
381 A flag which can be used to disable the global setting
382 `enable-commit-graph'. Default value: none.
384 repo.enable-log-filecount::
385 A flag which can be used to disable the global setting
386 `enable-log-filecount'. Default value: none.
388 repo.enable-log-linecount::
389 A flag which can be used to disable the global setting
390 `enable-log-linecount'. Default value: none.
392 repo.enable-remote-branches::
393 Flag which, when set to "1", will make cgit display remote branches
394 in the summary and refs views. Default value: <enable-remote-branches>.
396 repo.enable-subject-links::
397 A flag which can be used to override the global setting
398 `enable-subject-links'. Default value: none.
401 Url which specifies the source of an image which will be used as a logo
402 on this repo's pages. Default value: global logo.
405 Url loaded when clicking on the cgit logo image. If unspecified the
406 calculated url of the repository index page will be used. Default
407 value: global logo-link.
410 Override the default maximum statistics period. Valid values are equal
411 to the values specified for the global "max-stats" setting. Default
415 The value to show as repository name. Default value: <repo.url>.
418 A value used to identify the owner of the repository. Default value:
422 An absolute path to the repository directory. For non-bare repositories
423 this is the .git-directory. Default value: none.
426 A path (relative to <repo.path>) which specifies a file to include
427 verbatim as the "About" page for this repo. You may also specify a
428 git refspec by head or by hash by prepending the refspec followed by
429 a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
432 A mask of allowed snapshot-formats for this repo, restricted by the
433 "snapshots" global setting. Default value: <snapshots>.
436 Override the current section name for this repository. Default value:
440 Override the default source-filter. Default value: none. See also:
441 "enable-filter-overrides". See also: "FILTER API".
444 The relative url used to access the repository. This must be the first
445 setting specified for each repo. Default value: none.
448 REPOSITORY-SPECIFIC CGITRC FILE
449 -------------------------------
450 When the option "scan-path" is used to auto-discover git repositories, cgit
451 will try to parse the file "cgitrc" within any found repository. Such a
452 repo-specific config file may contain any of the repo-specific options
453 described above, except "repo.url" and "repo.path". Additionally, the "filter"
454 options are only acknowledged in repo-specific config files when
455 "enable-filter-overrides" is set to "1".
457 Note: the "repo." prefix is dropped from the option names in repo-specific
458 config files, e.g. "repo.desc" becomes "desc".
464 This filter is given no arguments.
465 The about text that is to be filtered is available on standard input and the
466 filtered text is expected on standard output.
468 This filter is given no arguments.
469 The commit message text that is to be filtered is available on standard input
470 and the filtered text is expected on standard output.
472 This filter is given a single parameter: the filename of the source file to
473 filter. The filter can use the filename to determine (for example) the syntax
475 The contents of the source file that is to be filtered is available on
476 standard input and the filtered contents is expected on standard output.
478 Also, all filters are handed the following environment variables:
479 - CGIT_REPO_URL ( = repo.url setting )
480 - CGIT_REPO_NAME ( = repo.name setting )
481 - CGIT_REPO_PATH ( = repo.path setting )
482 - CGIT_REPO_OWNER ( = repo.owner setting )
483 - CGIT_REPO_DEFBRANCH ( = repo.defbranch setting )
484 - CGIT_REPO_SECTION ( = section setting )
485 - CGIT_REPO_CLONE_URL ( = repo.clone-url setting )
487 If a setting is not defined for a repository and the corresponding global
488 setting is also not defined (if applicable), then the corresponding
489 environment variable will be an empty string.
491 Note that under normal circumstance all these environment variables are
492 defined. If however the total size of the defined settings exceed the
493 allocated buffer within cgit then only the environment variables that fit
494 in the allocated buffer are handed to the filter.
499 The following cgitrc options supports a simple macro expansion feature,
500 where tokens prefixed with "$" are replaced with the value of a similary
501 named environment variable:
508 Macro expansion will also happen on the content of $CGIT_CONFIG, if
511 One usage of this feature is virtual hosting, which in its simplest form
512 can be accomplished by adding the following line to /etc/cgitrc:
514 include=/etc/cgitrc.d/$HTTP_HOST
521 # Enable caching of up to 1000 output entriess
525 # Specify some default clone prefixes
526 clone-prefix=git://example.com ssh://example.com/pub/git http://example.com/git
528 # Specify the css url
532 # Show extra links for each repository on the index page
536 # Enable ASCII art commit history graph on the log pages
537 enable-commit-graph=1
540 # Show number of affected files per commit on the log pages
541 enable-log-filecount=1
544 # Show number of added/removed lines per commit on the log pages
545 enable-log-linecount=1
556 # Enable statistics per week, month and quarter
560 # Set the title and heading of the repository index page
561 root-title=example.com git repositories
564 # Set a subheading for the repository index page
565 root-desc=tracking the foobar development
568 # Include some more info about example.com on the index page
569 root-readme=/var/www/htdocs/about.html
572 # Allow download of tar.gz, tar.bz2 and zip-files
573 snapshots=tar.gz tar.bz2 zip
577 ## List of common mimetypes
580 mimetype.gif=image/gif
581 mimetype.html=text/html
582 mimetype.jpg=image/jpeg
583 mimetype.jpeg=image/jpeg
584 mimetype.pdf=application/pdf
585 mimetype.png=image/png
586 mimetype.svg=image/svg+xml
590 ## List of repositories.
591 ## PS: Any repositories listed when section is unset will not be
592 ## displayed under a section heading
593 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
594 ## and included like this:
595 ## include=/etc/cgitrepos
600 repo.path=/pub/git/foo.git
601 repo.desc=the master foo repository
602 repo.owner=fooman@example.com
603 repo.readme=info/web/about.html
607 repo.path=/pub/git/bar.git
608 repo.desc=the bars for your foo
609 repo.owner=barman@example.com
610 repo.readme=info/web/about.html
613 # The next repositories will be displayed under the 'extras' heading
618 repo.path=/pub/git/baz.git
619 repo.desc=a set of extensions for bar users
622 repo.path=/pub/git/wiz.git
623 repo.desc=the wizard of foo
626 # Add some mirrored repositories
631 repo.path=/pub/git/git.git
636 repo.path=/pub/git/linux.git
639 # Disable adhoc downloads of this repo
642 # Disable line-counts for this repo
643 repo.enable-log-linecount=0
645 # Restrict the max statistics period for this repo
652 Comments currently cannot appear on the same line as a setting; the comment
653 will be included as part of the value. E.g. this line:
655 robots=index # allow indexing
657 will generate the following html element:
659 <meta name='robots' content='index # allow indexing'/>
665 Lars Hjemli <hjemli@gmail.com>
666 Jason A. Donenfeld <Jason@zx2c4.com>
git.ckatri.com / cgit.git / blob