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