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