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