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