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