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