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, 0 insertions, 926 deletions

diff --git a/cgitrc.5.txt b/cgitrc.5.txt
deleted file mode 100644
index b05f6e9..0000000
--- a/cgitrc.5.txt
+++ /dev/null
@@ -1,926 +0,0 @@
-:man source:   cgit
-:man manual:   cgit
-
-CGITRC(5)
-========
-
-
-NAME
-----
-cgitrc - runtime configuration for cgit
-
-
-SYNOPSIS
---------
-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 '#', are ignored.
-
-
-LOCATION
---------
-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".
-
-agefile::
-	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 quite a few arguments, and data on both stdin and
-	stdout for authentication processing. Details follow later in this
-	document. If no auth-filter is specified, no authentication is
-	performed. Default value: none. See also: "FILTER API".
-
-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: "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:
-	"CACHE". Default value: "5".
-
-cache-repo-ttl::
-	Number which specifies the time-to-live, in minutes, for the cached
-	version of the repository summary page. See also: "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 "CACHE".
-
-cache-root-ttl::
-	Number which specifies the time-to-live, in minutes, for the cached
-	version of the repository index page. See also: "CACHE". Default
-	value: "5".
-
-cache-scanrc-ttl::
-	Number which specifies the time-to-live, in minutes, for the result
-	of scanning a path for git repositories. See also: "CACHE". Default
-	value: "15".
-
-case-sensitive-sort::
-	Sort items in the repo list case sensitively. Default value: "1".
-	See also: repository-sort, section-sort.
-
-cache-size::
-	The maximum number of entries in the cgit cache. When set to "0",
-	caching is disabled. See also: "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: "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:
-	"CACHE". Default value: -1".
-
-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.
-
-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: none. See
-	also: "noheader".
-
-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-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 all filter settings to be
-	overridden in repository-specific cgitrc files. Default value: none.
-
-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-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-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-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-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-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-stats::
-	Flag which, when set to "1", enables the statistics page, which
-	holds the commits-per-author table. Default value: "0". See also:
-	"repo.enable-stats", "max-stats".
-
-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-linenumbers::
-	Flag which, when set to "1", will make cgit generate linenumber links
-	for plaintext blobs printed in the tree view. Default value: "1".
-
-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".
-
-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 (i.e. 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 config-
-	file is parsed. 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. The value "0" 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::
-	Bound the coarsest period selectable on the statistics page. Valid
-	values are "week", "month", "quarter" and "year". Unset, every
-	period is offered. This option no longer enables the page, that is
-	what "enable-stats" does. Default value: none. See also:
-	"enable-stats", "repo.max-stats".
-
-mimetype.<ext>::
-	Set the mimetype for the specified filename extension. This is used
-	by the `plain` command when returning blob content.
-
-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>".
-
-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.
-
-noplainemail::
-	If set to "1" showing full author email addresses will be disabled.
-	Default value: "0".
-
-noheader::
-	Flag which, when set to "1", will make cgit omit the standard header
-	on all pages. Default value: none. See also: "embedded".
-
-project-list::
-	A list of subdirectories inside of scan-path, relative to it, that
-	should 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.
-
-renamelimit::
-	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. Be advised that only the global settings taken
-	before the scan-path directive will be applied to each repository.
-	Default value: none. See also: cache-scanrc-ttl, project-list,
-	"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-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.
-
-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".
-
-side-by-side-diffs::
-	If set to "1" shows side-by-side diffs instead of unidiffs per
-	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".
-
-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".
-
-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.
-
-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 '?r=cgit&p=tree&path=README'. Default
-	value: none.
-	NOTE: cgit has recently learned how to use PATH_INFO to achieve the
-	same kind of virtual urls, so this option will probably be deprecated.
-
-
-REPOSITORY SETTINGS
--------------------
-repo.about-filter::
-	Override the default about-filter. Default value: none. See also:
-	"enable-filter-overrides". 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: "name".
-
-repo.clone-url::
-	A list of space-separated urls which can be used to clone this repo.
-	Default value: none. See also: "MACRO EXPANSION".
-
-repo.commit-filter::
-	Override the default commit-filter. Default value: none. See also:
-	"enable-filter-overrides". 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: unset.
-
-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. Default value: none.
-
-repo.email-filter::
-	Override the default email-filter. Default value: none. See also:
-	"enable-filter-overrides". See also: "FILTER API".
-
-repo.enable-blame::
-	A flag which can be used to disable the global setting
-	`enable-blame'. Default value: none.
-
-repo.enable-commit-graph::
-	A flag which can be used to disable the global setting
-	`enable-commit-graph'. Default value: none.
-
-repo.enable-follow-links::
-	A flag which can be used to disable the global setting
-	`enable-follow-links'. Default value: none.
-
-repo.enable-gitmodules-links::
-	A flag which can be used to override the global setting
-	`enable-gitmodules-links'. Default value: none.
-
-repo.enable-html-serving::
-	A flag which can be used to override the global setting
-	`enable-html-serving`. Default value: none.
-
-repo.enable-log-filecount::
-	A flag which can be used to disable the global setting
-	`enable-log-filecount'. Default value: none.
-
-repo.enable-log-linecount::
-	A flag which can be used to disable the global setting
-	`enable-log-linecount'. Default value: none.
-
-repo.enable-remote-branches::
-	Flag which, when set to "1", will make cgit display remote branches
-	in the summary and refs views. Default value: <enable-remote-branches>.
-
-repo.enable-stats::
-	A flag which can be used to override the global setting
-	`enable-stats'. Default value: none.
-
-repo.enable-subject-links::
-	A flag which can be used to override the global setting
-	`enable-subject-links'. Default value: none.
-
-repo.extra-head-content::
-	This value will be added verbatim to the head section of each page
-	displayed for this repo. Default value: none.
-
-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: global 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: global logo-link.
-
-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.max-stats::
-	Override the default maximum statistics period. Valid values are equal
-	to the values specified for the global "max-stats" setting. 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. 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 giving in 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:
-	none.
-
-repo.snapshots::
-	A mask of snapshot formats for this repo that cgit generates links for,
-	restricted by the global "snapshots" setting. Default value:
-	<snapshots>.
-
-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.source-filter::
-	Override the default source-filter. Default value: none. See also:
-	"enable-filter-overrides". 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; 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 referer
-	  - http path
-	  - 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
-
-
-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, and the page type is never cached.
-
-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.
-
-
-BUGS
-----
-Comments currently cannot appear on the same line as a setting; the comment
-will be included as part of the value. E.g. this line:
-
-	robots=index  # allow indexing
-
-will generate the following html element:
-
-	<meta name='robots' content='index  # allow indexing'/>
-
-
-
-AUTHOR
-------
-Lars Hjemli <hjemli@gmail.com>
-Jason A. Donenfeld <Jason@zx2c4.com>