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-hidden-path::
278	If set to "1" and scan-path is enabled, scan-path will recurse into
279	directories whose name starts with a period ('.'). Otherwise,
280	scan-path will stay away from such directories (considered as
281	"hidden"). Note that this does not apply to the ".git" directory in
282	non-bare repos. This must be defined prior to scan-path.
283	Default value: 0. See also: scan-path.
284
285scan-path::
286	A path which will be scanned for repositories. If caching is enabled,
287	the result will be cached as a cgitrc include-file in the cache
288	directory. If project-list has been defined prior to scan-path,
289	scan-path loads only the directories listed in the file pointed to by
290	project-list. Be advised that only the global settings taken
291	before the scan-path directive will be applied to each repository.
292	Default value: none. See also: cache-scanrc-ttl, project-list.
293
294section::
295	The name of the current repository section - all repositories defined
296	after this option will inherit the current section name. Default value:
297	none.
298
299section-from-path::
300	A number which, if specified before scan-path, specifies how many
301	path elements from each repo path to use as a default section name.
302	If negative, cgit will discard the specified number of path elements
303	above the repo directory. Default value: 0.
304
305side-by-side-diffs::
306	If set to "1" shows side-by-side diffs instead of unidiffs per
307	default. Default value: "0".
308
309snapshots::
310	Text which specifies the default set of snapshot formats generated by
311	cgit. The value is a space-separated list of zero or more of the
312	values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
313	none.
314
315source-filter::
316	Specifies a command which will be invoked to format plaintext blobs
317	in the tree view. The command will get the blob content on its STDIN
318	and the name of the blob as its only command line argument. The STDOUT
319	from the command will be included verbatim as the blob contents, i.e.
320	this can be used to implement e.g. syntax highlighting. Default value:
321	none.
322
323summary-branches::
324	Specifies the number of branches to display in the repository "summary"
325	view. Default value: "10".
326
327summary-log::
328	Specifies the number of log entries to display in the repository
329	"summary" view. Default value: "10".
330
331summary-tags::
332	Specifies the number of tags to display in the repository "summary"
333	view. Default value: "10".
334
335strict-export::
336	Filename which, if specified, needs to be present within the repository
337	for cgit to allow access to that repository. This can be used to emulate
338	gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
339	repositories to match those exported by git-daemon. This option MUST come
340	before 'scan-path'.
341
342virtual-root::
343	Url which, if specified, will be used as root for all cgit links. It
344	will also cause cgit to generate 'virtual urls', i.e. urls like
345	'/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
346	value: none.
347	NOTE: cgit has recently learned how to use PATH_INFO to achieve the
348	same kind of virtual urls, so this option will probably be deprecated.
349
350REPOSITORY SETTINGS
351-------------------
352repo.about-filter::
353	Override the default about-filter. Default value: none. See also:
354	"enable-filter-overrides".
355
356repo.clone-url::
357	A list of space-separated urls which can be used to clone this repo.
358	Default value: none.
359
360repo.commit-filter::
361	Override the default commit-filter. Default value: none. See also:
362	"enable-filter-overrides".
363
364repo.defbranch::
365	The name of the default branch for this repository. If no such branch
366	exists in the repository, the first branch name (when sorted) is used
367	as default instead. Default value: "master".
368
369repo.desc::
370	The value to show as repository description. Default value: none.
371
372repo.enable-commit-graph::
373	A flag which can be used to disable the global setting
374	`enable-commit-graph'. Default value: none.
375
376repo.enable-log-filecount::
377	A flag which can be used to disable the global setting
378	`enable-log-filecount'. Default value: none.
379
380repo.enable-log-linecount::
381	A flag which can be used to disable the global setting
382	`enable-log-linecount'. Default value: none.
383
384repo.enable-remote-branches::
385	Flag which, when set to "1", will make cgit display remote branches
386	in the summary and refs views. Default value: <enable-remote-branches>.
387
388repo.enable-subject-links::
389	A flag which can be used to override the global setting
390	`enable-subject-links'. Default value: none.
391
392repo.logo::
393	Url which specifies the source of an image which will be used as a logo
394	on this repo's pages. Default value: global logo.
395
396repo.logo-link::
397	Url loaded when clicking on the cgit logo image. If unspecified the
398	calculated url of the repository index page will be used. Default
399	value: global logo-link.
400
401repo.max-stats::
402	Override the default maximum statistics period. Valid values are equal
403	to the values specified for the global "max-stats" setting. Default
404	value: none.
405
406repo.name::
407	The value to show as repository name. Default value: <repo.url>.
408
409repo.owner::
410	A value used to identify the owner of the repository. Default value:
411	none.
412
413repo.path::
414	An absolute path to the repository directory. For non-bare repositories
415	this is the .git-directory. Default value: none.
416
417repo.readme::
418	A path (relative to <repo.path>) which specifies a file to include
419	verbatim as the "About" page for this repo. You may also specify a
420	git refspec by head or by hash by prepending the refspec followed by
421	a colon. For example, "master:docs/readme.mkd" Default value: <readme>.
422
423repo.snapshots::
424	A mask of allowed snapshot-formats for this repo, restricted by the
425	"snapshots" global setting. Default value: <snapshots>.
426
427repo.section::
428	Override the current section name for this repository. Default value:
429	none.
430
431repo.source-filter::
432	Override the default source-filter. Default value: none. See also:
433	"enable-filter-overrides".
434
435repo.url::
436	The relative url used to access the repository. This must be the first
437	setting specified for each repo. Default value: none.
438
439
440REPOSITORY-SPECIFIC CGITRC FILE
441-------------------------------
442When the option "scan-path" is used to auto-discover git repositories, cgit
443will try to parse the file "cgitrc" within any found repository. Such a
444repo-specific config file may contain any of the repo-specific options
445described above, except "repo.url" and "repo.path". Additionally, the "filter"
446options are only acknowledged in repo-specific config files when
447"enable-filter-overrides" is set to "1".
448
449Note: the "repo." prefix is dropped from the option names in repo-specific
450config files, e.g. "repo.desc" becomes "desc".
451
452
453EXAMPLE CGITRC FILE
454-------------------
455
456....
457# Enable caching of up to 1000 output entriess
458cache-size=1000
459
460
461# Specify some default clone prefixes
462clone-prefix=git://example.com ssh://example.com/pub/git http://example.com/git
463
464# Specify the css url
465css=/css/cgit.css
466
467
468# Show extra links for each repository on the index page
469enable-index-links=1
470
471
472# Enable ASCII art commit history graph on the log pages
473enable-commit-graph=1
474
475
476# Show number of affected files per commit on the log pages
477enable-log-filecount=1
478
479
480# Show number of added/removed lines per commit on the log pages
481enable-log-linecount=1
482
483
484# Add a cgit favicon
485favicon=/favicon.ico
486
487
488# Use a custom logo
489logo=/img/mylogo.png
490
491
492# Enable statistics per week, month and quarter
493max-stats=quarter
494
495
496# Set the title and heading of the repository index page
497root-title=example.com git repositories
498
499
500# Set a subheading for the repository index page
501root-desc=tracking the foobar development
502
503
504# Include some more info about example.com on the index page
505root-readme=/var/www/htdocs/about.html
506
507
508# Allow download of tar.gz, tar.bz2 and zip-files
509snapshots=tar.gz tar.bz2 zip
510
511
512##
513## List of common mimetypes
514##
515
516mimetype.gif=image/gif
517mimetype.html=text/html
518mimetype.jpg=image/jpeg
519mimetype.jpeg=image/jpeg
520mimetype.pdf=application/pdf
521mimetype.png=image/png
522mimetype.svg=image/svg+xml
523
524
525##
526## List of repositories.
527## PS: Any repositories listed when section is unset will not be
528##     displayed under a section heading
529## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
530##      and included like this:
531##        include=/etc/cgitrepos
532##
533
534
535repo.url=foo
536repo.path=/pub/git/foo.git
537repo.desc=the master foo repository
538repo.owner=fooman@example.com
539repo.readme=info/web/about.html
540
541
542repo.url=bar
543repo.path=/pub/git/bar.git
544repo.desc=the bars for your foo
545repo.owner=barman@example.com
546repo.readme=info/web/about.html
547
548
549# The next repositories will be displayed under the 'extras' heading
550section=extras
551
552
553repo.url=baz
554repo.path=/pub/git/baz.git
555repo.desc=a set of extensions for bar users
556
557repo.url=wiz
558repo.path=/pub/git/wiz.git
559repo.desc=the wizard of foo
560
561
562# Add some mirrored repositories
563section=mirrors
564
565
566repo.url=git
567repo.path=/pub/git/git.git
568repo.desc=the dscm
569
570
571repo.url=linux
572repo.path=/pub/git/linux.git
573repo.desc=the kernel
574
575# Disable adhoc downloads of this repo
576repo.snapshots=0
577
578# Disable line-counts for this repo
579repo.enable-log-linecount=0
580
581# Restrict the max statistics period for this repo
582repo.max-stats=month
583....
584
585
586BUGS
587----
588Comments currently cannot appear on the same line as a setting; the comment
589will be included as part of the value. E.g. this line:
590
591	robots=index  # allow indexing
592
593will generate the following html element:
594
595	<meta name='robots' content='index  # allow indexing'/>
596
597
598
599AUTHOR
600------
601Lars Hjemli <hjemli@gmail.com>
602Jason A. Donenfeld <Jason@zx2c4.com>