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