1CGITRC(5)                            cgit                            CGITRC(5)
2
3
4

NAME

6       cgitrc - runtime configuration for cgit
7

SYNOPSIS

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

LOCATION

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

GLOBAL SETTINGS

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

REPOSITORY SETTINGS

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

REPOSITORY-SPECIFIC CGITRC FILE

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

FILTER API

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

MACRO EXPANSION

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

CACHE

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

SIGNATURES

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

EXAMPLE CGITRC FILE

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

BUGS

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

AUTHOR

1017       Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com>
1018
1019
1020
1021cgit                              07/19/2023                         CGITRC(5)
Impressum