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