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-gitweb-owner::
 99	If set to "1" and scan-path is enabled, we first check each repository
100	for the git config value "gitweb.owner" to determine the owner.
101	Default value: "1". See also: scan-path.
102
103enable-http-clone::
104	If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
105	If you use an alternate way of serving git repositories, you may wish
106	to disable this. Default value: "1".
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-log-filecount::
363	A flag which can be used to disable the global setting
364	`enable-log-filecount'. Default value: none.
365
366repo.enable-log-linecount::
367	A flag which can be used to disable the global setting
368	`enable-log-linecount'. Default value: none.
369
370repo.enable-remote-branches::
371	Flag which, when set to "1", will make cgit display remote branches
372	in the summary and refs views. Default value: <enable-remote-branches>.
373
374repo.enable-subject-links::
375	A flag which can be used to override the global setting
376	`enable-subject-links'. Default value: none.
377
378repo.max-stats::
379	Override the default maximum statistics period. Valid values are equal
380	to the values specified for the global "max-stats" setting. Default
381	value: none.
382
383repo.name::
384	The value to show as repository name. Default value: <repo.url>.
385
386repo.owner::
387	A value used to identify the owner of the repository. Default value:
388	none.
389
390repo.path::
391	An absolute path to the repository directory. For non-bare repositories
392	this is the .git-directory. Default value: none.
393
394repo.readme::
395	A path (relative to <repo.path>) which specifies a file to include
396	verbatim as the "About" page for this repo. You may also specify a
397	git refspec by head or by hash by prepending the refspec followed by
398	a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
399
400repo.snapshots::
401	A mask of allowed snapshot-formats for this repo, restricted by the
402	"snapshots" global setting. Default value: <snapshots>.
403
404repo.section::
405	Override the current section name for this repository. Default value:
406	none.
407
408repo.source-filter::
409	Override the default source-filter. Default value: none. See also:
410	"enable-filter-overrides".
411
412repo.url::
413	The relative url used to access the repository. This must be the first
414	setting specified for each repo. Default value: none.
415
416
417REPOSITORY-SPECIFIC CGITRC FILE
418-------------------------------
419When the option "scan-path" is used to auto-discover git repositories, cgit
420will try to parse the file "cgitrc" within any found repository. Such a
421repo-specific config file may contain any of the repo-specific options
422described above, except "repo.url" and "repo.path". Additionally, the "filter"
423options are only acknowledged in repo-specific config files when
424"enable-filter-overrides" is set to "1".
425
426Note: the "repo." prefix is dropped from the option names in repo-specific
427config files, e.g. "repo.desc" becomes "desc".
428
429
430EXAMPLE CGITRC FILE
431-------------------
432
433....
434# Enable caching of up to 1000 output entriess
435cache-size=1000
436
437
438# Specify some default clone prefixes
439clone-prefix=git://example.com ssh://example.com/pub/git http://example.com/git
440
441# Specify the css url
442css=/css/cgit.css
443
444
445# Show extra links for each repository on the index page
446enable-index-links=1
447
448
449# Show number of affected files per commit on the log pages
450enable-log-filecount=1
451
452
453# Show number of added/removed lines per commit on the log pages
454enable-log-linecount=1
455
456
457# Add a cgit favicon
458favicon=/favicon.ico
459
460
461# Use a custom logo
462logo=/img/mylogo.png
463
464
465# Enable statistics per week, month and quarter
466max-stats=quarter
467
468
469# Set the title and heading of the repository index page
470root-title=example.com git repositories
471
472
473# Set a subheading for the repository index page
474root-desc=tracking the foobar development
475
476
477# Include some more info about example.com on the index page
478root-readme=/var/www/htdocs/about.html
479
480
481# Allow download of tar.gz, tar.bz2 and zip-files
482snapshots=tar.gz tar.bz2 zip
483
484
485##
486## List of common mimetypes
487##
488
489mimetype.gif=image/gif
490mimetype.html=text/html
491mimetype.jpg=image/jpeg
492mimetype.jpeg=image/jpeg
493mimetype.pdf=application/pdf
494mimetype.png=image/png
495mimetype.svg=image/svg+xml
496
497
498##
499## List of repositories.
500## PS: Any repositories listed when section is unset will not be
501##     displayed under a section heading
502## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
503##      and included like this:
504##        include=/etc/cgitrepos
505##
506
507
508repo.url=foo
509repo.path=/pub/git/foo.git
510repo.desc=the master foo repository
511repo.owner=fooman@example.com
512repo.readme=info/web/about.html
513
514
515repo.url=bar
516repo.path=/pub/git/bar.git
517repo.desc=the bars for your foo
518repo.owner=barman@example.com
519repo.readme=info/web/about.html
520
521
522# The next repositories will be displayed under the 'extras' heading
523section=extras
524
525
526repo.url=baz
527repo.path=/pub/git/baz.git
528repo.desc=a set of extensions for bar users
529
530repo.url=wiz
531repo.path=/pub/git/wiz.git
532repo.desc=the wizard of foo
533
534
535# Add some mirrored repositories
536section=mirrors
537
538
539repo.url=git
540repo.path=/pub/git/git.git
541repo.desc=the dscm
542
543
544repo.url=linux
545repo.path=/pub/git/linux.git
546repo.desc=the kernel
547
548# Disable adhoc downloads of this repo
549repo.snapshots=0
550
551# Disable line-counts for this repo
552repo.enable-log-linecount=0
553
554# Restrict the max statistics period for this repo
555repo.max-stats=month
556....
557
558
559BUGS
560----
561Comments currently cannot appear on the same line as a setting; the comment
562will be included as part of the value. E.g. this line:
563
564	robots=index  # allow indexing
565
566will generate the following html element:
567
568	<meta name='robots' content='index  # allow indexing'/>
569
570
571
572AUTHOR
573------
574Lars Hjemli <hjemli@gmail.com>
575Jason A. Donenfeld <Jason@zx2c4.com>