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.
 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".
 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
 73clone-prefix::
 74	Space-separated list of common prefixes which, when combined with a
 75	repository url, generates valid clone urls for the repository. This
 76	setting is only used if `repo.clone-url` is unspecified. Default value:
 77	none.
 78
 79commit-filter::
 80	Specifies a command which will be invoked to format commit messages.
 81	The command will get the message on its STDIN, and the STDOUT from the
 82	command will be included verbatim as the commit message, i.e. this can
 83	be used to implement bugtracker integration. Default value: none.
 84
 85css::
 86	Url which specifies the css document to include in all cgit pages.
 87	Default value: "/cgit.css".
 88
 89embedded::
 90	Flag which, when set to "1", will make cgit generate a html fragment
 91	suitable for embedding in other html pages. Default value: none. See
 92	also: "noheader".
 93	
 94enable-filter-overrides::
 95	Flag which, when set to "1", allows all filter settings to be
 96	overridden in repository-specific cgitrc files. Default value: none.
 97
 98enable-index-links::
 99	Flag which, when set to "1", will make cgit generate extra links for
100	each repo in the repository index (specifically, to the "summary",
101	"commit" and "tree" pages). Default value: "0".
102
103enable-log-filecount::
104	Flag which, when set to "1", will make cgit print the number of
105	modified files for each commit on the repository log page. Default
106	value: "0".
107
108enable-log-linecount::
109	Flag which, when set to "1", will make cgit print the number of added
110	and removed lines for each commit on the repository log page. Default
111	value: "0".
112
113enable-remote-branches::
114	Flag which, when set to "1", will make cgit display remote branches
115	in the summary and refs views. Default value: "0". See also:
116	"repo.enable-remote-branches".
117
118enable-subject-links::
119	Flag which, when set to "1", will make cgit use the subject of the
120	parent commit as link text when generating links to parent commits
121	in commit view. Default value: "0". See also:
122	"repo.enable-subject-links".
123
124enable-tree-linenumbers::
125	Flag which, when set to "1", will make cgit generate linenumber links
126	for plaintext blobs printed in the tree view. Default value: "1".
127
128favicon::
129	Url used as link to a shortcut icon for cgit. If specified, it is
130	suggested to use the value "/favicon.ico" since certain browsers will
131	ignore other values. Default value: none.
132
133footer::
134	The content of the file specified with this option will be included
135	verbatim at the bottom of all pages (i.e. it replaces the standard
136	"generated by..." message. Default value: none.
137
138head-include::
139	The content of the file specified with this option will be included
140	verbatim in the html HEAD section on all pages. Default value: none.
141
142header::
143	The content of the file specified with this option will be included
144	verbatim at the top of all pages. Default value: none.
145
146include::
147	Name of a configfile to include before the rest of the current config-
148	file is parsed. Default value: none.
149
150index-header::
151	The content of the file specified with this option will be included
152	verbatim above the repository index. This setting is deprecated, and
153	will not be supported by cgit-1.0 (use root-readme instead). Default
154	value: none.
155
156index-info::
157	The content of the file specified with this option will be included
158	verbatim below the heading on the repository index page. This setting
159	is deprecated, and will not be supported by cgit-1.0 (use root-desc
160	instead). Default value: none.
161
162local-time::
163	Flag which, if set to "1", makes cgit print commit and tag times in the
164	servers timezone. Default value: "0".
165
166logo::
167	Url which specifies the source of an image which will be used as a logo
168	on all cgit pages. Default value: "/cgit.png".
169
170logo-link::
171	Url loaded when clicking on the cgit logo image. If unspecified the
172	calculated url of the repository index page will be used. Default
173	value: none.
174
175max-atom-items::
176	Specifies the number of items to display in atom feeds view. Default
177	value: "10".
178
179max-commit-count::
180	Specifies the number of entries to list per page in "log" view. Default
181	value: "50".
182
183max-message-length::
184	Specifies the maximum number of commit message characters to display in
185	"log" view. Default value: "80".
186
187max-repo-count::
188	Specifies the number of entries to list per page on the	repository
189	index page. Default value: "50".
190
191max-repodesc-length::
192	Specifies the maximum number of repo description characters to display
193	on the repository index page. Default value: "80".
194
195max-blob-size::
196	Specifies the maximum size of a blob to display HTML for in KBytes.
197	Default value: "0" (limit disabled).
198
199max-stats::
200	Set the default maximum statistics period. Valid values are "week",
201	"month", "quarter" and "year". If unspecified, statistics are
202	disabled. Default value: none. See also: "repo.max-stats".
203
204mimetype.<ext>::
205	Set the mimetype for the specified filename extension. This is used
206	by the `plain` command when returning blob content.
207
208module-link::
209	Text which will be used as the formatstring for a hyperlink when a
210	submodule is printed in a directory listing. The arguments for the
211	formatstring are the path and SHA1 of the submodule commit. Default
212	value: "./?repo=%s&page=commit&id=%s"
213
214nocache::
215	If set to the value "1" caching will be disabled. This settings is
216	deprecated, and will not be honored starting with cgit-1.0. Default
217	value: "0".
218
219noplainemail::
220	If set to "1" showing full author email adresses will be disabled.
221	Default value: "0".
222
223noheader::
224	Flag which, when set to "1", will make cgit omit the standard header
225	on all pages. Default value: none. See also: "embedded".
226
227project-list::
228	A list of subdirectories inside of scan-path, relative to it, that
229	should loaded as git repositories. This must be defined prior to
230	scan-path. Default value: none. See also: scan-path.
231
232renamelimit::
233	Maximum number of files to consider when detecting renames. The value
234	 "-1" uses the compiletime value in git (for further info, look at
235	  `man git-diff`). Default value: "-1".
236
237repo.group::
238	Legacy alias for "section". This option is deprecated and will not be
239	supported in cgit-1.0.
240
241robots::
242	Text used as content for the "robots" meta-tag. Default value:
243	"index, nofollow".
244
245root-desc::
246	Text printed below the heading on the repository index page. Default
247	value: "a fast webinterface for the git dscm".
248
249root-readme::
250	The content of the file specified with this option will be included
251	verbatim below the "about" link on the repository index page. Default
252	value: none.
253
254root-title::
255	Text printed as heading on the repository index page. Default value:
256	"Git Repository Browser".
257
258scan-path::
259	A path which will be scanned for repositories. If caching is enabled,
260	the result will be cached as a cgitrc include-file in the cache
261	directory. If project-list has been defined prior to scan-path,
262	scan-path loads only the directories listed in the file pointed to by
263	project-list. Default value: none. See also: cache-scanrc-ttl,
264	project-list.
265
266section::
267	The name of the current repository section - all repositories defined
268	after this option will inherit the current section name. Default value:
269	none.
270
271side-by-side-diffs::
272	If set to "1" shows side-by-side diffs instead of unidiffs per
273	default. Default value: "0".
274
275snapshots::
276	Text which specifies the default set of snapshot formats generated by
277	cgit. The value is a space-separated list of zero or more of the
278	values "tar", "tar.gz", "tar.bz2" and "zip". Default value: none.
279
280source-filter::
281	Specifies a command which will be invoked to format plaintext blobs
282	in the tree view. The command will get the blob content on its STDIN
283	and the name of the blob as its only command line argument. The STDOUT
284	from the command will be included verbatim as the blob contents, i.e.
285	this can be used to implement e.g. syntax highlighting. Default value:
286	none.
287
288summary-branches::
289	Specifies the number of branches to display in the repository "summary"
290	view. Default value: "10".
291
292summary-log::
293	Specifies the number of log entries to display in the repository
294	"summary" view. Default value: "10".
295
296summary-tags::
297	Specifies the number of tags to display in the repository "summary"
298	view. Default value: "10".
299
300virtual-root::
301	Url which, if specified, will be used as root for all cgit links. It
302	will also cause cgit to generate 'virtual urls', i.e. urls like
303	'/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
304	value: none.
305	NOTE: cgit has recently learned how to use PATH_INFO to achieve the
306	same kind of virtual urls, so this option will probably be deprecated.
307
308REPOSITORY SETTINGS
309-------------------
310repo.about-filter::
311	Override the default about-filter. Default value: none. See also:
312	"enable-filter-overrides".
313
314repo.clone-url::
315	A list of space-separated urls which can be used to clone this repo.
316	Default value: none.
317
318repo.commit-filter::
319	Override the default commit-filter. Default value: none. See also:
320	"enable-filter-overrides".
321
322repo.defbranch::
323	The name of the default branch for this repository. If no such branch
324	exists in the repository, the first branch name (when sorted) is used
325	as default instead. Default value: "master".
326
327repo.desc::
328	The value to show as repository description. Default value: none.
329
330repo.enable-log-filecount::
331	A flag which can be used to disable the global setting
332	`enable-log-filecount'. Default value: none.
333
334repo.enable-log-linecount::
335	A flag which can be used to disable the global setting
336	`enable-log-linecount'. Default value: none.
337
338repo.enable-remote-branches::
339	Flag which, when set to "1", will make cgit display remote branches
340	in the summary and refs views. Default value: <enable-remote-branches>.
341
342repo.enable-subject-links::
343	A flag which can be used to override the global setting
344	`enable-subject-links'. Default value: none.
345
346repo.max-stats::
347	Override the default maximum statistics period. Valid values are equal
348	to the values specified for the global "max-stats" setting. Default
349	value: none.
350
351repo.name::
352	The value to show as repository name. Default value: <repo.url>.
353
354repo.owner::
355	A value used to identify the owner of the repository. Default value:
356	none.
357
358repo.path::
359	An absolute path to the repository directory. For non-bare repositories
360	this is the .git-directory. Default value: none.
361
362repo.readme::
363	A path (relative to <repo.path>) which specifies a file to include
364	verbatim as the "About" page for this repo. Default value: none.
365
366repo.snapshots::
367	A mask of allowed snapshot-formats for this repo, restricted by the
368	"snapshots" global setting. Default value: <snapshots>.
369
370repo.section::
371	Override the current section name for this repository. Default value:
372	none.
373
374repo.source-filter::
375	Override the default source-filter. Default value: none. See also:
376	"enable-filter-overrides".
377
378repo.url::
379	The relative url used to access the repository. This must be the first
380	setting specified for each repo. Default value: none.
381
382
383REPOSITORY-SPECIFIC CGITRC FILE
384-------------------------------
385When the option "scan-path" is used to auto-discover git repositories, cgit
386will try to parse the file "cgitrc" within any found repository. Such a
387repo-specific config file may contain any of the repo-specific options
388described above, except "repo.url" and "repo.path". Additionally, the "filter"
389options are only acknowledged in repo-specific config files when
390"enable-filter-overrides" is set to "1".
391
392Note: the "repo." prefix is dropped from the option names in repo-specific
393config files, e.g. "repo.desc" becomes "desc".
394
395
396EXAMPLE CGITRC FILE
397-------------------
398
399....
400# Enable caching of up to 1000 output entriess
401cache-size=1000
402
403
404# Specify some default clone prefixes
405clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
406
407# Specify the css url
408css=/css/cgit.css
409
410
411# Show extra links for each repository on the index page
412enable-index-links=1
413
414
415# Show number of affected files per commit on the log pages
416enable-log-filecount=1
417
418
419# Show number of added/removed lines per commit on the log pages
420enable-log-linecount=1
421
422
423# Add a cgit favicon
424favicon=/favicon.ico
425
426
427# Use a custom logo
428logo=/img/mylogo.png
429
430
431# Enable statistics per week, month and quarter
432max-stats=quarter
433
434
435# Set the title and heading of the repository index page
436root-title=foobar.com git repositories
437
438
439# Set a subheading for the repository index page
440root-desc=tracking the foobar development
441
442
443# Include some more info about foobar.com on the index page
444root-readme=/var/www/htdocs/about.html
445
446
447# Allow download of tar.gz, tar.bz2 and zip-files
448snapshots=tar.gz tar.bz2 zip
449
450
451##
452## List of common mimetypes
453##
454
455mimetype.gif=image/gif
456mimetype.html=text/html
457mimetype.jpg=image/jpeg
458mimetype.jpeg=image/jpeg
459mimetype.pdf=application/pdf
460mimetype.png=image/png
461mimetype.svg=image/svg+xml
462
463
464##
465## List of repositories.
466## PS: Any repositories listed when section is unset will not be
467##     displayed under a section heading
468## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
469##      and included like this:
470##        include=/etc/cgitrepos
471##
472
473
474repo.url=foo
475repo.path=/pub/git/foo.git
476repo.desc=the master foo repository
477repo.owner=fooman@foobar.com
478repo.readme=info/web/about.html
479
480
481repo.url=bar
482repo.path=/pub/git/bar.git
483repo.desc=the bars for your foo
484repo.owner=barman@foobar.com
485repo.readme=info/web/about.html
486
487
488# The next repositories will be displayed under the 'extras' heading
489section=extras
490
491
492repo.url=baz
493repo.path=/pub/git/baz.git
494repo.desc=a set of extensions for bar users
495
496repo.url=wiz
497repo.path=/pub/git/wiz.git
498repo.desc=the wizard of foo
499
500
501# Add some mirrored repositories
502section=mirrors
503
504
505repo.url=git
506repo.path=/pub/git/git.git
507repo.desc=the dscm
508
509
510repo.url=linux
511repo.path=/pub/git/linux.git
512repo.desc=the kernel
513
514# Disable adhoc downloads of this repo
515repo.snapshots=0
516
517# Disable line-counts for this repo
518repo.enable-log-linecount=0
519
520# Restrict the max statistics period for this repo
521repo.max-stats=month
522....
523
524
525BUGS
526----
527Comments currently cannot appear on the same line as a setting; the comment
528will be included as part of the value. E.g. this line:
529
530	robots=index  # allow indexing
531
532will generate the following html element:
533
534	<meta name='robots' content='index  # allow indexing'/>
535
536
537
538AUTHOR
539------
540Lars Hjemli <hjemli@gmail.com>