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, the name of the file
 33	as the first argument, and the STDOUT from the command will be
 34	included verbatim on the about page. Default value: none. See
 35	also: "FILTER API".
 36
 37agefile::
 38	Specifies a path, relative to each repository path, which can be used
 39	to specify the date and time of the youngest commit in the repository.
 40	The first line in the file is used as input to the "parse_date"
 41	function in libgit. Recommended timestamp-format is "yyyy-mm-dd
 42	hh:mm:ss". You may want to generate this file from a post-receive
 43	hook. Default value: "info/web/last-modified".
 44
 45auth-filter::
 46	Specifies a command that will be invoked for authenticating repository
 47	access. Receives quite a few arguments, and data on both stdin and
 48	stdout for authentication processing. Details follow later in this
 49	document. If no auth-filter is specified, no authentication is
 50	performed. Default value: none. See also: "FILTER API".
 51
 52branch-sort::
 53	Flag which, when set to "age", enables date ordering in the branch ref
 54	list, and when set to "name" enables ordering by branch name. Default
 55	value: "name".
 56
 57cache-root::
 58	Path used to store the cgit cache entries. Default value:
 59	"/var/cache/cgit". See also: "MACRO EXPANSION".
 60
 61cache-static-ttl::
 62	Number which specifies the time-to-live, in minutes, for the cached
 63	version of repository pages accessed with a fixed SHA1. See also:
 64	"CACHE". Default value: -1".
 65
 66cache-dynamic-ttl::
 67	Number which specifies the time-to-live, in minutes, for the cached
 68	version of repository pages accessed without a fixed SHA1. See also:
 69	"CACHE". Default value: "5".
 70
 71cache-repo-ttl::
 72	Number which specifies the time-to-live, in minutes, for the cached
 73	version of the repository summary page. See also: "CACHE". Default
 74	value: "5".
 75
 76cache-root-ttl::
 77	Number which specifies the time-to-live, in minutes, for the cached
 78	version of the repository index page. See also: "CACHE". Default
 79	value: "5".
 80
 81cache-scanrc-ttl::
 82	Number which specifies the time-to-live, in minutes, for the result
 83	of scanning a path for git repositories. See also: "CACHE". Default
 84	value: "15".
 85
 86cache-about-ttl::
 87	Number which specifies the time-to-live, in minutes, for the cached
 88	version of the repository about page. See also: "CACHE". Default
 89	value: "15".
 90
 91cache-snapshot-ttl::
 92	Number which specifies the time-to-live, in minutes, for the cached
 93	version of snapshots. See also: "CACHE". Default value: "5".
 94
 95cache-size::
 96	The maximum number of entries in the cgit cache. When set to "0",
 97	caching is disabled. See also: "CACHE". Default value: "0"
 98
 99case-sensitive-sort::
100	Sort items in the repo list case sensitively. Default value: "1".
101	See also: repository-sort, section-sort.
102
103clone-prefix::
104	Space-separated list of common prefixes which, when combined with a
105	repository url, generates valid clone urls for the repository. This
106	setting is only used if `repo.clone-url` is unspecified. Default value:
107	none.
108
109clone-url::
110	Space-separated list of clone-url templates. This setting is only
111	used if `repo.clone-url` is unspecified. Default value: none. See
112	also: "MACRO EXPANSION", "FILTER API".
113
114commit-filter::
115	Specifies a command which will be invoked to format commit messages.
116	The command will get the message on its STDIN, and the STDOUT from the
117	command will be included verbatim as the commit message, i.e. this can
118	be used to implement bugtracker integration. Default value: none.
119	See also: "FILTER API".
120
121commit-sort::
122	Flag which, when set to "date", enables strict date ordering in the
123	commit log, and when set to "topo" enables strict topological
124	ordering. If unset, the default ordering of "git log" is used. Default
125	value: unset.
126
127css::
128	Url which specifies the css document to include in all cgit pages.
129	Default value: "/cgit.css".
130
131email-filter::
132	Specifies a command which will be invoked to format names and email
133	address of committers, authors, and taggers, as represented in various
134	places throughout the cgit interface. This command will receive an
135	email address and an origin page string as its command line arguments,
136	and the text to format on STDIN. It is to write the formatted text back
137	out onto STDOUT. Default value: none. See also: "FILTER API".
138
139embedded::
140	Flag which, when set to "1", will make cgit generate a html fragment
141	suitable for embedding in other html pages. Default value: none. See
142	also: "noheader".
143
144enable-commit-graph::
145	Flag which, when set to "1", will make cgit print an ASCII-art commit
146	history graph to the left of the commit messages in the repository
147	log page. Default value: "0".
148
149enable-filter-overrides::
150	Flag which, when set to "1", allows all filter settings to be
151	overridden in repository-specific cgitrc files. Default value: none.
152
153enable-follow-links::
154	Flag which, when set to "1", allows users to follow a file in the log
155	view.  Default value: "0".
156
157enable-http-clone::
158	If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
159	You can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url
160	to expose this feature. If you use an alternate way of serving git
161	repositories, you may wish to disable this. Default value: "1".
162
163enable-index-links::
164	Flag which, when set to "1", will make cgit generate extra links for
165	each repo in the repository index (specifically, to the "summary",
166	"commit" and "tree" pages). Default value: "0".
167
168enable-index-owner::
169	Flag which, when set to "1", will make cgit display the owner of
170	each repo in the repository index. Default value: "1".
171
172enable-log-filecount::
173	Flag which, when set to "1", will make cgit print the number of
174	modified files for each commit on the repository log page. Default
175	value: "0".
176
177enable-log-linecount::
178	Flag which, when set to "1", will make cgit print the number of added
179	and removed lines for each commit on the repository log page. Default
180	value: "0".
181
182enable-remote-branches::
183	Flag which, when set to "1", will make cgit display remote branches
184	in the summary and refs views. Default value: "0". See also:
185	"repo.enable-remote-branches".
186
187enable-subject-links::
188	Flag which, when set to "1", will make cgit use the subject of the
189	parent commit as link text when generating links to parent commits
190	in commit view. Default value: "0". See also:
191	"repo.enable-subject-links".
192
193enable-html-serving::
194	Flag which, when set to "1", will allow the /plain handler to serve
195	mimetype headers that result in the file being treated as HTML by the
196	browser. When set to "0", such file types are returned instead as
197	text/plain or application/octet-stream. Default value: "0". See also:
198	"repo.enable-html-serving".
199
200enable-tree-linenumbers::
201	Flag which, when set to "1", will make cgit generate linenumber links
202	for plaintext blobs printed in the tree view. Default value: "1".
203
204enable-git-config::
205	Flag which, when set to "1", will allow cgit to use git config to set
206	any repo specific settings. This option is used in conjunction with
207	"scan-path", and must be defined prior, to augment repo-specific
208	settings. The keys gitweb.owner, gitweb.category, and gitweb.description
209	will map to the cgit keys repo.owner, repo.section, and repo.desc,
210	respectively. All git config keys that begin with "cgit." will be mapped
211	to the corresponding "repo." key in cgit. Default value: "0". See also:
212	scan-path, section-from-path.
213
214favicon::
215	Url used as link to a shortcut icon for cgit. It is suggested to use
216	the value "/favicon.ico" since certain browsers will ignore other
217	values. Default value: "/favicon.ico".
218
219footer::
220	The content of the file specified with this option will be included
221	verbatim at the bottom of all pages (i.e. it replaces the standard
222	"generated by..." message. Default value: none.
223
224head-include::
225	The content of the file specified with this option will be included
226	verbatim in the html HEAD section on all pages. Default value: none.
227
228header::
229	The content of the file specified with this option will be included
230	verbatim at the top of all pages. Default value: none.
231
232include::
233	Name of a configfile to include before the rest of the current config-
234	file is parsed. Default value: none. See also: "MACRO EXPANSION".
235
236index-header::
237	The content of the file specified with this option will be included
238	verbatim above the repository index. This setting is deprecated, and
239	will not be supported by cgit-1.0 (use root-readme instead). Default
240	value: none.
241
242index-info::
243	The content of the file specified with this option will be included
244	verbatim below the heading on the repository index page. This setting
245	is deprecated, and will not be supported by cgit-1.0 (use root-desc
246	instead). Default value: none.
247
248local-time::
249	Flag which, if set to "1", makes cgit print commit and tag times in the
250	servers timezone. Default value: "0".
251
252logo::
253	Url which specifies the source of an image which will be used as a logo
254	on all cgit pages. Default value: "/cgit.png".
255
256logo-link::
257	Url loaded when clicking on the cgit logo image. If unspecified the
258	calculated url of the repository index page will be used. Default
259	value: none.
260
261owner-filter::
262	Specifies a command which will be invoked to format the Owner
263	column of the main page.  The command will get the owner on STDIN,
264	and the STDOUT from the command will be included verbatim in the
265	table.  This can be used to link to additional context such as an
266	owners home page.  When active this filter is used instead of the
267	default owner query url.  Default value: none.
268	See also: "FILTER API".
269
270max-atom-items::
271	Specifies the number of items to display in atom feeds view. Default
272	value: "10".
273
274max-commit-count::
275	Specifies the number of entries to list per page in "log" view. Default
276	value: "50".
277
278max-message-length::
279	Specifies the maximum number of commit message characters to display in
280	"log" view. Default value: "80".
281
282max-repo-count::
283	Specifies the number of entries to list per page on the	repository
284	index page. Default value: "50".
285
286max-repodesc-length::
287	Specifies the maximum number of repo description characters to display
288	on the repository index page. Default value: "80".
289
290max-blob-size::
291	Specifies the maximum size of a blob to display HTML for in KBytes.
292	Default value: "0" (limit disabled).
293
294max-stats::
295	Set the default maximum statistics period. Valid values are "week",
296	"month", "quarter" and "year". If unspecified, statistics are
297	disabled. Default value: none. See also: "repo.max-stats".
298
299mimetype.<ext>::
300	Set the mimetype for the specified filename extension. This is used
301	by the `plain` command when returning blob content.
302
303mimetype-file::
304	Specifies the file to use for automatic mimetype lookup. If specified
305	then this field is used as a fallback when no "mimetype.<ext>" match is
306	found. If unspecified then no such lookup is performed. The typical file
307	to use on a Linux system is /etc/mime.types. The format of the file must
308	comply to:
309	- a comment line is an empty line or a line starting with a hash (#),
310	  optionally preceded by whitespace
311	- a non-comment line starts with the mimetype (like image/png), followed
312	  by one or more file extensions (like jpg), all separated by whitespace
313	Default value: none. See also: "mimetype.<ext>".
314
315module-link::
316	Text which will be used as the formatstring for a hyperlink when a
317	submodule is printed in a directory listing. The arguments for the
318	formatstring are the path and SHA1 of the submodule commit. Default
319	value: none.
320
321nocache::
322	If set to the value "1" caching will be disabled. This settings is
323	deprecated, and will not be honored starting with cgit-1.0. Default
324	value: "0".
325
326noplainemail::
327	If set to "1" showing full author email addresses will be disabled.
328	Default value: "0".
329
330noheader::
331	Flag which, when set to "1", will make cgit omit the standard header
332	on all pages. Default value: none. See also: "embedded".
333
334project-list::
335	A list of subdirectories inside of scan-path, relative to it, that
336	should loaded as git repositories. This must be defined prior to
337	scan-path. Default value: none. See also: scan-path, "MACRO
338	EXPANSION".
339
340readme::
341	Text which will be used as default value for "repo.readme". Multiple
342	config keys may be specified, and cgit will use the first found file
343	in this list. This is useful in conjunction with scan-path. Default
344	value: none. See also: scan-path, repo.readme.
345
346remove-suffix::
347	If set to "1" and scan-path is enabled, if any repositories are found
348	with a suffix of ".git", this suffix will be removed for the url and
349	name. This must be defined prior to scan-path. Default value: "0".
350	See also: scan-path.
351
352renamelimit::
353	Maximum number of files to consider when detecting renames. The value
354	 "-1" uses the compiletime value in git (for further info, look at
355	  `man git-diff`). Default value: "-1".
356
357repo.group::
358	Legacy alias for "section". This option is deprecated and will not be
359	supported in cgit-1.0.
360
361repository-sort::
362	The way in which repositories in each section are sorted. Valid values
363	are "name" for sorting by the repo name or "age" for sorting by the
364	most recently updated repository. Default value: "name". See also:
365	section, case-sensitive-sort, section-sort.
366
367robots::
368	Text used as content for the "robots" meta-tag. Default value:
369	"index, nofollow".
370
371root-desc::
372	Text printed below the heading on the repository index page. Default
373	value: "a fast webinterface for the git dscm".
374
375root-readme::
376	The content of the file specified with this option will be included
377	verbatim below the "about" link on the repository index page. Default
378	value: none.
379
380root-title::
381	Text printed as heading on the repository index page. Default value:
382	"Git Repository Browser".
383
384scan-hidden-path::
385	If set to "1" and scan-path is enabled, scan-path will recurse into
386	directories whose name starts with a period ('.'). Otherwise,
387	scan-path will stay away from such directories (considered as
388	"hidden"). Note that this does not apply to the ".git" directory in
389	non-bare repos. This must be defined prior to scan-path.
390	Default value: 0. See also: scan-path.
391
392scan-path::
393	A path which will be scanned for repositories. If caching is enabled,
394	the result will be cached as a cgitrc include-file in the cache
395	directory. If project-list has been defined prior to scan-path,
396	scan-path loads only the directories listed in the file pointed to by
397	project-list. Be advised that only the global settings taken
398	before the scan-path directive will be applied to each repository.
399	Default value: none. See also: cache-scanrc-ttl, project-list,
400	"MACRO EXPANSION".
401
402section::
403	The name of the current repository section - all repositories defined
404	after this option will inherit the current section name. Default value:
405	none.
406
407section-sort::
408	Flag which, when set to "1", will sort the sections on the repository
409	listing by name. Set this flag to "0" if the order in the cgitrc file should
410	be preserved. Default value: "1". See also: section,
411	case-sensitive-sort, repository-sort.
412
413section-from-path::
414	A number which, if defined prior to scan-path, specifies how many
415	path elements from each repo path to use as a default section name.
416	If negative, cgit will discard the specified number of path elements
417	above the repo directory. Default value: "0".
418
419side-by-side-diffs::
420	If set to "1" shows side-by-side diffs instead of unidiffs per
421	default. Default value: "0".
422
423snapshots::
424	Text which specifies the default set of snapshot formats that cgit
425	generates links for. The value is a space-separated list of zero or
426	more of the values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip".
427	Default value: none.
428
429source-filter::
430	Specifies a command which will be invoked to format plaintext blobs
431	in the tree view. The command will get the blob content on its STDIN
432	and the name of the blob as its only command line argument. The STDOUT
433	from the command will be included verbatim as the blob contents, i.e.
434	this can be used to implement e.g. syntax highlighting. Default value:
435	none. See also: "FILTER API".
436
437summary-branches::
438	Specifies the number of branches to display in the repository "summary"
439	view. Default value: "10".
440
441summary-log::
442	Specifies the number of log entries to display in the repository
443	"summary" view. Default value: "10".
444
445summary-tags::
446	Specifies the number of tags to display in the repository "summary"
447	view. Default value: "10".
448
449strict-export::
450	Filename which, if specified, needs to be present within the repository
451	for cgit to allow access to that repository. This can be used to emulate
452	gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
453	repositories to match those exported by git-daemon. This option must
454	be defined prior to scan-path.
455
456virtual-root::
457	Url which, if specified, will be used as root for all cgit links. It
458	will also cause cgit to generate 'virtual urls', i.e. urls like
459	'/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
460	value: none.
461	NOTE: cgit has recently learned how to use PATH_INFO to achieve the
462	same kind of virtual urls, so this option will probably be deprecated.
463
464
465REPOSITORY SETTINGS
466-------------------
467repo.about-filter::
468	Override the default about-filter. Default value: none. See also:
469	"enable-filter-overrides". See also: "FILTER API".
470
471repo.branch-sort::
472	Flag which, when set to "age", enables date ordering in the branch ref
473	list, and when set to "name" enables ordering by branch name. Default
474	value: "name".
475
476repo.clone-url::
477	A list of space-separated urls which can be used to clone this repo.
478	Default value: none. See also: "MACRO EXPANSION".
479
480repo.commit-filter::
481	Override the default commit-filter. Default value: none. See also:
482	"enable-filter-overrides". See also: "FILTER API".
483
484repo.commit-sort::
485	Flag which, when set to "date", enables strict date ordering in the
486	commit log, and when set to "topo" enables strict topological
487	ordering. If unset, the default ordering of "git log" is used. Default
488	value: unset.
489
490repo.defbranch::
491	The name of the default branch for this repository. If no such branch
492	exists in the repository, the first branch name (when sorted) is used
493	as default instead. Default value: branch pointed to by HEAD, or
494	"master" if there is no suitable HEAD.
495
496repo.desc::
497	The value to show as repository description. Default value: none.
498
499repo.email-filter::
500	Override the default email-filter. Default value: none. See also:
501	"enable-filter-overrides". See also: "FILTER API".
502
503repo.enable-commit-graph::
504	A flag which can be used to disable the global setting
505	`enable-commit-graph'. Default value: none.
506
507repo.enable-log-filecount::
508	A flag which can be used to disable the global setting
509	`enable-log-filecount'. Default value: none.
510
511repo.enable-log-linecount::
512	A flag which can be used to disable the global setting
513	`enable-log-linecount'. Default value: none.
514
515repo.enable-remote-branches::
516	Flag which, when set to "1", will make cgit display remote branches
517	in the summary and refs views. Default value: <enable-remote-branches>.
518
519repo.enable-subject-links::
520	A flag which can be used to override the global setting
521	`enable-subject-links'. Default value: none.
522
523enable-html-serving::
524	A flag which can be used to override the global setting
525	`enable-html-serving`. Default value: none.
526
527repo.hide::
528	Flag which, when set to "1", hides the repository from the repository
529	index. The repository can still be accessed by providing a direct path.
530	Default value: "0". See also: "repo.ignore".
531
532repo.ignore::
533	Flag which, when set to "1", ignores the repository. The repository
534	is not shown in the index and cannot be accessed by providing a direct
535	path. Default value: "0". See also: "repo.hide".
536
537repo.logo::
538	Url which specifies the source of an image which will be used as a logo
539	on this repo's pages. Default value: global logo.
540
541repo.logo-link::
542	Url loaded when clicking on the cgit logo image. If unspecified the
543	calculated url of the repository index page will be used. Default
544	value: global logo-link.
545
546repo.owner-filter::
547	Override the default owner-filter. Default value: none. See also:
548	"enable-filter-overrides". See also: "FILTER API".
549
550repo.module-link::
551	Text which will be used as the formatstring for a hyperlink when a
552	submodule is printed in a directory listing. The arguments for the
553	formatstring are the path and SHA1 of the submodule commit. Default
554	value: <module-link>
555
556repo.module-link.<path>::
557	Text which will be used as the formatstring for a hyperlink when a
558	submodule with the specified subdirectory path is printed in a
559	directory listing. The only argument for the formatstring is the SHA1
560	of the submodule commit. Default value: none.
561
562repo.max-stats::
563	Override the default maximum statistics period. Valid values are equal
564	to the values specified for the global "max-stats" setting. Default
565	value: none.
566
567repo.name::
568	The value to show as repository name. Default value: <repo.url>.
569
570repo.owner::
571	A value used to identify the owner of the repository. Default value:
572	none.
573
574repo.path::
575	An absolute path to the repository directory. For non-bare repositories
576	this is the .git-directory. Default value: none.
577
578repo.readme::
579	A path (relative to <repo.path>) which specifies a file to include
580	verbatim as the "About" page for this repo. You may also specify a
581	git refspec by head or by hash by prepending the refspec followed by
582	a colon. For example, "master:docs/readme.mkd". If the value begins
583	with a colon, i.e. ":docs/readme.rst", the default branch of the
584	repository will be used. Sharing any file will expose that entire
585	directory tree to the "/about/PATH" endpoints, so be sure that there
586	are no non-public files located in the same directory as the readme
587	file. Default value: <readme>.
588
589repo.snapshots::
590	A mask of snapshot formats for this repo that cgit generates links for,
591	restricted by the global "snapshots" setting. Default value:
592	<snapshots>.
593
594repo.section::
595	Override the current section name for this repository. Default value:
596	none.
597
598repo.source-filter::
599	Override the default source-filter. Default value: none. See also:
600	"enable-filter-overrides". See also: "FILTER API".
601
602repo.url::
603	The relative url used to access the repository. This must be the first
604	setting specified for each repo. Default value: none.
605
606
607REPOSITORY-SPECIFIC CGITRC FILE
608-------------------------------
609When the option "scan-path" is used to auto-discover git repositories, cgit
610will try to parse the file "cgitrc" within any found repository. Such a
611repo-specific config file may contain any of the repo-specific options
612described above, except "repo.url" and "repo.path". Additionally, the "filter"
613options are only acknowledged in repo-specific config files when
614"enable-filter-overrides" is set to "1".
615
616Note: the "repo." prefix is dropped from the option names in repo-specific
617config files, e.g. "repo.desc" becomes "desc".
618
619
620FILTER API
621----------
622By default, filters are separate processes that are executed each time they
623are needed.  Alternative technologies may be used by prefixing the filter
624specification with the relevant string; available values are:
625
626'exec:'::
627	The default "one process per filter" mode.
628
629'lua:'::
630	Executes the script using a built-in Lua interpreter. The script is
631	loaded once per execution of cgit, and may be called multiple times
632	during cgit's lifetime, making it a good choice for repeated filters
633	such as the 'email filter'. It responds to three functions:
634
635	'filter_open(argument1, argument2, argument3, ...)'::
636		This is called upon activation of the filter for a particular
637		set of data.
638	'filter_write(buffer)'::
639		This is called whenever cgit writes data to the webpage.
640	'filter_close()'::
641		This is called when the current filtering operation is
642		completed. It must return an integer value. Usually 0
643		indicates success.
644
645	Additionally, cgit exposes to the Lua the following built-in functions:
646
647	'html(str)'::
648		Writes 'str' to the webpage.
649	'html_txt(str)'::
650		HTML escapes and writes 'str' to the webpage.
651	'html_attr(str)'::
652		HTML escapes for an attribute and writes "str' to the webpage.
653	'html_url_path(str)'::
654		URL escapes for a path and writes 'str' to the webpage.
655	'html_url_arg(str)'::
656		URL escapes for an argument and writes 'str' to the webpage.
657	'html_include(file)'::
658		Includes 'file' in webpage.
659
660
661Parameters are provided to filters as follows.
662
663about filter::
664	This filter is given a single parameter: the filename of the source
665	file to filter. The filter can use the filename to determine (for
666	example) the type of syntax to follow when formatting the readme file.
667	The about text that is to be filtered is available on standard input
668	and the filtered text is expected on standard output.
669
670commit filter::
671	This filter is given no arguments. The commit message text that is to
672	be filtered is available on standard input and the filtered text is
673	expected on standard output.
674
675email filter::
676	This filter is given two parameters: the email address of the relevent
677	author and a string indicating the originating page. The filter will
678	then receive the text string to format on standard input and is
679	expected to write to standard output the formatted text to be included
680	in the page.
681
682owner filter::
683	This filter is given no arguments.  The owner text is avilable on
684	standard input and the filter is expected to write to standard
685	output.  The output is included in the Owner column.
686
687source filter::
688	This filter is given a single parameter: the filename of the source
689	file to filter. The filter can use the filename to determine (for
690	example) the syntax highlighting mode. The contents of the source
691	file that is to be filtered is available on standard input and the
692	filtered contents is expected on standard output.
693
694auth filter::
695	The authentication filter receives 12 parameters:
696	  - filter action, explained below, which specifies which action the
697	    filter is called for
698	  - http cookie
699	  - http method
700	  - http referer
701	  - http path
702	  - http https flag
703	  - cgit repo
704	  - cgit page
705	  - cgit url
706	  - cgit login url
707	When the filter action is "body", this filter must write to output the
708	HTML for displaying the login form, which POSTs to the login url. When
709	the filter action is "authenticate-cookie", this filter must validate
710	the http cookie and return a 0 if it is invalid or 1 if it is invalid,
711	in the exit code / close function. If the filter action is
712	"authenticate-post", this filter receives POST'd parameters on
713	standard input, and should write a complete CGI response, preferably
714	with a 302 redirect, and write to output one or more "Set-Cookie"
715	HTTP headers, each followed by a newline.
716
717	Please see `filters/simple-authentication.lua` for a clear example
718	script that may be modified.
719
720
721All filters are handed the following environment variables:
722
723- CGIT_REPO_URL (from repo.url)
724- CGIT_REPO_NAME (from repo.name)
725- CGIT_REPO_PATH (from repo.path)
726- CGIT_REPO_OWNER (from repo.owner)
727- CGIT_REPO_DEFBRANCH (from repo.defbranch)
728- CGIT_REPO_SECTION (from repo.section)
729- CGIT_REPO_CLONE_URL (from repo.clone-url)
730
731If a setting is not defined for a repository and the corresponding global
732setting is also not defined (if applicable), then the corresponding
733environment variable will be unset.
734
735
736MACRO EXPANSION
737---------------
738The following cgitrc options support a simple macro expansion feature,
739where tokens prefixed with "$" are replaced with the value of a similarly
740named environment variable:
741
742- cache-root
743- include
744- project-list
745- scan-path
746
747Macro expansion will also happen on the content of $CGIT_CONFIG, if
748defined.
749
750One usage of this feature is virtual hosting, which in its simplest form
751can be accomplished by adding the following line to /etc/cgitrc:
752
753	include=/etc/cgitrc.d/$HTTP_HOST
754
755The following options are expanded during request processing, and support
756the environment variables defined in "FILTER API":
757
758- clone-url
759- repo.clone-url
760
761
762CACHE
763------
764
765All cache ttl values are in minutes. Negative ttl values indicate that a page
766type will never expire, and thus the first time a URL is accessed, the result
767will be cached indefinitely, even if the underlying git repository changes.
768Conversely, when a ttl value is zero, the cache is disabled for that
769particular page type, and the page type is never cached.
770
771
772EXAMPLE CGITRC FILE
773-------------------
774
775....
776# Enable caching of up to 1000 output entries
777cache-size=1000
778
779
780# Specify some default clone urls using macro expansion
781clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
782
783# Specify the css url
784css=/css/cgit.css
785
786
787# Show owner on index page
788enable-index-owner=1
789
790
791# Allow http transport git clone
792enable-http-clone=1
793
794
795# Show extra links for each repository on the index page
796enable-index-links=1
797
798
799# Enable ASCII art commit history graph on the log pages
800enable-commit-graph=1
801
802
803# Show number of affected files per commit on the log pages
804enable-log-filecount=1
805
806
807# Show number of added/removed lines per commit on the log pages
808enable-log-linecount=1
809
810
811# Sort branches by date
812branch-sort=age
813
814
815# Add a cgit favicon
816favicon=/favicon.ico
817
818
819# Use a custom logo
820logo=/img/mylogo.png
821
822
823# Enable statistics per week, month and quarter
824max-stats=quarter
825
826
827# Set the title and heading of the repository index page
828root-title=example.com git repositories
829
830
831# Set a subheading for the repository index page
832root-desc=tracking the foobar development
833
834
835# Include some more info about example.com on the index page
836root-readme=/var/www/htdocs/about.html
837
838
839# Allow download of tar.gz, tar.bz2 and zip-files
840snapshots=tar.gz tar.bz2 zip
841
842
843##
844## List of common mimetypes
845##
846
847mimetype.gif=image/gif
848mimetype.html=text/html
849mimetype.jpg=image/jpeg
850mimetype.jpeg=image/jpeg
851mimetype.pdf=application/pdf
852mimetype.png=image/png
853mimetype.svg=image/svg+xml
854
855
856# Highlight source code with python pygments-based highlighter
857source-filter=/var/www/cgit/filters/syntax-highlighting.py
858
859# Format markdown, restructuredtext, manpages, text files, and html files
860# through the right converters
861about-filter=/var/www/cgit/filters/about-formatting.sh
862
863##
864## Search for these files in the root of the default branch of repositories
865## for coming up with the about page:
866##
867readme=:README.md
868readme=:readme.md
869readme=:README.mkd
870readme=:readme.mkd
871readme=:README.rst
872readme=:readme.rst
873readme=:README.html
874readme=:readme.html
875readme=:README.htm
876readme=:readme.htm
877readme=:README.txt
878readme=:readme.txt
879readme=:README
880readme=:readme
881readme=:INSTALL.md
882readme=:install.md
883readme=:INSTALL.mkd
884readme=:install.mkd
885readme=:INSTALL.rst
886readme=:install.rst
887readme=:INSTALL.html
888readme=:install.html
889readme=:INSTALL.htm
890readme=:install.htm
891readme=:INSTALL.txt
892readme=:install.txt
893readme=:INSTALL
894readme=:install
895
896
897##
898## List of repositories.
899## PS: Any repositories listed when section is unset will not be
900##     displayed under a section heading
901## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
902##      and included like this:
903##        include=/etc/cgitrepos
904##
905
906
907repo.url=foo
908repo.path=/pub/git/foo.git
909repo.desc=the master foo repository
910repo.owner=fooman@example.com
911repo.readme=info/web/about.html
912
913
914repo.url=bar
915repo.path=/pub/git/bar.git
916repo.desc=the bars for your foo
917repo.owner=barman@example.com
918repo.readme=info/web/about.html
919
920
921# The next repositories will be displayed under the 'extras' heading
922section=extras
923
924
925repo.url=baz
926repo.path=/pub/git/baz.git
927repo.desc=a set of extensions for bar users
928
929repo.url=wiz
930repo.path=/pub/git/wiz.git
931repo.desc=the wizard of foo
932
933
934# Add some mirrored repositories
935section=mirrors
936
937
938repo.url=git
939repo.path=/pub/git/git.git
940repo.desc=the dscm
941
942
943repo.url=linux
944repo.path=/pub/git/linux.git
945repo.desc=the kernel
946
947# Disable adhoc downloads of this repo
948repo.snapshots=0
949
950# Disable line-counts for this repo
951repo.enable-log-linecount=0
952
953# Restrict the max statistics period for this repo
954repo.max-stats=month
955....
956
957
958BUGS
959----
960Comments currently cannot appear on the same line as a setting; the comment
961will be included as part of the value. E.g. this line:
962
963	robots=index  # allow indexing
964
965will generate the following html element:
966
967	<meta name='robots' content='index  # allow indexing'/>
968
969
970
971AUTHOR
972------
973Lars Hjemli <hjemli@gmail.com>
974Jason A. Donenfeld <Jason@zx2c4.com>