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.
 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.
336
337section-from-path::
338	A number which, if specified before scan-path, specifies how many
339	path elements from each repo path to use as a default section name.
340	If negative, cgit will discard the specified number of path elements
341	above the repo directory. Default value: "0".
342
343side-by-side-diffs::
344	If set to "1" shows side-by-side diffs instead of unidiffs per
345	default. Default value: "0".
346
347snapshots::
348	Text which specifies the default set of snapshot formats generated by
349	cgit. The value is a space-separated list of zero or more of the
350	values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
351	none.
352
353source-filter::
354	Specifies a command which will be invoked to format plaintext blobs
355	in the tree view. The command will get the blob content on its STDIN
356	and the name of the blob as its only command line argument. The STDOUT
357	from the command will be included verbatim as the blob contents, i.e.
358	this can be used to implement e.g. syntax highlighting. Default value:
359	none. See also: "FILTER API".
360
361summary-branches::
362	Specifies the number of branches to display in the repository "summary"
363	view. Default value: "10".
364
365summary-log::
366	Specifies the number of log entries to display in the repository
367	"summary" view. Default value: "10".
368
369summary-tags::
370	Specifies the number of tags to display in the repository "summary"
371	view. Default value: "10".
372
373strict-export::
374	Filename which, if specified, needs to be present within the repository
375	for cgit to allow access to that repository. This can be used to emulate
376	gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
377	repositories to match those exported by git-daemon. This option MUST come
378	before 'scan-path'.
379
380virtual-root::
381	Url which, if specified, will be used as root for all cgit links. It
382	will also cause cgit to generate 'virtual urls', i.e. urls like
383	'/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
384	value: none.
385	NOTE: cgit has recently learned how to use PATH_INFO to achieve the
386	same kind of virtual urls, so this option will probably be deprecated.
387
388
389REPOSITORY SETTINGS
390-------------------
391repo.about-filter::
392	Override the default about-filter. Default value: none. See also:
393	"enable-filter-overrides". See also: "FILTER API".
394
395repo.clone-url::
396	A list of space-separated urls which can be used to clone this repo.
397	Default value: none. See also: "MACRO EXPANSION".
398
399repo.commit-filter::
400	Override the default commit-filter. Default value: none. See also:
401	"enable-filter-overrides". See also: "FILTER API".
402
403repo.defbranch::
404	The name of the default branch for this repository. If no such branch
405	exists in the repository, the first branch name (when sorted) is used
406	as default instead. Default value: branch pointed to by HEAD, or
407	"master" if there is no suitable HEAD.
408
409repo.desc::
410	The value to show as repository description. Default value: none.
411
412repo.enable-commit-graph::
413	A flag which can be used to disable the global setting
414	`enable-commit-graph'. Default value: none.
415
416repo.enable-log-filecount::
417	A flag which can be used to disable the global setting
418	`enable-log-filecount'. Default value: none.
419
420repo.enable-log-linecount::
421	A flag which can be used to disable the global setting
422	`enable-log-linecount'. Default value: none.
423
424repo.enable-remote-branches::
425	Flag which, when set to "1", will make cgit display remote branches
426	in the summary and refs views. Default value: <enable-remote-branches>.
427
428repo.enable-subject-links::
429	A flag which can be used to override the global setting
430	`enable-subject-links'. Default value: none.
431
432repo.logo::
433	Url which specifies the source of an image which will be used as a logo
434	on this repo's pages. Default value: global logo.
435
436repo.logo-link::
437	Url loaded when clicking on the cgit logo image. If unspecified the
438	calculated url of the repository index page will be used. Default
439	value: global logo-link.
440
441repo.module-link::
442	Text which will be used as the formatstring for a hyperlink when a
443	submodule is printed in a directory listing. The arguments for the
444	formatstring are the path and SHA1 of the submodule commit. Default
445	value: <module-link>
446
447repo.module-link.<path>::
448	Text which will be used as the formatstring for a hyperlink when a
449	submodule with the specified subdirectory path is printed in a
450	directory listing. The only argument for the formatstring is the SHA1
451	of the submodule commit. Default value: none.
452
453repo.max-stats::
454	Override the default maximum statistics period. Valid values are equal
455	to the values specified for the global "max-stats" setting. Default
456	value: none.
457
458repo.name::
459	The value to show as repository name. Default value: <repo.url>.
460
461repo.owner::
462	A value used to identify the owner of the repository. Default value:
463	none.
464
465repo.path::
466	An absolute path to the repository directory. For non-bare repositories
467	this is the .git-directory. Default value: none.
468
469repo.readme::
470	A path (relative to <repo.path>) which specifies a file to include
471	verbatim as the "About" page for this repo. You may also specify a
472	git refspec by head or by hash by prepending the refspec followed by
473	a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
474
475repo.snapshots::
476	A mask of allowed snapshot-formats for this repo, restricted by the
477	"snapshots" global setting. Default value: <snapshots>.
478
479repo.section::
480	Override the current section name for this repository. Default value:
481	none.
482
483repo.source-filter::
484	Override the default source-filter. Default value: none. See also:
485	"enable-filter-overrides". See also: "FILTER API".
486
487repo.url::
488	The relative url used to access the repository. This must be the first
489	setting specified for each repo. Default value: none.
490
491
492REPOSITORY-SPECIFIC CGITRC FILE
493-------------------------------
494When the option "scan-path" is used to auto-discover git repositories, cgit
495will try to parse the file "cgitrc" within any found repository. Such a
496repo-specific config file may contain any of the repo-specific options
497described above, except "repo.url" and "repo.path". Additionally, the "filter"
498options are only acknowledged in repo-specific config files when
499"enable-filter-overrides" is set to "1".
500
501Note: the "repo." prefix is dropped from the option names in repo-specific
502config files, e.g. "repo.desc" becomes "desc".
503
504
505FILTER API
506----------
507about filter::
508	This filter is given no arguments. The about text that is to be
509	filtered is available on standard input and the filtered text is
510	expected on standard output.
511
512commit filter::
513	This filter is given no arguments. The commit message text that is to
514	be filtered is available on standard input and the filtered text is
515	expected on standard output.
516
517source filter::
518	This filter is given a single parameter: the filename of the source
519	file to filter. The filter can use the filename to determine (for
520	example) the syntax highlighting mode. The contents of the source
521	file that is to be filtered is available on standard input and the
522	filtered contents is expected on standard output.
523
524Also, all filters are handed the following environment variables:
525
526- CGIT_REPO_URL (from repo.url)
527- CGIT_REPO_NAME (from repo.name)
528- CGIT_REPO_PATH (from repo.path)
529- CGIT_REPO_OWNER (from repo.owner)
530- CGIT_REPO_DEFBRANCH (from repo.defbranch)
531- CGIT_REPO_SECTION (from repo.section)
532- CGIT_REPO_CLONE_URL (from repo.clone-url)
533
534If a setting is not defined for a repository and the corresponding global
535setting is also not defined (if applicable), then the corresponding
536environment variable will be unset.
537
538
539MACRO EXPANSION
540---------------
541The following cgitrc options supports a simple macro expansion feature,
542where tokens prefixed with "$" are replaced with the value of a similary
543named environment variable:
544
545- cache-root
546- include
547- project-list
548- scan-path
549
550Macro expansion will also happen on the content of $CGIT_CONFIG, if
551defined.
552
553One usage of this feature is virtual hosting, which in its simplest form
554can be accomplished by adding the following line to /etc/cgitrc:
555
556	include=/etc/cgitrc.d/$HTTP_HOST
557
558The following options are expanded during request processing, and support
559the environment variables defined in "FILTER API":
560
561- clone-url
562- repo.clone-url
563
564
565EXAMPLE CGITRC FILE
566-------------------
567
568....
569# Enable caching of up to 1000 output entriess
570cache-size=1000
571
572
573# Specify some default clone urls using macro expansion
574clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
575
576# Specify the css url
577css=/css/cgit.css
578
579
580# Show extra links for each repository on the index page
581enable-index-links=1
582
583
584# Enable ASCII art commit history graph on the log pages
585enable-commit-graph=1
586
587
588# Show number of affected files per commit on the log pages
589enable-log-filecount=1
590
591
592# Show number of added/removed lines per commit on the log pages
593enable-log-linecount=1
594
595
596# Add a cgit favicon
597favicon=/favicon.ico
598
599
600# Use a custom logo
601logo=/img/mylogo.png
602
603
604# Enable statistics per week, month and quarter
605max-stats=quarter
606
607
608# Set the title and heading of the repository index page
609root-title=example.com git repositories
610
611
612# Set a subheading for the repository index page
613root-desc=tracking the foobar development
614
615
616# Include some more info about example.com on the index page
617root-readme=/var/www/htdocs/about.html
618
619
620# Allow download of tar.gz, tar.bz2 and zip-files
621snapshots=tar.gz tar.bz2 zip
622
623
624##
625## List of common mimetypes
626##
627
628mimetype.gif=image/gif
629mimetype.html=text/html
630mimetype.jpg=image/jpeg
631mimetype.jpeg=image/jpeg
632mimetype.pdf=application/pdf
633mimetype.png=image/png
634mimetype.svg=image/svg+xml
635
636
637##
638## List of repositories.
639## PS: Any repositories listed when section is unset will not be
640##     displayed under a section heading
641## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
642##      and included like this:
643##        include=/etc/cgitrepos
644##
645
646
647repo.url=foo
648repo.path=/pub/git/foo.git
649repo.desc=the master foo repository
650repo.owner=fooman@example.com
651repo.readme=info/web/about.html
652
653
654repo.url=bar
655repo.path=/pub/git/bar.git
656repo.desc=the bars for your foo
657repo.owner=barman@example.com
658repo.readme=info/web/about.html
659
660
661# The next repositories will be displayed under the 'extras' heading
662section=extras
663
664
665repo.url=baz
666repo.path=/pub/git/baz.git
667repo.desc=a set of extensions for bar users
668
669repo.url=wiz
670repo.path=/pub/git/wiz.git
671repo.desc=the wizard of foo
672
673
674# Add some mirrored repositories
675section=mirrors
676
677
678repo.url=git
679repo.path=/pub/git/git.git
680repo.desc=the dscm
681
682
683repo.url=linux
684repo.path=/pub/git/linux.git
685repo.desc=the kernel
686
687# Disable adhoc downloads of this repo
688repo.snapshots=0
689
690# Disable line-counts for this repo
691repo.enable-log-linecount=0
692
693# Restrict the max statistics period for this repo
694repo.max-stats=month
695....
696
697
698BUGS
699----
700Comments currently cannot appear on the same line as a setting; the comment
701will be included as part of the value. E.g. this line:
702
703	robots=index  # allow indexing
704
705will generate the following html element:
706
707	<meta name='robots' content='index  # allow indexing'/>
708
709
710
711AUTHOR
712------
713Lars Hjemli <hjemli@gmail.com>
714Jason A. Donenfeld <Jason@zx2c4.com>