Convert the manual page to plain `MANUAL.txt`

Beyond the format change, the documented defaults and inheritance
notes now match what the code does.

1 file changed, 903 insertions, 0 deletions

diff --git a/MANUAL.txt b/MANUAL.txt
new file mode 100644
index 0000000..4c924cf
--- /dev/null
+++ b/MANUAL.txt
@@ -0,0 +1,903 @@
+cgitrc - runtime configuration for cgit
+=======================================
+
+Cgitrc contains all runtime settings for cgit, including the list of git
+repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
+lines, and lines starting with '#' or ';', are ignored, and so is a line
+carrying no '='. A comment cannot share a line with a setting, since everything
+after the '=' belongs to the value. A NAME cgit does not recognise is ignored
+with a warning on stderr, which the web server collects in its error log.
+
+The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
+runtime, cgit will consult the environment variable CGIT_CONFIG and, if defined,
+use its value instead.
+
+
+Global settings
+---------------
+
+about-filter::
+	Specifies a command which will be invoked to format the content of about
+	pages (both top-level and for each repository). The command will get the
+	content of the about-file on its STDIN, the name of the file as the
+	first argument, and the STDOUT from the command will be included
+	verbatim on the about page. Default value: none. When no about-filter is
+	set, the readme is escaped and served as plain text. A bundled Lua
+	filter, about-render.lua, renders markdown, man pages and plain text
+	when about-filter points at it. See also: "Filter API".
+
+age-file::
+	Specifies a path, relative to each repository path, which can be used to
+	specify the date and time of the youngest commit in the repository. The
+	first line in the file is used as input to the "parse_date" function in
+	libgit. Recommended timestamp-format is "yyyy-mm-dd hh:mm:ss". You may
+	want to generate this file from a post-receive hook. Default value:
+	"info/web/last-modified".
+
+auth-filter::
+	Specifies a command that will be invoked for authenticating repository
+	access. Receives 12 arguments, with request data on stdin and its
+	answer on stdout, as described under "Filter API". If no auth-filter is
+	specified, no authentication is performed. Default value: none.
+
+branch-sort::
+	Flag which, when set to "age", enables date ordering in the branch ref
+	list, and when set to "name" enables ordering by branch name. Default
+	value: "name".
+
+cache-about-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of the repository about page. See also: "The cache". Default
+	value: "15".
+
+cache-dynamic-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of repository pages accessed without a fixed SHA1. See also:
+	"The cache". Default value: "5".
+
+cache-index-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of the repository index page. See also: "The cache". Default
+	value: "5".
+
+cache-root::
+	Path used to store the cgit cache entries. Default value:
+	"/var/cache/cgit". See also: "Macro expansion" and the note on ownership
+	under "The cache".
+
+cache-scan-ttl::
+	Number which specifies the time-to-live, in minutes, for the result of
+	scanning a path for git repositories. See also: "The cache". Default
+	value: "15".
+
+cache-size::
+	The maximum number of entries in the cgit cache. When set to "0",
+	caching is disabled. See also: "The cache". Default value: "0".
+
+cache-snapshot-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of snapshots. A snapshot requested with a fixed object id uses
+	"cache-static-ttl" instead, since its content can never change. See
+	also: "The cache". Default value: "5".
+
+cache-static-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of repository pages accessed with a fixed SHA1. See also: "The
+	cache". Default value: "-1".
+
+cache-summary-ttl::
+	Number which specifies the time-to-live, in minutes, for the cached
+	version of the repository summary page. See also: "The cache". Default
+	value: "5".
+
+case-sensitive-sort::
+	Sort items in the repo list case sensitively. Default value: "1". See
+	also: repository-sort, section-sort.
+
+clone-prefix::
+	Space-separated list of common prefixes which, when combined with a
+	repository url, generates valid clone urls for the repository. This
+	setting is only used if `repo.clone-url` is unspecified. Default value:
+	none.
+
+clone-url::
+	Space-separated list of clone-url templates. This setting is only used
+	if `repo.clone-url` is unspecified. Default value: none. See also:
+	"Macro expansion", "Filter API".
+
+commit-filter::
+	Specifies a command which will be invoked to format commit messages. The
+	command will get the message on its STDIN, and the STDOUT from the
+	command will be included verbatim as the commit message, i.e. this can
+	be used to implement bugtracker integration. Default value: none. See
+	also: "Filter API".
+
+commit-sort::
+	Flag which, when set to "date", enables strict date ordering in the
+	commit log, and when set to "topo" enables strict topological ordering.
+	If unset, the default ordering of "git log" is used. Default value:
+	unset.
+
+css::
+	Url which specifies the css document to include in all cgit pages.
+	Default value: "/cgit.css". May be given multiple times, each css URL
+	path is added in the head section of the document in turn. Setting this
+	to an empty string will disable generation of the link to this file in
+	the head section.
+
+date-format::
+	Format used for the calendar dates in the age columns of the log, refs
+	and index pages, both when "enable-relative-dates" is off and when a log
+	entry is too old to be shown as an age. Accepts the same names as git's
+	--date option: "default", "human", "iso" (or "iso8601"), "iso-strict"
+	(or "iso8601-strict"), "raw", "relative", "rfc" (or "rfc2822"), "short"
+	and "unix", each of which may carry a "-local" suffix, plus
+	"format:<strftime>" for an arbitrary layout. An unrecognised value is
+	ignored. Dates elsewhere, such as the author and committer lines on the
+	commit page, are always ISO 8601 and are not affected, nor are the exact
+	timestamps shown on hover. Default value: "short". See also:
+	"local-time".
+
+email-filter::
+	Specifies a command which will be invoked to format names and email
+	address of committers, authors, and taggers, as represented in various
+	places throughout the cgit interface. This command will receive an email
+	address and an origin page string as its command line arguments, and the
+	text to format on STDIN. It is to write the formatted text back out onto
+	STDOUT. Default value: none. See also: "Filter API".
+
+embedded::
+	Flag which, when set to "1", will make cgit generate a html fragment
+	suitable for embedding in other html pages. Default value: "0". See
+	also: "enable-header".
+
+enable-blame::
+	Flag which, when set to "1", will allow cgit to provide a "blame" page
+	for files, and will make it generate links to that page in appropriate
+	places. Default value: "0".
+
+enable-cache-list::
+	Flag which, when set to "1", exposes the "ls_cache" page. That page
+	lists the cache directory path and the URLs of requests other visitors
+	made, so it is disabled by default and should stay off on any instance
+	where that disclosure matters. Default value: "0".
+
+enable-commit-graph::
+	Flag which, when set to "1", will make cgit print an ASCII-art commit
+	history graph to the left of the commit messages in the repository log
+	page. Default value: "0".
+
+enable-filter-overrides::
+	Flag which, when set to "1", allows the filter settings to be set per
+	repository, both as "repo.<filter>" settings in the main cgitrc and
+	inside repository-specific cgitrc files. When unset, such settings are
+	ignored with a warning. Default value: "0".
+
+enable-follow-links::
+	Flag which, when set to "1", allows users to follow a file in the log
+	view. Default value: "0".
+
+enable-git-config::
+	Flag which, when set to "1", will allow cgit to use git config to set
+	any repo specific settings. This option is used in conjunction with
+	"scan-path", and must be defined prior, to augment repo-specific
+	settings. The keys gitweb.owner, gitweb.category, and gitweb.description
+	will map to the cgit keys repo.owner, repo.section, and repo.desc
+	respectively. All git config keys that begin with "cgit." will be mapped
+	to the corresponding "repo." key in cgit. Default value: "0". See also:
+	scan-path, section-from-path.
+
+enable-gitmodules-links::
+	Flag which, when set to "1", makes submodule listings derive a link from
+	the url recorded in the .gitmodules file at the shown revision, for
+	submodules that no module-link template covers. The url is first
+	matched, by its trailing path components, against the repositories
+	served by this cgit instance, so ssh, file and relative urls still get a
+	link when their target is hosted here, and the commit hash then links to
+	the target repository's commit page. Otherwise a plain http or https url
+	is linked as it is, an ssh url to a well-known public host is rewritten
+	to its https form, and any other url is left unlinked and shown as a
+	tooltip instead. Default value: "0". See also:
+	"repo.enable-gitmodules-links".
+
+enable-header::
+	Flag which, when set to "0", makes cgit omit the standard header on all
+	pages. Default value: "1". See also: "embedded".
+
+enable-html-serving::
+	Flag which, when set to "1", will allow the /plain handler to serve
+	mimetype headers that result in the file being treated as HTML by the
+	browser. When set to "0", such file types are returned instead as
+	text/plain or application/octet-stream. Default value: "0". See also:
+	"repo.enable-html-serving".
+
+enable-http-clone::
+	If set to "1", cgit will act as a dumb HTTP endpoint for git clones. You
+	can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url to
+	expose this feature. If you use an alternate way of serving git
+	repositories, you may wish to disable this. Default value: "1".
+
+enable-index-links::
+	Flag which, when set to "1", will make cgit generate extra links for
+	each repo in the repository index (specifically, to the "summary",
+	"commit" and "tree" pages). Default value: "0".
+
+enable-index-owner::
+	Flag which, when set to "1", will make cgit display the owner of each
+	repo in the repository index. Default value: "1".
+
+enable-log-filecount::
+	Flag which, when set to "1", will make cgit print the number of modified
+	files for each commit on the repository log page. Default value: "0".
+
+enable-log-linecount::
+	Flag which, when set to "1", will make cgit print the number of added
+	and removed lines for each commit on the repository log page. Default
+	value: "0".
+
+enable-plain-email::
+	Flag which, when set to "0", hides the full author, committer and tagger
+	email addresses wherever they would be shown beside the name. Default
+	value: "1".
+
+enable-relative-dates::
+	Flag which, when set to "1", shows the age columns of the log, refs and
+	index pages as an elapsed time such as "3 days" rather than a calendar
+	date. When set to "0" those columns always show a date, formatted
+	according to "date-format". Default value: "1".
+
+enable-remote-branches::
+	Flag which, when set to "1", will make cgit display remote branches in
+	the summary and refs views. Default value: "0". See also:
+	"repo.enable-remote-branches".
+
+enable-subject-links::
+	Flag which, when set to "1", will make cgit use the subject of the
+	parent commit as link text when generating links to parent commits in
+	commit view. Default value: "0". See also: "repo.enable-subject-links".
+
+enable-tree-group-dirs::
+	Flag which, when set to "1", makes the tree view list all directories
+	first, sorted, followed by the files. When set to "0", entries appear in
+	git's own order, with directories and files intermixed by name. Default
+	value: "0".
+
+enable-tree-linenumbers::
+	Flag which, when set to "1", will make cgit generate linenumber links
+	for plaintext blobs printed in the tree view. Default value: "1".
+
+favicon::
+	Url used as link to the icon for cgit. Any path works, but keeping the
+	value "/favicon.ico" is still worthwhile, since clients that do not
+	parse the page head probe that path directly. Default value:
+	"/favicon.ico".
+
+footer::
+	The content of the file specified with this option will be included
+	verbatim at the bottom of all pages (it replaces the standard "generated
+	by..." message). Default value: none.
+
+head-include::
+	The content of the file specified with this option will be included
+	verbatim in the html HEAD section on all pages. Default value: none.
+
+header::
+	The content of the file specified with this option will be included
+	verbatim at the top of all pages. Default value: none.
+
+include::
+	Name of a configfile to include before the rest of the current
+	configfile is parsed. Includes may nest eight levels deep, and anything
+	deeper is ignored. Default value: none. See also: "Macro expansion".
+
+js::
+	Url which specifies the javascript script document to include in all
+	cgit pages. Default value: "/cgit.js". Setting this to an empty string
+	will disable generation of the link to this file in the head section.
+
+local-time::
+	Flag which, if set to "1", makes cgit print commit and tag times in the
+	servers timezone. Default value: "0". See also: "date-format".
+
+logo::
+	Url which specifies the source of an image which will be used as a logo
+	on all cgit pages. Default value: "/cgit.png".
+
+logo-link::
+	Url loaded when clicking on the cgit logo image. If unspecified the
+	calculated url of the repository index page will be used. Default value:
+	none.
+
+max-atom-items::
+	Specifies the number of items to display in atom feeds view. Default
+	value: "10".
+
+max-blob-size::
+	Specifies the maximum size in KBytes of a blob that cgit will read into
+	memory to serve. It caps both the HTML blob view and the raw "plain" and
+	"blob" output, and a larger object is refused rather than loaded whole.
+	Default value: "10240" (10 MB). Set to "0" to disable the limit.
+
+max-commit-count::
+	Specifies the number of entries to list per page in "log" view. Default
+	value: "50".
+
+max-diff-files::
+	If a commit changes more files than this, the "commit" and "diff" views
+	show only the diffstat, where each file links to its own diff page. The
+	"rawdiff" and "patch" views are never limited. Default value: "200". Set
+	to "0" to always render every file inline.
+
+max-diff-lines::
+	If a single file's diff spans more lines than this, the whole-commit
+	views print a note in its place linking to the file's own diff page,
+	which always renders in full. Default value: "1000". Set to "0" to
+	always render oversized files inline.
+
+max-message-length::
+	Specifies the maximum number of commit message characters to display in
+	"log" view. Default value: "80".
+
+max-patch-count::
+	Specifies the maximum number of commits emitted as a series by the
+	"patch" view when an explicit revision range is requested. A single
+	commit is unaffected. Default value: "50". Set to "0" for no limit.
+
+max-ref-count::
+	Specifies the number of branches and tags to list per section on the
+	"refs" view, and per page on the dedicated branch and tag pages that its
+	overflow links lead to. Default value: "200". Set to "0" to list every
+	ref on one page.
+
+max-repo-count::
+	Specifies the number of entries to list per page on the repository index
+	page. A value of "0" or less shows all repositories without limitation.
+	Default value: "50".
+
+max-repodesc-length::
+	Specifies the maximum number of repo description characters to display
+	on the repository index page. Default value: "80".
+
+max-stats::
+	Enable the statistics page, which holds the commits-per-author table,
+	and set the coarsest period it offers. Valid values are "week", "month",
+	"quarter" and "year", each of which also offers the finer periods before
+	it. If unspecified, statistics are disabled. Default value: none. See
+	also: "repo.max-stats".
+
+mimetype-file::
+	Specifies the file to use for automatic mimetype lookup. If specified
+	then this field is used as a fallback when no "mimetype.<ext>" match is
+	found. If unspecified then no such lookup is performed. The typical file
+	to use on a Linux system is /etc/mime.types. The format of the file must
+	comply to:
+	- a comment line is an empty line or a line starting with a hash (#),
+	  optionally preceded by whitespace
+	- a non-comment line starts with the mimetype (like image/png), followed
+	  by one or more file extensions (like jpg), all separated by whitespace
+	Default value: none. See also: "mimetype.<ext>".
+
+mimetype.<ext>::
+	Set the mimetype for the specified filename extension. This is used by
+	the `plain` command when returning blob content.
+
+module-link::
+	Text which will be used as the formatstring for a hyperlink when a
+	submodule is printed in a directory listing. The arguments for the
+	formatstring are the name of the submodule directory and the SHA1 of the
+	submodule commit. Default value: none.
+
+project-list::
+	A list of subdirectories inside of scan-path, relative to it, that
+	should be loaded as git repositories. This must be defined prior to
+	scan-path. Default value: none. See also: scan-path, "Macro expansion".
+
+readme::
+	Text which will be used as default value for "repo.readme". Multiple
+	config keys may be specified, and cgit will use the first found file in
+	this list. This is useful in conjunction with scan-path. Default value:
+	none. See also: scan-path, repo.readme.
+
+remove-suffix::
+	If set to "1" and scan-path is enabled, if any repositories are found
+	with a suffix of ".git", this suffix will be removed for the url and
+	name. This must be defined prior to scan-path. Default value: "0". See
+	also: scan-path.
+
+rename-limit::
+	Maximum number of files to consider when detecting renames. The value
+	"-1" uses the compiletime value in git (for further info, look at `man
+	git-diff`). Default value: "-1".
+
+repository-sort::
+	The way in which repositories in each section are sorted. Valid values
+	are "name" for sorting by the repo name or "age" for sorting by the most
+	recently updated repository. Default value: "name". See also: section,
+	case-sensitive-sort, section-sort.
+
+robots::
+	Text used as content for the "robots" meta-tag. Default value: "index,
+	nofollow".
+
+root-desc::
+	Text printed below the heading on the repository index page. Default
+	value: "a fast webinterface for the git dscm".
+
+root-readme::
+	The content of the file specified with this option will be included
+	verbatim below the "about" link on the repository index page. Default
+	value: none.
+
+root-title::
+	Text printed as heading on the repository index page. Default value:
+	"Git repository browser".
+
+scan-hidden-path::
+	If set to "1" and scan-path is enabled, scan-path will recurse into
+	directories whose name starts with a period ('.'). Otherwise, scan-path
+	will stay away from such directories (considered as "hidden"). Note that
+	this does not apply to the ".git" directory in non-bare repos. This must
+	be defined prior to scan-path. Default value: "0". See also: scan-path.
+
+scan-path::
+	A path which will be scanned for repositories. If caching is enabled,
+	the result will be cached as a cgitrc include-file in the cache
+	directory. If project-list has been defined prior to scan-path,
+	scan-path loads only the directories listed in the file pointed to by
+	project-list. A repository containing a file named "noweb" is skipped,
+	the reverse of what "strict-export" checks. Be advised that only the
+	global settings taken before the scan-path directive will be applied to
+	each repository. That holds for every setting a repository inherits,
+	among them section, snapshots, readme, the filters and the enable flags,
+	not only the entries that say so explicitly. Default value: none. See
+	also: cache-scan-ttl, project-list, strict-export, "Macro expansion".
+
+section::
+	The name of the current repository section. All repositories defined
+	after this option will inherit the current section name. Default value:
+	none.
+
+section-from-path::
+	A number which, if defined prior to scan-path, specifies how many path
+	elements from each repo path to use as a default section name. If
+	negative, cgit will discard the specified number of path elements above
+	the repo directory. Default value: "0".
+
+section-sort::
+	Flag which, when set to "1", will sort the sections on the repository
+	listing by name, along with the repositories within each section. Set
+	this flag to "0" to preserve the order in the cgitrc file. Default
+	value: "0". See also: section, case-sensitive-sort, repository-sort.
+
+side-by-side-diffs::
+	If set to "1" shows side-by-side diffs instead of unidiffs by default.
+	Default value: "0".
+
+snapshots::
+	Text which specifies the default set of snapshot formats that cgit
+	generates links for. The value is a space-separated list of zero or more
+	of the values "tar", "tar.gz", "tar.bz2", "tar.lz", "tar.xz", "tar.zst"
+	and "zip". The special value "all" enables all snapshot formats. Default
+	value: none. All compressors use default settings. Some settings can be
+	influenced with environment variables, for example set ZSTD_CLEVEL=10 in
+	web server environment for higher (but slower) zstd compression.
+
+source-filter::
+	Specifies a command which will be invoked to format plaintext blobs in
+	the tree view. The command will get the blob content on its STDIN and
+	the name of the blob as its only command line argument. The STDOUT from
+	the command will be included verbatim as the blob contents, i.e. this
+	can be used to implement e.g. syntax highlighting. When no source-filter
+	is configured, cgit serves the text plain. A ready syntax highlighter
+	using the Scintillua lexer collection ships as
+	custom/extensions/syntax-highlight.lua, see the comments in that file
+	for its dependencies. Default value: none. See also: "Filter API".
+
+strict-export::
+	Filename which, if specified, needs to be present within the repository
+	for cgit to allow access to that repository. This can be used to emulate
+	gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
+	repositories to match those exported by git-daemon. This option must be
+	defined prior to scan-path. Default value: none. See also: scan-path.
+
+summary-branches::
+	Specifies the number of branches to display in the repository "summary"
+	view. Default value: "10".
+
+summary-log::
+	Specifies the number of log entries to display in the repository
+	"summary" view. Default value: "10".
+
+summary-tags::
+	Specifies the number of tags to display in the repository "summary"
+	view. Default value: "10".
+
+virtual-root::
+	Url which, if specified, will be used as root for all cgit links. It
+	will also cause cgit to generate 'virtual urls', i.e. urls like
+	'/cgit/tree/README' as opposed to '?url=cgit/tree/README'. Default
+	value: none.
+
+
+Repository settings
+-------------------
+
+repo.about-filter::
+	Override the default about-filter. Only honoured when
+	"enable-filter-overrides" is set. Default value: <about-filter>. See
+	also: "Filter API".
+
+repo.branch-sort::
+	Flag which, when set to "age", enables date ordering in the branch ref
+	list, and when set to "name" enables ordering by branch name. Default
+	value: <branch-sort>.
+
+repo.clone-url::
+	A list of space-separated urls which can be used to clone this repo.
+	Default value: <clone-url>. See also: "Macro expansion".
+
+repo.commit-filter::
+	Override the default commit-filter. Only honoured when
+	"enable-filter-overrides" is set. Default value: <commit-filter>. See
+	also: "Filter API".
+
+repo.commit-sort::
+	Flag which, when set to "date", enables strict date ordering in the
+	commit log, and when set to "topo" enables strict topological ordering.
+	If unset, the default ordering of "git log" is used. Default value:
+	<commit-sort>.
+
+repo.defbranch::
+	The name of the default branch for this repository. If no such branch
+	exists in the repository, the first branch name (when sorted) is used as
+	default instead. Default value: branch pointed to by HEAD, or "master"
+	if there is no suitable HEAD.
+
+repo.desc::
+	The value to show as repository description. When repositories are found
+	by scan-path the description file inside the repository is read as a
+	fallback, unless it still holds git's "Unnamed repository" boilerplate.
+	Default value: "[no description]".
+
+repo.email-filter::
+	Override the default email-filter. Only honoured when
+	"enable-filter-overrides" is set. Default value: <email-filter>. See
+	also: "Filter API".
+
+repo.enable-blame::
+	A flag which can be used to override the global setting "enable-blame".
+	Default value: <enable-blame>.
+
+repo.enable-commit-graph::
+	A flag which can be used to override the global setting
+	"enable-commit-graph". Default value: <enable-commit-graph>.
+
+repo.enable-follow-links::
+	A flag which can be used to override the global setting
+	"enable-follow-links". Default value: <enable-follow-links>.
+
+repo.enable-gitmodules-links::
+	A flag which can be used to override the global setting
+	"enable-gitmodules-links". Default value: <enable-gitmodules-links>.
+
+repo.enable-html-serving::
+	A flag which can be used to override the global setting
+	"enable-html-serving". Default value: <enable-html-serving>.
+
+repo.enable-log-filecount::
+	A flag which can be used to override the global setting
+	"enable-log-filecount". Default value: <enable-log-filecount>.
+
+repo.enable-log-linecount::
+	A flag which can be used to override the global setting
+	"enable-log-linecount". Default value: <enable-log-linecount>.
+
+repo.enable-remote-branches::
+	A flag which can be used to override the global setting
+	"enable-remote-branches". Default value: <enable-remote-branches>.
+
+repo.enable-subject-links::
+	A flag which can be used to override the global setting
+	"enable-subject-links". Default value: <enable-subject-links>.
+
+repo.head-content::
+	This value will be added verbatim to the html HEAD section of each page
+	displayed for this repo. Default value: none. See also: "head-include".
+
+repo.hide::
+	Flag which, when set to "1", hides the repository from the repository
+	index. The repository can still be accessed by providing a direct path.
+	Default value: "0". See also: "repo.ignore".
+
+repo.ignore::
+	Flag which, when set to "1", ignores the repository. The repository is
+	not shown in the index and cannot be accessed by providing a direct
+	path. Default value: "0". See also: "repo.hide".
+
+repo.logo::
+	Url which specifies the source of an image which will be used as a logo
+	on this repo's pages. Default value: <logo>.
+
+repo.logo-link::
+	Url loaded when clicking on the cgit logo image. If unspecified the
+	calculated url of the repository index page will be used. Default value:
+	<logo-link>.
+
+repo.max-stats::
+	Override the default maximum statistics period. Valid values are equal
+	to the values specified for the global "max-stats" setting, and a value
+	of "0" disables the statistics page for this repository. Default value:
+	<max-stats>.
+
+repo.module-link::
+	Text which will be used as the formatstring for a hyperlink when a
+	submodule is printed in a directory listing. The arguments for the
+	formatstring are the name of the submodule directory and the SHA1 of the
+	submodule commit. Default value: <module-link>.
+
+repo.module-link.<path>::
+	Text which will be used as the formatstring for a hyperlink when a
+	submodule with the specified subdirectory path is printed in a directory
+	listing. The only argument for the formatstring is the SHA1 of the
+	submodule commit. Default value: none.
+
+repo.name::
+	The value to show as repository name. Default value: <repo.url>.
+
+repo.owner::
+	A value used to identify the owner of the repository. When repositories
+	are found by scan-path the name of the repository directory's owner, as
+	recorded in the password database, is used as a fallback. Default value:
+	none.
+
+repo.path::
+	An absolute path to the repository directory. For non-bare repositories
+	this is the .git-directory. Default value: none.
+
+repo.readme::
+	A path (relative to <repo.path>) which specifies a file to include
+	verbatim as the "About" page for this repo. You may also specify a git
+	refspec by head or by hash by prepending the refspec followed by a
+	colon. For example, "master:docs/readme.mkd". If the value begins with a
+	colon, i.e. ":docs/readme.rst", the head given in the query or the
+	default branch of the repository will be used. Sharing any file will
+	expose that entire directory tree to the "/about/PATH" endpoints, so be
+	sure that there are no non-public files located in the same directory as
+	the readme file. Default value: <readme>.
+
+repo.section::
+	Override the current section name for this repository. Default value:
+	<section>.
+
+repo.snapshot-prefix::
+	Prefix to use for snapshot links instead of the repository basename. For
+	example, the "linux-stable" repository may wish to set this to "linux"
+	so that snapshots are in the format "linux-3.15.4" instead of
+	"linux-stable-3.15.4". Default value: <empty> meaning to use the
+	repository basename.
+
+repo.snapshots::
+	A mask of snapshot formats for this repo that cgit generates links for.
+	It is intersected with the global "snapshots" setting, so a repository
+	can withhold formats but never offer one the global setting does not.
+	Default value: <snapshots>.
+
+repo.source-filter::
+	Override the default source-filter. Only honoured when
+	"enable-filter-overrides" is set. Default value: <source-filter>. See
+	also: "Filter API".
+
+repo.url::
+	The relative url used to access the repository. This must be the first
+	setting specified for each repo. Default value: none.
+
+
+Repository-specific cgitrc file
+-------------------------------
+
+When the option "scan-path" is used to auto-discover git repositories, cgit will
+try to parse the file "cgitrc" within any found repository. Such a repo-specific
+config file may contain any of the repo-specific options described above, except
+"repo.url" and "repo.path". Additionally, the "filter" options are only
+acknowledged in repo-specific config files when "enable-filter-overrides" is set
+to "1".
+
+Note: the "repo." prefix is dropped from the option names in repo-specific
+config files, e.g. "repo.desc" becomes "desc".
+
+
+Filter API
+----------
+
+By default, filters are separate processes that are executed each time they are
+needed. Alternative technologies may be used by prefixing the filter
+specification with the relevant string. The available values are:
+
+'exec:'::
+	The default "one process per filter" mode.
+
+'lua:'::
+	Executes the script using a built-in Lua interpreter. The script is
+	loaded once per execution of cgit, and may be called multiple times
+	during cgit's lifetime, making it a good choice for repeated filters
+	such as the 'email filter'. It responds to three functions:
+
+	'filter_open(argument1, argument2, argument3, ...)'::
+		This is called upon activation of the filter for a particular
+		set of data.
+	'filter_write(buffer)'::
+		This is called whenever cgit writes data to the webpage.
+	'filter_close()'::
+		This is called when the current filtering operation is
+		completed. It must return an integer value. Usually 0 indicates
+		success.
+
+	Additionally, cgit exposes to the Lua the following built-in functions:
+
+	'html(str)'::
+		Writes 'str' to the webpage.
+	'html_txt(str)'::
+		HTML escapes and writes 'str' to the webpage.
+	'html_attr(str)'::
+		HTML escapes for an attribute and writes 'str' to the webpage.
+	'html_url_path(str)'::
+		URL escapes for a path and writes 'str' to the webpage.
+	'html_url_arg(str)'::
+		URL escapes for an argument and writes 'str' to the webpage.
+	'html_include(file)'::
+		Includes 'file' in webpage.
+
+
+Parameters are provided to filters as follows.
+
+about filter::
+	This filter is given a single parameter: the filename of the source file
+	to filter. The filter can use the filename to determine (for example)
+	the type of syntax to follow when formatting the readme file. The about
+	text that is to be filtered is available on standard input and the
+	filtered text is expected on standard output.
+
+auth filter::
+	The authentication filter receives 12 parameters:
+	  - filter action, explained below, which specifies which action the
+	    filter is called for
+	  - http cookie
+	  - http method
+	  - http query string
+	  - http referer
+	  - http path
+	  - http host
+	  - http https flag
+	  - cgit repo
+	  - cgit page
+	  - cgit url
+	  - cgit login url
+	When the filter action is "body", this filter must write to output the
+	HTML for displaying the login form, which POSTs to the login url. When
+	the filter action is "authenticate-cookie", this filter must validate
+	the http cookie and return a 0 if it is invalid or 1 if it is valid, in
+	the exit code / close function. If the filter action is
+	"authenticate-post", this filter receives POST'd parameters on standard
+	input, and should write a complete CGI response, preferably with a 302
+	redirect, and write to output one or more "Set-Cookie" HTTP headers,
+	each followed by a newline.
+
+	See `custom/extensions/auth-inline.lua` for a ready to modify example
+	that keeps its user list inline, or `custom/extensions/auth-file.lua`
+	for the same filter reading its users from files on disk.
+
+commit filter::
+	This filter is given no arguments. The commit message text that is to be
+	filtered is available on standard input and the filtered text is
+	expected on standard output.
+
+email filter::
+	This filter is given two parameters: the email address of the relevant
+	author and a string indicating the originating page. The filter will
+	then receive the text string to format on standard input and is expected
+	to write to standard output the formatted text to be included in the
+	page.
+
+source filter::
+	This filter is given a single parameter: the filename of the source file
+	to filter. The filter can use the filename to determine (for example)
+	the syntax highlighting mode. The contents of the source file that is to
+	be filtered is available on standard input and the filtered contents is
+	expected on standard output.
+
+
+All filters are handed the following environment variables:
+
+- CGIT_REPO_URL (from repo.url)
+- CGIT_REPO_NAME (from repo.name)
+- CGIT_REPO_PATH (from repo.path)
+- CGIT_REPO_OWNER (from repo.owner)
+- CGIT_REPO_DEFBRANCH (from repo.defbranch)
+- CGIT_REPO_SECTION (from repo.section)
+- CGIT_REPO_CLONE_URL (from repo.clone-url)
+
+If a setting is not defined for a repository and the corresponding global
+setting is also not defined (if applicable), then the corresponding environment
+variable will be unset.
+
+
+Macro expansion
+---------------
+
+The following cgitrc options support a simple macro expansion feature, where
+tokens prefixed with "$" are replaced with the value of a similarly named
+environment variable:
+
+- cache-root
+- include
+- project-list
+- scan-path
+
+Macro expansion will also happen on the content of $CGIT_CONFIG, if defined.
+
+The set of available variables is not fixed by cgit. The options above are
+expanded while the configuration is parsed, against whatever environment the web
+server hands the cgit process, so any variable the server sets can be used. A
+CGI server provides the standard request variables, among them $HTTP_HOST,
+$HTTPS, $PATH_INFO, $QUERY_STRING, $REQUEST_METHOD, $SCRIPT_NAME, $SERVER_NAME
+and $SERVER_PORT, and server directives such as SetEnv (Apache), fastcgi_param
+(nginx) or setenv.add-environment (lighttpd) can add anything else. Note that
+cgit unsets $HOME and $XDG_CONFIG_HOME before reading its configuration, so
+those two never expand.
+
+One usage of this feature is virtual hosting, which in its simplest form can be
+accomplished by adding the following line to /etc/cgitrc:
+
+	include=/etc/cgitrc.d/$HTTP_HOST
+
+The following options are expanded later, during request processing, and
+additionally support the seven CGIT_REPO_* variables defined in "Filter API":
+
+- clone-url
+- repo.clone-url
+
+
+The cache
+---------
+
+All cache ttl values are in minutes. Negative ttl values indicate that a page
+type will never expire, and thus the first time a URL is accessed, the result
+will be cached indefinitely, even if the underlying git repository changes.
+Conversely, when a ttl value is zero, the cache is disabled for that particular
+page type.
+
+The cache directory holds one file per slot plus transient lock files, all
+created by cgit itself. Create the directory ahead of time, owned by the account
+the web server runs cgit as, with mode 0700. cgit creates its files by name
+without guarding against links planted beside them, so a directory other
+accounts can write to would let those accounts redirect the writes. A directory
+other accounts can read exposes every cached page along with the URLs visitors
+asked for.
+
+
+Signatures
+----------
+
+Cgit can host .asc signatures corresponding to various snapshot formats, through
+use of git notes. For example, the following command may be used to add a
+signature to a .tar.xz archive:
+
+    git notes --ref=refs/notes/signatures/tar.xz add -C "$(
+	gpg --output - --armor --detach-sign cgit-1.1.tar.xz |
+	git hash-object -w --stdin
+    )" v1.1
+
+If it is instead desirable to attach a signature of the underlying .tar, this
+will be linked, as a special case, beside a .tar.* link that does not have its
+own signature. For example, a signature of a tarball of the latest tag might be
+added with a similar command:
+
+    tag="$(git describe --abbrev=0)"
+    git notes --ref=refs/notes/signatures/tar add -C "$(
+        git archive --format tar --prefix "cgit-${tag#v}/" "$tag" |
+        gpg --output - --armor --detach-sign |
+        git hash-object -w --stdin
+    )" "$tag"
+
+Since git-archive(1) is expected to produce stable output between versions, this
+allows one to generate a long-term signature of the contents of a given tag.