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