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