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