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, and the STDOUT from the
33 command will be included verbatim on the about page. Default value:
34 none. See also: "FILTER API".
35
36agefile::
37 Specifies a path, relative to each repository path, which can be used
38 to specify the date and time of the youngest commit in the repository.
39 The first line in the file is used as input to the "parse_date"
40 function in libgit. Recommended timestamp-format is "yyyy-mm-dd
41 hh:mm:ss". Default value: "info/web/last-modified".
42
43cache-root::
44 Path used to store the cgit cache entries. Default value:
45 "/var/cache/cgit". See also: "MACRO EXPANSION".
46
47cache-dynamic-ttl::
48 Number which specifies the time-to-live, in minutes, for the cached
49 version of repository pages accessed without a fixed SHA1. Default
50 value: "5".
51
52cache-repo-ttl::
53 Number which specifies the time-to-live, in minutes, for the cached
54 version of the repository summary page. Default value: "5".
55
56cache-root-ttl::
57 Number which specifies the time-to-live, in minutes, for the cached
58 version of the repository index page. Default value: "5".
59
60cache-scanrc-ttl::
61 Number which specifies the time-to-live, in minutes, for the result
62 of scanning a path for git repositories. Default value: "15".
63
64cache-size::
65 The maximum number of entries in the cgit cache. Default value: "0"
66 (i.e. caching is disabled).
67
68cache-static-ttl::
69 Number which specifies the time-to-live, in minutes, for the cached
70 version of repository pages accessed with a fixed SHA1. Default value:
71 "5".
72
73clone-prefix::
74 Space-separated list of common prefixes which, when combined with a
75 repository url, generates valid clone urls for the repository. This
76 setting is only used if `repo.clone-url` is unspecified. Default value:
77 none.
78
79clone-url::
80 Space-separated list of clone-url templates. This setting is only
81 used if `repo.clone-url` is unspecified. Default value: none. See
82 also: "MACRO EXPANSION", "FILTER API".
83
84commit-filter::
85 Specifies a command which will be invoked to format commit messages.
86 The command will get the message on its STDIN, and the STDOUT from the
87 command will be included verbatim as the commit message, i.e. this can
88 be used to implement bugtracker integration. Default value: none.
89 See also: "FILTER API".
90
91css::
92 Url which specifies the css document to include in all cgit pages.
93 Default value: "/cgit.css".
94
95embedded::
96 Flag which, when set to "1", will make cgit generate a html fragment
97 suitable for embedding in other html pages. Default value: none. See
98 also: "noheader".
99
100enable-commit-graph::
101 Flag which, when set to "1", will make cgit print an ASCII-art commit
102 history graph to the left of the commit messages in the repository
103 log page. Default value: "0".
104
105enable-filter-overrides::
106 Flag which, when set to "1", allows all filter settings to be
107 overridden in repository-specific cgitrc files. Default value: none.
108
109enable-gitweb-desc::
110 If set to "1" and scan-path is enabled, we first check each repository
111 for the git config value "gitweb.description" to determine the owner.
112 Otherwise, the description is read from a file titled "description"
113 inside of the repository directory.
114 Default value: "1". See also: scan-path.
115
116enable-gitweb-owner::
117 If set to "1" and scan-path is enabled, we first check each repository
118 for the git config value "gitweb.owner" to determine the owner.
119 Default value: "1". See also: scan-path.
120
121enable-http-clone::
122 If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
123 If you use an alternate way of serving git repositories, you may wish
124 to disable this. Default value: "1".
125
126enable-index-links::
127 Flag which, when set to "1", will make cgit generate extra links for
128 each repo in the repository index (specifically, to the "summary",
129 "commit" and "tree" pages). Default value: "0".
130
131enable-log-filecount::
132 Flag which, when set to "1", will make cgit print the number of
133 modified files for each commit on the repository log page. Default
134 value: "0".
135
136enable-log-linecount::
137 Flag which, when set to "1", will make cgit print the number of added
138 and removed lines for each commit on the repository log page. Default
139 value: "0".
140
141enable-remote-branches::
142 Flag which, when set to "1", will make cgit display remote branches
143 in the summary and refs views. Default value: "0". See also:
144 "repo.enable-remote-branches".
145
146enable-subject-links::
147 Flag which, when set to "1", will make cgit use the subject of the
148 parent commit as link text when generating links to parent commits
149 in commit view. Default value: "0". See also:
150 "repo.enable-subject-links".
151
152enable-tree-linenumbers::
153 Flag which, when set to "1", will make cgit generate linenumber links
154 for plaintext blobs printed in the tree view. Default value: "1".
155
156favicon::
157 Url used as link to a shortcut icon for cgit. If specified, it is
158 suggested to use the value "/favicon.ico" since certain browsers will
159 ignore other values. Default value: none.
160
161footer::
162 The content of the file specified with this option will be included
163 verbatim at the bottom of all pages (i.e. it replaces the standard
164 "generated by..." message. Default value: none.
165
166head-include::
167 The content of the file specified with this option will be included
168 verbatim in the html HEAD section on all pages. Default value: none.
169
170header::
171 The content of the file specified with this option will be included
172 verbatim at the top of all pages. Default value: none.
173
174include::
175 Name of a configfile to include before the rest of the current config-
176 file is parsed. Default value: none. See also: "MACRO EXPANSION".
177
178index-header::
179 The content of the file specified with this option will be included
180 verbatim above the repository index. This setting is deprecated, and
181 will not be supported by cgit-1.0 (use root-readme instead). Default
182 value: none.
183
184index-info::
185 The content of the file specified with this option will be included
186 verbatim below the heading on the repository index page. This setting
187 is deprecated, and will not be supported by cgit-1.0 (use root-desc
188 instead). Default value: none.
189
190local-time::
191 Flag which, if set to "1", makes cgit print commit and tag times in the
192 servers timezone. Default value: "0".
193
194logo::
195 Url which specifies the source of an image which will be used as a logo
196 on all cgit pages. Default value: "/cgit.png".
197
198logo-link::
199 Url loaded when clicking on the cgit logo image. If unspecified the
200 calculated url of the repository index page will be used. Default
201 value: none.
202
203max-atom-items::
204 Specifies the number of items to display in atom feeds view. Default
205 value: "10".
206
207max-commit-count::
208 Specifies the number of entries to list per page in "log" view. Default
209 value: "50".
210
211max-message-length::
212 Specifies the maximum number of commit message characters to display in
213 "log" view. Default value: "80".
214
215max-repo-count::
216 Specifies the number of entries to list per page on the repository
217 index page. Default value: "50".
218
219max-repodesc-length::
220 Specifies the maximum number of repo description characters to display
221 on the repository index page. Default value: "80".
222
223max-blob-size::
224 Specifies the maximum size of a blob to display HTML for in KBytes.
225 Default value: "0" (limit disabled).
226
227max-stats::
228 Set the default maximum statistics period. Valid values are "week",
229 "month", "quarter" and "year". If unspecified, statistics are
230 disabled. Default value: none. See also: "repo.max-stats".
231
232mimetype.<ext>::
233 Set the mimetype for the specified filename extension. This is used
234 by the `plain` command when returning blob content.
235
236mimetype-file::
237 Specifies the file to use for automatic mimetype lookup. If specified
238 then this field is used as a fallback when no "mimetype.<ext>" match is
239 found. If unspecified then no such lookup is performed. The typical file
240 to use on a Linux system is /etc/mime.types. Default value: none. See
241 also: "mimetype.<ext>". The format of the file must comply to:
242 - a comment line is an empty line or a line starting with a hash (#),
243 optionally preceded by whitespace
244 - a non-comment line starts with the mimetype (like image/png), followed
245 by one or more file extensions (like jpg), all separated by whitespace
246
247module-link::
248 Text which will be used as the formatstring for a hyperlink when a
249 submodule is printed in a directory listing. The arguments for the
250 formatstring are the path and SHA1 of the submodule commit. Default
251 value: none.
252
253nocache::
254 If set to the value "1" caching will be disabled. This settings is
255 deprecated, and will not be honored starting with cgit-1.0. Default
256 value: "0".
257
258noplainemail::
259 If set to "1" showing full author email adresses will be disabled.
260 Default value: "0".
261
262noheader::
263 Flag which, when set to "1", will make cgit omit the standard header
264 on all pages. Default value: none. See also: "embedded".
265
266project-list::
267 A list of subdirectories inside of scan-path, relative to it, that
268 should loaded as git repositories. This must be defined prior to
269 scan-path. Default value: none. See also: scan-path, "MACRO
270 EXPANSION".
271
272readme::
273 Text which will be used as default value for "repo.readme". Default
274 value: none.
275
276remove-suffix::
277 If set to "1" and scan-path is enabled, if any repositories are found
278 with a suffix of ".git", this suffix will be removed for the url and
279 name. Default value: "0". See also: scan-path.
280
281renamelimit::
282 Maximum number of files to consider when detecting renames. The value
283 "-1" uses the compiletime value in git (for further info, look at
284 `man git-diff`). Default value: "-1".
285
286repo.group::
287 Legacy alias for "section". This option is deprecated and will not be
288 supported in cgit-1.0.
289
290robots::
291 Text used as content for the "robots" meta-tag. Default value:
292 "index, nofollow".
293
294root-desc::
295 Text printed below the heading on the repository index page. Default
296 value: "a fast webinterface for the git dscm".
297
298root-readme::
299 The content of the file specified with this option will be included
300 verbatim below the "about" link on the repository index page. Default
301 value: none.
302
303root-title::
304 Text printed as heading on the repository index page. Default value:
305 "Git Repository Browser".
306
307scan-hidden-path::
308 If set to "1" and scan-path is enabled, scan-path will recurse into
309 directories whose name starts with a period ('.'). Otherwise,
310 scan-path will stay away from such directories (considered as
311 "hidden"). Note that this does not apply to the ".git" directory in
312 non-bare repos. This must be defined prior to scan-path.
313 Default value: 0. See also: scan-path.
314
315scan-path::
316 A path which will be scanned for repositories. If caching is enabled,
317 the result will be cached as a cgitrc include-file in the cache
318 directory. If project-list has been defined prior to scan-path,
319 scan-path loads only the directories listed in the file pointed to by
320 project-list. Be advised that only the global settings taken
321 before the scan-path directive will be applied to each repository.
322 Default value: none. See also: cache-scanrc-ttl, project-list,
323 "MACRO EXPANSION".
324
325section::
326 The name of the current repository section - all repositories defined
327 after this option will inherit the current section name. Default value:
328 none.
329
330section-from-path::
331 A number which, if specified before scan-path, specifies how many
332 path elements from each repo path to use as a default section name.
333 If negative, cgit will discard the specified number of path elements
334 above the repo directory. Default value: 0.
335
336side-by-side-diffs::
337 If set to "1" shows side-by-side diffs instead of unidiffs per
338 default. Default value: "0".
339
340snapshots::
341 Text which specifies the default set of snapshot formats generated by
342 cgit. The value is a space-separated list of zero or more of the
343 values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
344 none.
345
346source-filter::
347 Specifies a command which will be invoked to format plaintext blobs
348 in the tree view. The command will get the blob content on its STDIN
349 and the name of the blob as its only command line argument. The STDOUT
350 from the command will be included verbatim as the blob contents, i.e.
351 this can be used to implement e.g. syntax highlighting. Default value:
352 none. See also: "FILTER API".
353
354summary-branches::
355 Specifies the number of branches to display in the repository "summary"
356 view. Default value: "10".
357
358summary-log::
359 Specifies the number of log entries to display in the repository
360 "summary" view. Default value: "10".
361
362summary-tags::
363 Specifies the number of tags to display in the repository "summary"
364 view. Default value: "10".
365
366strict-export::
367 Filename which, if specified, needs to be present within the repository
368 for cgit to allow access to that repository. This can be used to emulate
369 gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
370 repositories to match those exported by git-daemon. This option MUST come
371 before 'scan-path'.
372
373virtual-root::
374 Url which, if specified, will be used as root for all cgit links. It
375 will also cause cgit to generate 'virtual urls', i.e. urls like
376 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
377 value: none.
378 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
379 same kind of virtual urls, so this option will probably be deprecated.
380
381REPOSITORY SETTINGS
382-------------------
383repo.about-filter::
384 Override the default about-filter. Default value: none. See also:
385 "enable-filter-overrides". See also: "FILTER API".
386
387repo.clone-url::
388 A list of space-separated urls which can be used to clone this repo.
389 Default value: none. See also: "MACRO EXPANSION".
390
391repo.commit-filter::
392 Override the default commit-filter. Default value: none. See also:
393 "enable-filter-overrides". See also: "FILTER API".
394
395repo.defbranch::
396 The name of the default branch for this repository. If no such branch
397 exists in the repository, the first branch name (when sorted) is used
398 as default instead. Default value: branch pointed to by HEAD, or
399 "master" if there is no suitable HEAD.
400
401repo.desc::
402 The value to show as repository description. Default value: none.
403
404repo.enable-commit-graph::
405 A flag which can be used to disable the global setting
406 `enable-commit-graph'. Default value: none.
407
408repo.enable-log-filecount::
409 A flag which can be used to disable the global setting
410 `enable-log-filecount'. Default value: none.
411
412repo.enable-log-linecount::
413 A flag which can be used to disable the global setting
414 `enable-log-linecount'. Default value: none.
415
416repo.enable-remote-branches::
417 Flag which, when set to "1", will make cgit display remote branches
418 in the summary and refs views. Default value: <enable-remote-branches>.
419
420repo.enable-subject-links::
421 A flag which can be used to override the global setting
422 `enable-subject-links'. Default value: none.
423
424repo.logo::
425 Url which specifies the source of an image which will be used as a logo
426 on this repo's pages. Default value: global logo.
427
428repo.logo-link::
429 Url loaded when clicking on the cgit logo image. If unspecified the
430 calculated url of the repository index page will be used. Default
431 value: global logo-link.
432
433repo.module-link::
434 Text which will be used as the formatstring for a hyperlink when a
435 submodule is printed in a directory listing. The arguments for the
436 formatstring are the path and SHA1 of the submodule commit. Default
437 value: <module-link>
438
439repo.module-link.<path>::
440 Text which will be used as the formatstring for a hyperlink when a
441 submodule with the specified subdirectory path is printed in a
442 directory listing. The only argument for the formatstring is the SHA1
443 of the submodule commit. Default value: none.
444
445repo.max-stats::
446 Override the default maximum statistics period. Valid values are equal
447 to the values specified for the global "max-stats" setting. Default
448 value: none.
449
450repo.name::
451 The value to show as repository name. Default value: <repo.url>.
452
453repo.owner::
454 A value used to identify the owner of the repository. Default value:
455 none.
456
457repo.path::
458 An absolute path to the repository directory. For non-bare repositories
459 this is the .git-directory. Default value: none.
460
461repo.readme::
462 A path (relative to <repo.path>) which specifies a file to include
463 verbatim as the "About" page for this repo. You may also specify a
464 git refspec by head or by hash by prepending the refspec followed by
465 a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
466
467repo.snapshots::
468 A mask of allowed snapshot-formats for this repo, restricted by the
469 "snapshots" global setting. Default value: <snapshots>.
470
471repo.section::
472 Override the current section name for this repository. Default value:
473 none.
474
475repo.source-filter::
476 Override the default source-filter. Default value: none. See also:
477 "enable-filter-overrides". See also: "FILTER API".
478
479repo.url::
480 The relative url used to access the repository. This must be the first
481 setting specified for each repo. Default value: none.
482
483
484REPOSITORY-SPECIFIC CGITRC FILE
485-------------------------------
486When the option "scan-path" is used to auto-discover git repositories, cgit
487will try to parse the file "cgitrc" within any found repository. Such a
488repo-specific config file may contain any of the repo-specific options
489described above, except "repo.url" and "repo.path". Additionally, the "filter"
490options are only acknowledged in repo-specific config files when
491"enable-filter-overrides" is set to "1".
492
493Note: the "repo." prefix is dropped from the option names in repo-specific
494config files, e.g. "repo.desc" becomes "desc".
495
496
497FILTER API
498----------
499about filter::
500 This filter is given no arguments. The about text that is to be
501 filtered is available on standard input and the filtered text is
502 expected on standard output.
503
504commit filter::
505 This filter is given no arguments. The commit message text that is to
506 be filtered is available on standard input and the filtered text is
507 expected on standard output.
508
509source filter::
510 This filter is given a single parameter: the filename of the source
511 file to filter. The filter can use the filename to determine (for
512 example) the syntax highlighting mode. The contents of the source
513 file that is to be filtered is available on standard input and the
514 filtered contents is expected on standard output.
515
516Also, all filters are handed the following environment variables:
517
518- CGIT_REPO_URL (from repo.url)
519- CGIT_REPO_NAME (from repo.name)
520- CGIT_REPO_PATH (from repo.path)
521- CGIT_REPO_OWNER (from repo.owner)
522- CGIT_REPO_DEFBRANCH (from repo.defbranch)
523- CGIT_REPO_SECTION (from repo.section)
524- CGIT_REPO_CLONE_URL (from repo.clone-url)
525
526If a setting is not defined for a repository and the corresponding global
527setting is also not defined (if applicable), then the corresponding
528environment variable will be unset.
529
530
531MACRO EXPANSION
532---------------
533The following cgitrc options supports a simple macro expansion feature,
534where tokens prefixed with "$" are replaced with the value of a similary
535named environment variable:
536
537- cache-root
538- include
539- project-list
540- scan-path
541
542Macro expansion will also happen on the content of $CGIT_CONFIG, if
543defined.
544
545One usage of this feature is virtual hosting, which in its simplest form
546can be accomplished by adding the following line to /etc/cgitrc:
547
548 include=/etc/cgitrc.d/$HTTP_HOST
549
550The following options are expanded during request processing, and support
551the environment variables defined in "FILTER API":
552
553- clone-url
554- repo.clone-url
555
556
557EXAMPLE CGITRC FILE
558-------------------
559
560....
561# Enable caching of up to 1000 output entriess
562cache-size=1000
563
564
565# Specify some default clone urls using macro expansion
566clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
567
568# Specify the css url
569css=/css/cgit.css
570
571
572# Show extra links for each repository on the index page
573enable-index-links=1
574
575
576# Enable ASCII art commit history graph on the log pages
577enable-commit-graph=1
578
579
580# Show number of affected files per commit on the log pages
581enable-log-filecount=1
582
583
584# Show number of added/removed lines per commit on the log pages
585enable-log-linecount=1
586
587
588# Add a cgit favicon
589favicon=/favicon.ico
590
591
592# Use a custom logo
593logo=/img/mylogo.png
594
595
596# Enable statistics per week, month and quarter
597max-stats=quarter
598
599
600# Set the title and heading of the repository index page
601root-title=example.com git repositories
602
603
604# Set a subheading for the repository index page
605root-desc=tracking the foobar development
606
607
608# Include some more info about example.com on the index page
609root-readme=/var/www/htdocs/about.html
610
611
612# Allow download of tar.gz, tar.bz2 and zip-files
613snapshots=tar.gz tar.bz2 zip
614
615
616##
617## List of common mimetypes
618##
619
620mimetype.gif=image/gif
621mimetype.html=text/html
622mimetype.jpg=image/jpeg
623mimetype.jpeg=image/jpeg
624mimetype.pdf=application/pdf
625mimetype.png=image/png
626mimetype.svg=image/svg+xml
627
628
629##
630## List of repositories.
631## PS: Any repositories listed when section is unset will not be
632## displayed under a section heading
633## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
634## and included like this:
635## include=/etc/cgitrepos
636##
637
638
639repo.url=foo
640repo.path=/pub/git/foo.git
641repo.desc=the master foo repository
642repo.owner=fooman@example.com
643repo.readme=info/web/about.html
644
645
646repo.url=bar
647repo.path=/pub/git/bar.git
648repo.desc=the bars for your foo
649repo.owner=barman@example.com
650repo.readme=info/web/about.html
651
652
653# The next repositories will be displayed under the 'extras' heading
654section=extras
655
656
657repo.url=baz
658repo.path=/pub/git/baz.git
659repo.desc=a set of extensions for bar users
660
661repo.url=wiz
662repo.path=/pub/git/wiz.git
663repo.desc=the wizard of foo
664
665
666# Add some mirrored repositories
667section=mirrors
668
669
670repo.url=git
671repo.path=/pub/git/git.git
672repo.desc=the dscm
673
674
675repo.url=linux
676repo.path=/pub/git/linux.git
677repo.desc=the kernel
678
679# Disable adhoc downloads of this repo
680repo.snapshots=0
681
682# Disable line-counts for this repo
683repo.enable-log-linecount=0
684
685# Restrict the max statistics period for this repo
686repo.max-stats=month
687....
688
689
690BUGS
691----
692Comments currently cannot appear on the same line as a setting; the comment
693will be included as part of the value. E.g. this line:
694
695 robots=index # allow indexing
696
697will generate the following html element:
698
699 <meta name='robots' content='index # allow indexing'/>
700
701
702
703AUTHOR
704------
705Lars Hjemli <hjemli@gmail.com>
706Jason A. Donenfeld <Jason@zx2c4.com>