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