cgitrc.5.txt (view raw)
1:man source: cgit
2:man manual: cgit
3
4CGITRC(5)
5========
6
7
8NAME
9----
10cgitrc - runtime configuration for cgit
11
12
13SYNOPSIS
14--------
15Cgitrc contains all runtime settings for cgit, including the list of git
16repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
17lines, and lines starting with '#', are ignored.
18
19
20LOCATION
21--------
22The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
23runtime, cgit will consult the environment variable CGIT_CONFIG and, if
24defined, use its value instead.
25
26
27GLOBAL SETTINGS
28---------------
29about-filter::
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, the name of the file
33 as the first argument, and the STDOUT from the command will be
34 included verbatim on the about page. Default value: none. See
35 also: "FILTER API".
36
37agefile::
38 Specifies a path, relative to each repository path, which can be used
39 to specify the date and time of the youngest commit in the repository.
40 The first line in the file is used as input to the "parse_date"
41 function in libgit. Recommended timestamp-format is "yyyy-mm-dd
42 hh:mm:ss". You may want to generate this file from a post-receive
43 hook. Default value: "info/web/last-modified".
44
45auth-filter::
46 Specifies a command that will be invoked for authenticating repository
47 access. Receives quite a few arguments, and data on both stdin and
48 stdout for authentication processing. Details follow later in this
49 document. If no auth-filter is specified, no authentication is
50 performed. Default value: none. See also: "FILTER API".
51
52branch-sort::
53 Flag which, when set to "age", enables date ordering in the branch ref
54 list, and when set to "name" enables ordering by branch name. Default
55 value: "name".
56
57cache-root::
58 Path used to store the cgit cache entries. Default value:
59 "/var/cache/cgit". See also: "MACRO EXPANSION".
60
61cache-static-ttl::
62 Number which specifies the time-to-live, in minutes, for the cached
63 version of repository pages accessed with a fixed SHA1. Negative
64 values have infinite ttl. Default value: -1".
65
66cache-dynamic-ttl::
67 Number which specifies the time-to-live, in minutes, for the cached
68 version of repository pages accessed without a fixed SHA1. Negative
69 values have infinite ttl. Default value: "5".
70
71cache-repo-ttl::
72 Number which specifies the time-to-live, in minutes, for the cached
73 version of the repository summary page. Negative values have infinite
74 ttl. Default value: "5".
75
76cache-root-ttl::
77 Number which specifies the time-to-live, in minutes, for the cached
78 version of the repository index page. Negative values have infinite
79 ttl. Default value: "5".
80
81cache-scanrc-ttl::
82 Number which specifies the time-to-live, in minutes, for the result
83 of scanning a path for git repositories. Negative values have infinite
84 ttl. Default value: "15".
85
86cache-about-ttl::
87 Number which specifies the time-to-live, in minutes, for the cached
88 version of the repository about page. Negative values have infinite
89 ttl. Default value: "15".
90
91cache-size::
92 The maximum number of entries in the cgit cache. Default value: "0"
93 (i.e. caching is disabled).
94
95case-sensitive-sort::
96 Sort items in the repo list case sensitively. Default value: "1".
97 See also: repository-sort, section-sort.
98
99clone-prefix::
100 Space-separated list of common prefixes which, when combined with a
101 repository url, generates valid clone urls for the repository. This
102 setting is only used if `repo.clone-url` is unspecified. Default value:
103 none.
104
105clone-url::
106 Space-separated list of clone-url templates. This setting is only
107 used if `repo.clone-url` is unspecified. Default value: none. See
108 also: "MACRO EXPANSION", "FILTER API".
109
110commit-filter::
111 Specifies a command which will be invoked to format commit messages.
112 The command will get the message on its STDIN, and the STDOUT from the
113 command will be included verbatim as the commit message, i.e. this can
114 be used to implement bugtracker integration. Default value: none.
115 See also: "FILTER API".
116
117commit-sort::
118 Flag which, when set to "date", enables strict date ordering in the
119 commit log, and when set to "topo" enables strict topological
120 ordering. If unset, the default ordering of "git log" is used. Default
121 value: unset.
122
123css::
124 Url which specifies the css document to include in all cgit pages.
125 Default value: "/cgit.css".
126
127email-filter::
128 Specifies a command which will be invoked to format names and email
129 address of committers, authors, and taggers, as represented in various
130 places throughout the cgit interface. This command will receive an
131 email address and an origin page string as its command line arguments,
132 and the text to format on STDIN. It is to write the formatted text back
133 out onto STDOUT. Default value: none. See also: "FILTER API".
134
135embedded::
136 Flag which, when set to "1", will make cgit generate a html fragment
137 suitable for embedding in other html pages. Default value: none. See
138 also: "noheader".
139
140enable-commit-graph::
141 Flag which, when set to "1", will make cgit print an ASCII-art commit
142 history graph to the left of the commit messages in the repository
143 log page. Default value: "0".
144
145enable-filter-overrides::
146 Flag which, when set to "1", allows all filter settings to be
147 overridden in repository-specific cgitrc files. Default value: none.
148
149enable-http-clone::
150 If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
151 You can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url
152 to expose this feature. If you use an alternate way of serving git
153 repositories, you may wish to disable this. Default value: "1".
154
155enable-index-links::
156 Flag which, when set to "1", will make cgit generate extra links for
157 each repo in the repository index (specifically, to the "summary",
158 "commit" and "tree" pages). Default value: "0".
159
160enable-index-owner::
161 Flag which, when set to "1", will make cgit display the owner of
162 each repo in the repository index. Default value: "1".
163
164enable-log-filecount::
165 Flag which, when set to "1", will make cgit print the number of
166 modified files for each commit on the repository log page. Default
167 value: "0".
168
169enable-log-linecount::
170 Flag which, when set to "1", will make cgit print the number of added
171 and removed lines for each commit on the repository log page. Default
172 value: "0".
173
174enable-remote-branches::
175 Flag which, when set to "1", will make cgit display remote branches
176 in the summary and refs views. Default value: "0". See also:
177 "repo.enable-remote-branches".
178
179enable-subject-links::
180 Flag which, when set to "1", will make cgit use the subject of the
181 parent commit as link text when generating links to parent commits
182 in commit view. Default value: "0". See also:
183 "repo.enable-subject-links".
184
185enable-tree-linenumbers::
186 Flag which, when set to "1", will make cgit generate linenumber links
187 for plaintext blobs printed in the tree view. Default value: "1".
188
189enable-git-config::
190 Flag which, when set to "1", will allow cgit to use git config to set
191 any repo specific settings. This option is used in conjunction with
192 "scan-path", and must be defined prior, to augment repo-specific
193 settings. The keys gitweb.owner, gitweb.category, and gitweb.description
194 will map to the cgit keys repo.owner, repo.section, and repo.desc,
195 respectively. All git config keys that begin with "cgit." will be mapped
196 to the corresponding "repo." key in cgit. Default value: "0". See also:
197 scan-path, section-from-path.
198
199favicon::
200 Url used as link to a shortcut icon for cgit. It is suggested to use
201 the value "/favicon.ico" since certain browsers will ignore other
202 values. Default value: "/favicon.ico".
203
204footer::
205 The content of the file specified with this option will be included
206 verbatim at the bottom of all pages (i.e. it replaces the standard
207 "generated by..." message. Default value: none.
208
209head-include::
210 The content of the file specified with this option will be included
211 verbatim in the html HEAD section on all pages. Default value: none.
212
213header::
214 The content of the file specified with this option will be included
215 verbatim at the top of all pages. Default value: none.
216
217include::
218 Name of a configfile to include before the rest of the current config-
219 file is parsed. Default value: none. See also: "MACRO EXPANSION".
220
221index-header::
222 The content of the file specified with this option will be included
223 verbatim above the repository index. This setting is deprecated, and
224 will not be supported by cgit-1.0 (use root-readme instead). Default
225 value: none.
226
227index-info::
228 The content of the file specified with this option will be included
229 verbatim below the heading on the repository index page. This setting
230 is deprecated, and will not be supported by cgit-1.0 (use root-desc
231 instead). Default value: none.
232
233local-time::
234 Flag which, if set to "1", makes cgit print commit and tag times in the
235 servers timezone. Default value: "0".
236
237logo::
238 Url which specifies the source of an image which will be used as a logo
239 on all cgit pages. Default value: "/cgit.png".
240
241logo-link::
242 Url loaded when clicking on the cgit logo image. If unspecified the
243 calculated url of the repository index page will be used. Default
244 value: none.
245
246max-atom-items::
247 Specifies the number of items to display in atom feeds view. Default
248 value: "10".
249
250max-commit-count::
251 Specifies the number of entries to list per page in "log" view. Default
252 value: "50".
253
254max-message-length::
255 Specifies the maximum number of commit message characters to display in
256 "log" view. Default value: "80".
257
258max-repo-count::
259 Specifies the number of entries to list per page on the repository
260 index page. Default value: "50".
261
262max-repodesc-length::
263 Specifies the maximum number of repo description characters to display
264 on the repository index page. Default value: "80".
265
266max-blob-size::
267 Specifies the maximum size of a blob to display HTML for in KBytes.
268 Default value: "0" (limit disabled).
269
270max-stats::
271 Set the default maximum statistics period. Valid values are "week",
272 "month", "quarter" and "year". If unspecified, statistics are
273 disabled. Default value: none. See also: "repo.max-stats".
274
275mimetype.<ext>::
276 Set the mimetype for the specified filename extension. This is used
277 by the `plain` command when returning blob content.
278
279mimetype-file::
280 Specifies the file to use for automatic mimetype lookup. If specified
281 then this field is used as a fallback when no "mimetype.<ext>" match is
282 found. If unspecified then no such lookup is performed. The typical file
283 to use on a Linux system is /etc/mime.types. The format of the file must
284 comply to:
285 - a comment line is an empty line or a line starting with a hash (#),
286 optionally preceded by whitespace
287 - a non-comment line starts with the mimetype (like image/png), followed
288 by one or more file extensions (like jpg), all separated by whitespace
289 Default value: none. See also: "mimetype.<ext>".
290
291module-link::
292 Text which will be used as the formatstring for a hyperlink when a
293 submodule is printed in a directory listing. The arguments for the
294 formatstring are the path and SHA1 of the submodule commit. Default
295 value: none.
296
297nocache::
298 If set to the value "1" caching will be disabled. This settings is
299 deprecated, and will not be honored starting with cgit-1.0. Default
300 value: "0".
301
302noplainemail::
303 If set to "1" showing full author email addresses will be disabled.
304 Default value: "0".
305
306noheader::
307 Flag which, when set to "1", will make cgit omit the standard header
308 on all pages. Default value: none. See also: "embedded".
309
310project-list::
311 A list of subdirectories inside of scan-path, relative to it, that
312 should loaded as git repositories. This must be defined prior to
313 scan-path. Default value: none. See also: scan-path, "MACRO
314 EXPANSION".
315
316readme::
317 Text which will be used as default value for "repo.readme". Multiple
318 config keys may be specified, and cgit will use the first found file
319 in this list. This is useful in conjunction with scan-path. Default
320 value: none. See also: scan-path, repo.readme.
321
322remove-suffix::
323 If set to "1" and scan-path is enabled, if any repositories are found
324 with a suffix of ".git", this suffix will be removed for the url and
325 name. This must be defined prior to scan-path. Default value: "0".
326 See also: scan-path.
327
328renamelimit::
329 Maximum number of files to consider when detecting renames. The value
330 "-1" uses the compiletime value in git (for further info, look at
331 `man git-diff`). Default value: "-1".
332
333repo.group::
334 Legacy alias for "section". This option is deprecated and will not be
335 supported in cgit-1.0.
336
337repository-sort::
338 The way in which repositories in each section are sorted. Valid values
339 are "name" for sorting by the repo name or "age" for sorting by the
340 most recently updated repository. Default value: "name". See also:
341 section, case-sensitive-sort, section-sort.
342
343robots::
344 Text used as content for the "robots" meta-tag. Default value:
345 "index, nofollow".
346
347root-desc::
348 Text printed below the heading on the repository index page. Default
349 value: "a fast webinterface for the git dscm".
350
351root-readme::
352 The content of the file specified with this option will be included
353 verbatim below the "about" link on the repository index page. Default
354 value: none.
355
356root-title::
357 Text printed as heading on the repository index page. Default value:
358 "Git Repository Browser".
359
360scan-hidden-path::
361 If set to "1" and scan-path is enabled, scan-path will recurse into
362 directories whose name starts with a period ('.'). Otherwise,
363 scan-path will stay away from such directories (considered as
364 "hidden"). Note that this does not apply to the ".git" directory in
365 non-bare repos. This must be defined prior to scan-path.
366 Default value: 0. See also: scan-path.
367
368scan-path::
369 A path which will be scanned for repositories. If caching is enabled,
370 the result will be cached as a cgitrc include-file in the cache
371 directory. If project-list has been defined prior to scan-path,
372 scan-path loads only the directories listed in the file pointed to by
373 project-list. Be advised that only the global settings taken
374 before the scan-path directive will be applied to each repository.
375 Default value: none. See also: cache-scanrc-ttl, project-list,
376 "MACRO EXPANSION".
377
378section::
379 The name of the current repository section - all repositories defined
380 after this option will inherit the current section name. Default value:
381 none.
382
383section-sort::
384 Flag which, when set to "1", will sort the sections on the repository
385 listing by name. Set this flag to "0" if the order in the cgitrc file should
386 be preserved. Default value: "1". See also: section,
387 case-sensitive-sort, repository-sort.
388
389section-from-path::
390 A number which, if defined prior to scan-path, specifies how many
391 path elements from each repo path to use as a default section name.
392 If negative, cgit will discard the specified number of path elements
393 above the repo directory. Default value: "0".
394
395side-by-side-diffs::
396 If set to "1" shows side-by-side diffs instead of unidiffs per
397 default. Default value: "0".
398
399snapshots::
400 Text which specifies the default set of snapshot formats that cgit
401 generates links for. The value is a space-separated list of zero or
402 more of the values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip".
403 Default value: none.
404
405source-filter::
406 Specifies a command which will be invoked to format plaintext blobs
407 in the tree view. The command will get the blob content on its STDIN
408 and the name of the blob as its only command line argument. The STDOUT
409 from the command will be included verbatim as the blob contents, i.e.
410 this can be used to implement e.g. syntax highlighting. Default value:
411 none. See also: "FILTER API".
412
413summary-branches::
414 Specifies the number of branches to display in the repository "summary"
415 view. Default value: "10".
416
417summary-log::
418 Specifies the number of log entries to display in the repository
419 "summary" view. Default value: "10".
420
421summary-tags::
422 Specifies the number of tags to display in the repository "summary"
423 view. Default value: "10".
424
425strict-export::
426 Filename which, if specified, needs to be present within the repository
427 for cgit to allow access to that repository. This can be used to emulate
428 gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
429 repositories to match those exported by git-daemon. This option must
430 be defined prior to scan-path.
431
432virtual-root::
433 Url which, if specified, will be used as root for all cgit links. It
434 will also cause cgit to generate 'virtual urls', i.e. urls like
435 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
436 value: none.
437 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
438 same kind of virtual urls, so this option will probably be deprecated.
439
440
441REPOSITORY SETTINGS
442-------------------
443repo.about-filter::
444 Override the default about-filter. Default value: none. See also:
445 "enable-filter-overrides". See also: "FILTER API".
446
447repo.branch-sort::
448 Flag which, when set to "age", enables date ordering in the branch ref
449 list, and when set to "name" enables ordering by branch name. Default
450 value: "name".
451
452repo.clone-url::
453 A list of space-separated urls which can be used to clone this repo.
454 Default value: none. See also: "MACRO EXPANSION".
455
456repo.commit-filter::
457 Override the default commit-filter. Default value: none. See also:
458 "enable-filter-overrides". See also: "FILTER API".
459
460repo.commit-sort::
461 Flag which, when set to "date", enables strict date ordering in the
462 commit log, and when set to "topo" enables strict topological
463 ordering. If unset, the default ordering of "git log" is used. Default
464 value: unset.
465
466repo.defbranch::
467 The name of the default branch for this repository. If no such branch
468 exists in the repository, the first branch name (when sorted) is used
469 as default instead. Default value: branch pointed to by HEAD, or
470 "master" if there is no suitable HEAD.
471
472repo.desc::
473 The value to show as repository description. Default value: none.
474
475repo.email-filter::
476 Override the default email-filter. Default value: none. See also:
477 "enable-filter-overrides". See also: "FILTER API".
478
479repo.enable-commit-graph::
480 A flag which can be used to disable the global setting
481 `enable-commit-graph'. Default value: none.
482
483repo.enable-log-filecount::
484 A flag which can be used to disable the global setting
485 `enable-log-filecount'. Default value: none.
486
487repo.enable-log-linecount::
488 A flag which can be used to disable the global setting
489 `enable-log-linecount'. Default value: none.
490
491repo.enable-remote-branches::
492 Flag which, when set to "1", will make cgit display remote branches
493 in the summary and refs views. Default value: <enable-remote-branches>.
494
495repo.enable-subject-links::
496 A flag which can be used to override the global setting
497 `enable-subject-links'. Default value: none.
498
499repo.logo::
500 Url which specifies the source of an image which will be used as a logo
501 on this repo's pages. Default value: global logo.
502
503repo.logo-link::
504 Url loaded when clicking on the cgit logo image. If unspecified the
505 calculated url of the repository index page will be used. Default
506 value: global logo-link.
507
508repo.module-link::
509 Text which will be used as the formatstring for a hyperlink when a
510 submodule is printed in a directory listing. The arguments for the
511 formatstring are the path and SHA1 of the submodule commit. Default
512 value: <module-link>
513
514repo.module-link.<path>::
515 Text which will be used as the formatstring for a hyperlink when a
516 submodule with the specified subdirectory path is printed in a
517 directory listing. The only argument for the formatstring is the SHA1
518 of the submodule commit. Default value: none.
519
520repo.max-stats::
521 Override the default maximum statistics period. Valid values are equal
522 to the values specified for the global "max-stats" setting. Default
523 value: none.
524
525repo.name::
526 The value to show as repository name. Default value: <repo.url>.
527
528repo.owner::
529 A value used to identify the owner of the repository. Default value:
530 none.
531
532repo.path::
533 An absolute path to the repository directory. For non-bare repositories
534 this is the .git-directory. Default value: none.
535
536repo.readme::
537 A path (relative to <repo.path>) which specifies a file to include
538 verbatim as the "About" page for this repo. You may also specify a
539 git refspec by head or by hash by prepending the refspec followed by
540 a colon. For example, "master:docs/readme.mkd". If the value begins
541 with a colon, i.e. ":docs/readme.rst", the default branch of the
542 repository will be used. Sharing any file will expose that entire
543 directory tree to the "/about/PATH" endpoints, so be sure that there
544 are no non-public files located in the same directory as the readme
545 file. Default value: <readme>.
546
547repo.snapshots::
548 A mask of snapshot formats for this repo that cgit generates links for,
549 restricted by the global "snapshots" setting. Default value:
550 <snapshots>.
551
552repo.section::
553 Override the current section name for this repository. Default value:
554 none.
555
556repo.source-filter::
557 Override the default source-filter. Default value: none. See also:
558 "enable-filter-overrides". See also: "FILTER API".
559
560repo.url::
561 The relative url used to access the repository. This must be the first
562 setting specified for each repo. Default value: none.
563
564
565REPOSITORY-SPECIFIC CGITRC FILE
566-------------------------------
567When the option "scan-path" is used to auto-discover git repositories, cgit
568will try to parse the file "cgitrc" within any found repository. Such a
569repo-specific config file may contain any of the repo-specific options
570described above, except "repo.url" and "repo.path". Additionally, the "filter"
571options are only acknowledged in repo-specific config files when
572"enable-filter-overrides" is set to "1".
573
574Note: the "repo." prefix is dropped from the option names in repo-specific
575config files, e.g. "repo.desc" becomes "desc".
576
577
578FILTER API
579----------
580By default, filters are separate processes that are executed each time they
581are needed. Alternative technologies may be used by prefixing the filter
582specification with the relevant string; available values are:
583
584'exec:'::
585 The default "one process per filter" mode.
586
587'lua:'::
588 Executes the script using a built-in Lua interpreter. The script is
589 loaded once per execution of cgit, and may be called multiple times
590 during cgit's lifetime, making it a good choice for repeated filters
591 such as the 'email filter'. It responds to three functions:
592
593 'filter_open(argument1, argument2, argument3, ...)'::
594 This is called upon activation of the filter for a particular
595 set of data.
596 'filter_write(buffer)'::
597 This is called whenever cgit writes data to the webpage.
598 'filter_close()'::
599 This is called when the current filtering operation is
600 completed. It must return an integer value. Usually 0
601 indicates success.
602
603 Additionally, cgit exposes to the Lua the following built-in functions:
604
605 'html(str)'::
606 Writes 'str' to the webpage.
607 'html_txt(str)'::
608 HTML escapes and writes 'str' to the webpage.
609 'html_attr(str)'::
610 HTML escapes for an attribute and writes "str' to the webpage.
611 'html_url_path(str)'::
612 URL escapes for a path and writes 'str' to the webpage.
613 'html_url_arg(str)'::
614 URL escapes for an argument and writes 'str' to the webpage.
615 'html_include(file)'::
616 Includes 'file' in webpage.
617
618
619Parameters are provided to filters as follows.
620
621about filter::
622 This filter is given a single parameter: the filename of the source
623 file to filter. The filter can use the filename to determine (for
624 example) the type of syntax to follow when formatting the readme file.
625 The about text that is to be filtered is available on standard input
626 and the filtered text is expected on standard output.
627
628commit filter::
629 This filter is given no arguments. The commit message text that is to
630 be filtered is available on standard input and the filtered text is
631 expected on standard output.
632
633email filter::
634 This filter is given two parameters: the email address of the relevent
635 author and a string indicating the originating page. The filter will
636 then receive the text string to format on standard input and is
637 expected to write to standard output the formatted text to be included
638 in the page.
639
640source filter::
641 This filter is given a single parameter: the filename of the source
642 file to filter. The filter can use the filename to determine (for
643 example) the syntax highlighting mode. The contents of the source
644 file that is to be filtered is available on standard input and the
645 filtered contents is expected on standard output.
646
647auth filter::
648 The authentication filter receives 12 parameters:
649 - filter action, explained below, which specifies which action the
650 filter is called for
651 - http cookie
652 - http method
653 - http referer
654 - http path
655 - http https flag
656 - cgit repo
657 - cgit page
658 - cgit url
659 - cgit login url
660 When the filter action is "body", this filter must write to output the
661 HTML for displaying the login form, which POSTs to the login url. When
662 the filter action is "authenticate-cookie", this filter must validate
663 the http cookie and return a 0 if it is invalid or 1 if it is invalid,
664 in the exit code / close function. If the filter action is
665 "authenticate-post", this filter receives POST'd parameters on
666 standard input, and should write a complete CGI request, preferably
667 with a 302 redirect, and write to output one or more "Set-Cookie"
668 HTTP headers, each followed by a newline.
669
670 Please see `filters/simple-authentication.lua` for a clear example
671 script that may be modified.
672
673
674All filters are handed the following environment variables:
675
676- CGIT_REPO_URL (from repo.url)
677- CGIT_REPO_NAME (from repo.name)
678- CGIT_REPO_PATH (from repo.path)
679- CGIT_REPO_OWNER (from repo.owner)
680- CGIT_REPO_DEFBRANCH (from repo.defbranch)
681- CGIT_REPO_SECTION (from repo.section)
682- CGIT_REPO_CLONE_URL (from repo.clone-url)
683
684If a setting is not defined for a repository and the corresponding global
685setting is also not defined (if applicable), then the corresponding
686environment variable will be unset.
687
688
689MACRO EXPANSION
690---------------
691The following cgitrc options support a simple macro expansion feature,
692where tokens prefixed with "$" are replaced with the value of a similarly
693named environment variable:
694
695- cache-root
696- include
697- project-list
698- scan-path
699
700Macro expansion will also happen on the content of $CGIT_CONFIG, if
701defined.
702
703One usage of this feature is virtual hosting, which in its simplest form
704can be accomplished by adding the following line to /etc/cgitrc:
705
706 include=/etc/cgitrc.d/$HTTP_HOST
707
708The following options are expanded during request processing, and support
709the environment variables defined in "FILTER API":
710
711- clone-url
712- repo.clone-url
713
714
715EXAMPLE CGITRC FILE
716-------------------
717
718....
719# Enable caching of up to 1000 output entries
720cache-size=1000
721
722
723# Specify some default clone urls using macro expansion
724clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
725
726# Specify the css url
727css=/css/cgit.css
728
729
730# Show owner on index page
731enable-index-owner=1
732
733
734# Allow http transport git clone
735enable-http-clone=1
736
737
738# Show extra links for each repository on the index page
739enable-index-links=1
740
741
742# Enable ASCII art commit history graph on the log pages
743enable-commit-graph=1
744
745
746# Show number of affected files per commit on the log pages
747enable-log-filecount=1
748
749
750# Show number of added/removed lines per commit on the log pages
751enable-log-linecount=1
752
753
754# Sort branches by date
755branch-sort=age
756
757
758# Add a cgit favicon
759favicon=/favicon.ico
760
761
762# Use a custom logo
763logo=/img/mylogo.png
764
765
766# Enable statistics per week, month and quarter
767max-stats=quarter
768
769
770# Set the title and heading of the repository index page
771root-title=example.com git repositories
772
773
774# Set a subheading for the repository index page
775root-desc=tracking the foobar development
776
777
778# Include some more info about example.com on the index page
779root-readme=/var/www/htdocs/about.html
780
781
782# Allow download of tar.gz, tar.bz2 and zip-files
783snapshots=tar.gz tar.bz2 zip
784
785
786##
787## List of common mimetypes
788##
789
790mimetype.gif=image/gif
791mimetype.html=text/html
792mimetype.jpg=image/jpeg
793mimetype.jpeg=image/jpeg
794mimetype.pdf=application/pdf
795mimetype.png=image/png
796mimetype.svg=image/svg+xml
797
798
799# Highlight source code with python pygments-based highlighter
800source-filter=/var/www/cgit/filters/syntax-highlighting.py
801
802# Format markdown, restructuredtext, manpages, text files, and html files
803# through the right converters
804about-filter=/var/www/cgit/filters/about-formatting.sh
805
806##
807## Search for these files in the root of the default branch of repositories
808## for coming up with the about page:
809##
810readme=:README.md
811readme=:readme.md
812readme=:README.mkd
813readme=:readme.mkd
814readme=:README.rst
815readme=:readme.rst
816readme=:README.html
817readme=:readme.html
818readme=:README.htm
819readme=:readme.htm
820readme=:README.txt
821readme=:readme.txt
822readme=:README
823readme=:readme
824readme=:INSTALL.md
825readme=:install.md
826readme=:INSTALL.mkd
827readme=:install.mkd
828readme=:INSTALL.rst
829readme=:install.rst
830readme=:INSTALL.html
831readme=:install.html
832readme=:INSTALL.htm
833readme=:install.htm
834readme=:INSTALL.txt
835readme=:install.txt
836readme=:INSTALL
837readme=:install
838
839
840##
841## List of repositories.
842## PS: Any repositories listed when section is unset will not be
843## displayed under a section heading
844## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
845## and included like this:
846## include=/etc/cgitrepos
847##
848
849
850repo.url=foo
851repo.path=/pub/git/foo.git
852repo.desc=the master foo repository
853repo.owner=fooman@example.com
854repo.readme=info/web/about.html
855
856
857repo.url=bar
858repo.path=/pub/git/bar.git
859repo.desc=the bars for your foo
860repo.owner=barman@example.com
861repo.readme=info/web/about.html
862
863
864# The next repositories will be displayed under the 'extras' heading
865section=extras
866
867
868repo.url=baz
869repo.path=/pub/git/baz.git
870repo.desc=a set of extensions for bar users
871
872repo.url=wiz
873repo.path=/pub/git/wiz.git
874repo.desc=the wizard of foo
875
876
877# Add some mirrored repositories
878section=mirrors
879
880
881repo.url=git
882repo.path=/pub/git/git.git
883repo.desc=the dscm
884
885
886repo.url=linux
887repo.path=/pub/git/linux.git
888repo.desc=the kernel
889
890# Disable adhoc downloads of this repo
891repo.snapshots=0
892
893# Disable line-counts for this repo
894repo.enable-log-linecount=0
895
896# Restrict the max statistics period for this repo
897repo.max-stats=month
898....
899
900
901BUGS
902----
903Comments currently cannot appear on the same line as a setting; the comment
904will be included as part of the value. E.g. this line:
905
906 robots=index # allow indexing
907
908will generate the following html element:
909
910 <meta name='robots' content='index # allow indexing'/>
911
912
913
914AUTHOR
915------
916Lars Hjemli <hjemli@gmail.com>
917Jason A. Donenfeld <Jason@zx2c4.com>