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