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" Default value: <readme>.
509
510repo.snapshots::
511	A mask of allowed snapshot-formats for this repo, restricted by the
512	"snapshots" global setting. Default value: <snapshots>.
513
514repo.section::
515	Override the current section name for this repository. Default value:
516	none.
517
518repo.source-filter::
519	Override the default source-filter. Default value: none. See also:
520	"enable-filter-overrides". See also: "FILTER API".
521
522repo.url::
523	The relative url used to access the repository. This must be the first
524	setting specified for each repo. Default value: none.
525
526
527REPOSITORY-SPECIFIC CGITRC FILE
528-------------------------------
529When the option "scan-path" is used to auto-discover git repositories, cgit
530will try to parse the file "cgitrc" within any found repository. Such a
531repo-specific config file may contain any of the repo-specific options
532described above, except "repo.url" and "repo.path". Additionally, the "filter"
533options are only acknowledged in repo-specific config files when
534"enable-filter-overrides" is set to "1".
535
536Note: the "repo." prefix is dropped from the option names in repo-specific
537config files, e.g. "repo.desc" becomes "desc".
538
539
540FILTER API
541----------
542about filter::
543	This filter is given no arguments. The about text that is to be
544	filtered is available on standard input and the filtered text is
545	expected on standard output.
546
547commit filter::
548	This filter is given no arguments. The commit message text that is to
549	be filtered is available on standard input and the filtered text is
550	expected on standard output.
551
552source filter::
553	This filter is given a single parameter: the filename of the source
554	file to filter. The filter can use the filename to determine (for
555	example) the syntax highlighting mode. The contents of the source
556	file that is to be filtered is available on standard input and the
557	filtered contents is expected on standard output.
558
559Also, all filters are handed the following environment variables:
560
561- CGIT_REPO_URL (from repo.url)
562- CGIT_REPO_NAME (from repo.name)
563- CGIT_REPO_PATH (from repo.path)
564- CGIT_REPO_OWNER (from repo.owner)
565- CGIT_REPO_DEFBRANCH (from repo.defbranch)
566- CGIT_REPO_SECTION (from repo.section)
567- CGIT_REPO_CLONE_URL (from repo.clone-url)
568
569If a setting is not defined for a repository and the corresponding global
570setting is also not defined (if applicable), then the corresponding
571environment variable will be unset.
572
573
574MACRO EXPANSION
575---------------
576The following cgitrc options supports a simple macro expansion feature,
577where tokens prefixed with "$" are replaced with the value of a similary
578named environment variable:
579
580- cache-root
581- include
582- project-list
583- scan-path
584
585Macro expansion will also happen on the content of $CGIT_CONFIG, if
586defined.
587
588One usage of this feature is virtual hosting, which in its simplest form
589can be accomplished by adding the following line to /etc/cgitrc:
590
591	include=/etc/cgitrc.d/$HTTP_HOST
592
593The following options are expanded during request processing, and support
594the environment variables defined in "FILTER API":
595
596- clone-url
597- repo.clone-url
598
599
600EXAMPLE CGITRC FILE
601-------------------
602
603....
604# Enable caching of up to 1000 output entriess
605cache-size=1000
606
607
608# Specify some default clone urls using macro expansion
609clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
610
611# Specify the css url
612css=/css/cgit.css
613
614
615# Show extra links for each repository on the index page
616enable-index-links=1
617
618
619# Enable ASCII art commit history graph on the log pages
620enable-commit-graph=1
621
622
623# Show number of affected files per commit on the log pages
624enable-log-filecount=1
625
626
627# Show number of added/removed lines per commit on the log pages
628enable-log-linecount=1
629
630
631# Add a cgit favicon
632favicon=/favicon.ico
633
634
635# Use a custom logo
636logo=/img/mylogo.png
637
638
639# Enable statistics per week, month and quarter
640max-stats=quarter
641
642
643# Set the title and heading of the repository index page
644root-title=example.com git repositories
645
646
647# Set a subheading for the repository index page
648root-desc=tracking the foobar development
649
650
651# Include some more info about example.com on the index page
652root-readme=/var/www/htdocs/about.html
653
654
655# Allow download of tar.gz, tar.bz2 and zip-files
656snapshots=tar.gz tar.bz2 zip
657
658
659##
660## List of common mimetypes
661##
662
663mimetype.gif=image/gif
664mimetype.html=text/html
665mimetype.jpg=image/jpeg
666mimetype.jpeg=image/jpeg
667mimetype.pdf=application/pdf
668mimetype.png=image/png
669mimetype.svg=image/svg+xml
670
671
672##
673## List of repositories.
674## PS: Any repositories listed when section is unset will not be
675##     displayed under a section heading
676## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
677##      and included like this:
678##        include=/etc/cgitrepos
679##
680
681
682repo.url=foo
683repo.path=/pub/git/foo.git
684repo.desc=the master foo repository
685repo.owner=fooman@example.com
686repo.readme=info/web/about.html
687
688
689repo.url=bar
690repo.path=/pub/git/bar.git
691repo.desc=the bars for your foo
692repo.owner=barman@example.com
693repo.readme=info/web/about.html
694
695
696# The next repositories will be displayed under the 'extras' heading
697section=extras
698
699
700repo.url=baz
701repo.path=/pub/git/baz.git
702repo.desc=a set of extensions for bar users
703
704repo.url=wiz
705repo.path=/pub/git/wiz.git
706repo.desc=the wizard of foo
707
708
709# Add some mirrored repositories
710section=mirrors
711
712
713repo.url=git
714repo.path=/pub/git/git.git
715repo.desc=the dscm
716
717
718repo.url=linux
719repo.path=/pub/git/linux.git
720repo.desc=the kernel
721
722# Disable adhoc downloads of this repo
723repo.snapshots=0
724
725# Disable line-counts for this repo
726repo.enable-log-linecount=0
727
728# Restrict the max statistics period for this repo
729repo.max-stats=month
730....
731
732
733BUGS
734----
735Comments currently cannot appear on the same line as a setting; the comment
736will be included as part of the value. E.g. this line:
737
738	robots=index  # allow indexing
739
740will generate the following html element:
741
742	<meta name='robots' content='index  # allow indexing'/>
743
744
745
746AUTHOR
747------
748Lars Hjemli <hjemli@gmail.com>
749Jason A. Donenfeld <Jason@zx2c4.com>