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