'\" t
.\"     Title: cgitrc
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/07/2024
.\"    Manual: cgit
.\"    Source: cgit
.\"  Language: English
.\"
.TH "CGITRC" "5" "10/07/2024" "cgit" "cgit"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cgitrc \- runtime configuration for cgit
.SH "SYNOPSIS"
.sp
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 \fI#\fR, are ignored\&.
.SH "LOCATION"
.sp
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\&.
.SH "GLOBAL SETTINGS"
.PP
about\-filter
.RS 4
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\&. See also: "FILTER API"\&.
.RE
.PP
agefile
.RS 4
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"\&.
.RE
.PP
auth\-filter
.RS 4
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"\&.
.RE
.PP
branch\-sort
.RS 4
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"\&.
.RE
.PP
cache\-about\-ttl
.RS 4
Number which specifies the time\-to\-live, in minutes, for the cached version of the repository about page\&. See also: "CACHE"\&. Default value: "15"\&.
.RE
.PP
cache\-dynamic\-ttl
.RS 4
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"\&.
.RE
.PP
cache\-repo\-ttl
.RS 4
Number which specifies the time\-to\-live, in minutes, for the cached version of the repository summary page\&. See also: "CACHE"\&. Default value: "5"\&.
.RE
.PP
cache\-root
.RS 4
Path used to store the cgit cache entries\&. Default value: "/var/cache/cgit"\&. See also: "MACRO EXPANSION"\&.
.RE
.PP
cache\-root\-ttl
.RS 4
Number which specifies the time\-to\-live, in minutes, for the cached version of the repository index page\&. See also: "CACHE"\&. Default value: "5"\&.
.RE
.PP
cache\-scanrc\-ttl
.RS 4
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"\&.
.RE
.PP
case\-sensitive\-sort
.RS 4
Sort items in the repo list case sensitively\&. Default value: "1"\&. See also: repository\-sort, section\-sort\&.
.RE
.PP
cache\-size
.RS 4
The maximum number of entries in the cgit cache\&. When set to "0", caching is disabled\&. See also: "CACHE"\&. Default value: "0"
.RE
.PP
cache\-snapshot\-ttl
.RS 4
Number which specifies the time\-to\-live, in minutes, for the cached version of snapshots\&. See also: "CACHE"\&. Default value: "5"\&.
.RE
.PP
cache\-static\-ttl
.RS 4
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"\&.
.RE
.PP
clone\-prefix
.RS 4
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\&.
.RE
.PP
clone\-url
.RS 4
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"\&.
.RE
.PP
commit\-filter
.RS 4
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"\&.
.RE
.PP
commit\-sort
.RS 4
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\&.
.RE
.PP
css
.RS 4
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\&.
.RE
.PP
email\-filter
.RS 4
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"\&.
.RE
.PP
embedded
.RS 4
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"\&.
.RE
.PP
enable\-blame
.RS 4
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"\&.
.RE
.PP
enable\-commit\-graph
.RS 4
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"\&.
.RE
.PP
enable\-filter\-overrides
.RS 4
Flag which, when set to "1", allows all filter settings to be overridden in repository\-specific cgitrc files\&. Default value: none\&.
.RE
.PP
enable\-follow\-links
.RS 4
Flag which, when set to "1", allows users to follow a file in the log view\&. Default value: "0"\&.
.RE
.PP
enable\-git\-config
.RS 4
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, gitweb\&.description, and gitweb\&.homepage will map to the cgit keys repo\&.owner, repo\&.section, repo\&.desc, and repo\&.homepage 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\&.
.RE
.PP
enable\-http\-clone
.RS 4
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"\&.
.RE
.PP
enable\-html\-serving
.RS 4
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"\&.
.RE
.PP
enable\-index\-links
.RS 4
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"\&.
.RE
.PP
enable\-index\-owner
.RS 4
Flag which, when set to "1", will make cgit display the owner of each repo in the repository index\&. Default value: "1"\&.
.RE
.PP
enable\-log\-filecount
.RS 4
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"\&.
.RE
.PP
enable\-log\-linecount
.RS 4
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"\&.
.RE
.PP
enable\-remote\-branches
.RS 4
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"\&.
.RE
.PP
enable\-subject\-links
.RS 4
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"\&.
.RE
.PP
enable\-tree\-linenumbers
.RS 4
Flag which, when set to "1", will make cgit generate linenumber links for plaintext blobs printed in the tree view\&. Default value: "1"\&.
.RE
.PP
favicon
.RS 4
Url used as link to a shortcut icon for cgit\&. It is suggested to use the value "/favicon\&.ico" since certain browsers will ignore other values\&. Default value: "/favicon\&.ico"\&.
.RE
.PP
footer
.RS 4
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\&.
.RE
.PP
head\-include
.RS 4
The content of the file specified with this option will be included verbatim in the html HEAD section on all pages\&. Default value: none\&.
.RE
.PP
header
.RS 4
The content of the file specified with this option will be included verbatim at the top of all pages\&. Default value: none\&.
.RE
.PP
include
.RS 4
Name of a configfile to include before the rest of the current config\- file is parsed\&. Default value: none\&. See also: "MACRO EXPANSION"\&.
.RE
.PP
js
.RS 4
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\&.
.RE
.PP
local\-time
.RS 4
Flag which, if set to "1", makes cgit print commit and tag times in the servers timezone\&. Default value: "0"\&.
.RE
.PP
logo
.RS 4
Url which specifies the source of an image which will be used as a logo on all cgit pages\&. Default value: "/cgit\&.png"\&.
.RE
.PP
logo\-link
.RS 4
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\&.
.RE
.PP
max\-atom\-items
.RS 4
Specifies the number of items to display in atom feeds view\&. Default value: "10"\&.
.RE
.PP
max\-blob\-size
.RS 4
Specifies the maximum size of a blob to display HTML for in KBytes\&. Default value: "0" (limit disabled)\&.
.RE
.PP
max\-commit\-count
.RS 4
Specifies the number of entries to list per page in "log" view\&. Default value: "50"\&.
.RE
.PP
max\-message\-length
.RS 4
Specifies the maximum number of commit message characters to display in "log" view\&. Default value: "80"\&.
.RE
.PP
max\-repo\-count
.RS 4
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"\&.
.RE
.PP
max\-repodesc\-length
.RS 4
Specifies the maximum number of repo description characters to display on the repository index page\&. Default value: "80"\&.
.RE
.PP
max\-stats
.RS 4
Set the default maximum statistics period\&. Valid values are "week", "month", "quarter" and "year"\&. If unspecified, statistics are disabled\&. Default value: none\&. See also: "repo\&.max\-stats"\&.
.RE
.PP
mimetype\&.<ext>
.RS 4
Set the mimetype for the specified filename extension\&. This is used by the
plain
command when returning blob content\&.
.RE
.PP
mimetype\-file
.RS 4
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a comment line is an empty line or a line starting with a hash (#), optionally preceded by whitespace
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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>"\&.
.RE
.RE
.PP
module\-link
.RS 4
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 path and SHA1 of the submodule commit\&. Default value: none\&.
.RE
.PP
noplainemail
.RS 4
If set to "1" showing full author email addresses will be disabled\&. Default value: "0"\&.
.RE
.PP
noheader
.RS 4
Flag which, when set to "1", will make cgit omit the standard header on all pages\&. Default value: none\&. See also: "embedded"\&.
.RE
.PP
owner\-filter
.RS 4
Specifies a command which will be invoked to format the Owner column of the main page\&. The command will get the owner on STDIN, and the STDOUT from the command will be included verbatim in the table\&. This can be used to link to additional context such as an owners home page\&. When active this filter is used instead of the default owner query url\&. Default value: none\&. See also: "FILTER API"\&.
.RE
.PP
project\-list
.RS 4
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"\&.
.RE
.PP
readme
.RS 4
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\&.
.RE
.PP
remove\-suffix
.RS 4
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\&.
.RE
.PP
renamelimit
.RS 4
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"\&.
.RE
.PP
repository\-sort
.RS 4
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\&.
.RE
.PP
robots
.RS 4
Text used as content for the "robots" meta\-tag\&. Default value: "index, nofollow"\&.
.RE
.PP
root\-desc
.RS 4
Text printed below the heading on the repository index page\&. Default value: "a fast webinterface for the git dscm"\&.
.RE
.PP
root\-readme
.RS 4
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\&.
.RE
.PP
root\-title
.RS 4
Text printed as heading on the repository index page\&. Default value: "Git Repository Browser"\&.
.RE
.PP
scan\-hidden\-path
.RS 4
If set to "1" and scan\-path is enabled, scan\-path will recurse into directories whose name starts with a period (\fI\&.\fR)\&. 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\&.
.RE
.PP
scan\-path
.RS 4
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"\&.
.RE
.PP
section
.RS 4
The name of the current repository section \- all repositories defined after this option will inherit the current section name\&. Default value: none\&.
.RE
.PP
section\-sort
.RS 4
Flag which, when set to "1", will sort the sections on the repository listing by name\&. Set this flag to "0" if the order in the cgitrc file should be preserved\&. Default value: "1"\&. See also: section, case\-sensitive\-sort, repository\-sort\&.
.RE
.PP
section\-from\-path
.RS 4
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"\&.
.RE
.PP
side\-by\-side\-diffs
.RS 4
If set to "1" shows side\-by\-side diffs instead of unidiffs per default\&. Default value: "0"\&.
.RE
.PP
snapshots
.RS 4
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\&.
.RE
.PP
source\-filter
.RS 4
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\&. Default value: none\&. See also: "FILTER API"\&.
.RE
.PP
summary\-branches
.RS 4
Specifies the number of branches to display in the repository "summary" view\&. Default value: "10"\&.
.RE
.PP
summary\-log
.RS 4
Specifies the number of log entries to display in the repository "summary" view\&. Default value: "10"\&.
.RE
.PP
summary\-tags
.RS 4
Specifies the number of tags to display in the repository "summary" view\&. Default value: "10"\&.
.RE
.PP
strict\-export
.RS 4
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\(cqs EXPORT_OK and STRICT_EXPORT functionality and limit cgit\(cqs repositories to match those exported by git\-daemon\&. This option must be defined prior to scan\-path\&.
.RE
.PP
virtual\-root
.RS 4
Url which, if specified, will be used as root for all cgit links\&. It will also cause cgit to generate
\fIvirtual urls\fR, i\&.e\&. urls like
\fI/cgit/tree/README\fR
as opposed to
\fI?r=cgit&p=tree&path=README\fR\&. 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\&.
.RE
.SH "REPOSITORY SETTINGS"
.PP
repo\&.about\-filter
.RS 4
Override the default about\-filter\&. Default value: none\&. See also: "enable\-filter\-overrides"\&. See also: "FILTER API"\&.
.RE
.PP
repo\&.branch\-sort
.RS 4
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"\&.
.RE
.PP
repo\&.clone\-url
.RS 4
A list of space\-separated urls which can be used to clone this repo\&. Default value: none\&. See also: "MACRO EXPANSION"\&.
.RE
.PP
repo\&.commit\-filter
.RS 4
Override the default commit\-filter\&. Default value: none\&. See also: "enable\-filter\-overrides"\&. See also: "FILTER API"\&.
.RE
.PP
repo\&.commit\-sort
.RS 4
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\&.
.RE
.PP
repo\&.defbranch
.RS 4
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\&.
.RE
.PP
repo\&.desc
.RS 4
The value to show as repository description\&. Default value: none\&.
.RE
.PP
repo\&.email\-filter
.RS 4
Override the default email\-filter\&. Default value: none\&. See also: "enable\-filter\-overrides"\&. See also: "FILTER API"\&.
.RE
.PP
repo\&.enable\-blame
.RS 4
A flag which can be used to disable the global setting \(oqenable\-blame\(cq\&. Default value: none\&.
.RE
.PP
repo\&.enable\-commit\-graph
.RS 4
A flag which can be used to disable the global setting \(oqenable\-commit\-graph\(cq\&. Default value: none\&.
.RE
.PP
repo\&.enable\-html\-serving
.RS 4
A flag which can be used to override the global setting
enable\-html\-serving\&. Default value: none\&.
.RE
.PP
repo\&.enable\-log\-filecount
.RS 4
A flag which can be used to disable the global setting \(oqenable\-log\-filecount\(cq\&. Default value: none\&.
.RE
.PP
repo\&.enable\-log\-linecount
.RS 4
A flag which can be used to disable the global setting \(oqenable\-log\-linecount\(cq\&. Default value: none\&.
.RE
.PP
repo\&.enable\-remote\-branches
.RS 4
Flag which, when set to "1", will make cgit display remote branches in the summary and refs views\&. Default value: <enable\-remote\-branches>\&.
.RE
.PP
repo\&.enable\-subject\-links
.RS 4
A flag which can be used to override the global setting \(oqenable\-subject\-links\(cq\&. Default value: none\&.
.RE
.PP
repo\&.extra\-head\-content
.RS 4
This value will be added verbatim to the head section of each page displayed for this repo\&. Default value: none\&.
.RE
.PP
repo\&.hide
.RS 4
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"\&.
.RE
.PP
repo\&.homepage
.RS 4
The value to show as repository homepage\&. Default value: none\&.
.RE
.PP
repo\&.ignore
.RS 4
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"\&.
.RE
.PP
repo\&.logo
.RS 4
Url which specifies the source of an image which will be used as a logo on this repo\(cqs pages\&. Default value: global logo\&.
.RE
.PP
repo\&.logo\-link
.RS 4
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\&.
.RE
.PP
repo\&.module\-link
.RS 4
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 path and SHA1 of the submodule commit\&. Default value: <module\-link>
.RE
.PP
repo\&.module\-link\&.<path>
.RS 4
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\&.
.RE
.PP
repo\&.max\-stats
.RS 4
Override the default maximum statistics period\&. Valid values are equal to the values specified for the global "max\-stats" setting\&. Default value: none\&.
.RE
.PP
repo\&.name
.RS 4
The value to show as repository name\&. Default value: <repo\&.url>\&.
.RE
.PP
repo\&.owner
.RS 4
A value used to identify the owner of the repository\&. Default value: none\&.
.RE
.PP
repo\&.owner\-filter
.RS 4
Override the default owner\-filter\&. Default value: none\&. See also: "enable\-filter\-overrides"\&. See also: "FILTER API"\&.
.RE
.PP
repo\&.path
.RS 4
An absolute path to the repository directory\&. For non\-bare repositories this is the \&.git\-directory\&. Default value: none\&.
.RE
.PP
repo\&.readme
.RS 4
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>\&.
.RE
.PP
repo\&.section
.RS 4
Override the current section name for this repository\&. Default value: none\&.
.RE
.PP
repo\&.snapshots
.RS 4
A mask of snapshot formats for this repo that cgit generates links for, restricted by the global "snapshots" setting\&. Default value: <snapshots>\&.
.RE
.PP
repo\&.snapshot\-prefix
.RS 4
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\&.
.RE
.PP
repo\&.source\-filter
.RS 4
Override the default source\-filter\&. Default value: none\&. See also: "enable\-filter\-overrides"\&. See also: "FILTER API"\&.
.RE
.PP
repo\&.url
.RS 4
The relative url used to access the repository\&. This must be the first setting specified for each repo\&. Default value: none\&.
.RE
.SH "REPOSITORY\-SPECIFIC CGITRC FILE"
.sp
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"\&.
.sp
Note: the "repo\&." prefix is dropped from the option names in repo\-specific config files, e\&.g\&. "repo\&.desc" becomes "desc"\&.
.SH "FILTER API"
.sp
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:
.PP
\fIexec:\fR
.RS 4
The default "one process per filter" mode\&.
.RE
.PP
\fIlua:\fR
.RS 4
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\(cqs lifetime, making it a good choice for repeated filters such as the
\fIemail filter\fR\&. It responds to three functions:
.RE
.PP
\fIfilter_open(argument1, argument2, argument3, \&...)\fR
.RS 4
This is called upon activation of the filter for a particular set of data\&.
.RE
.PP
\fIfilter_write(buffer)\fR
.RS 4
This is called whenever cgit writes data to the webpage\&.
.RE
.PP
\fIfilter_close()\fR
.RS 4
This is called when the current filtering operation is completed\&. It must return an integer value\&. Usually 0 indicates success\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Additionally, cgit exposes to the Lua the following built\-in functions:
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fIhtml(str)\fR
.RS 4
Writes
\fIstr\fR
to the webpage\&.
.RE
.PP
\fIhtml_txt(str)\fR
.RS 4
HTML escapes and writes
\fIstr\fR
to the webpage\&.
.RE
.PP
\fIhtml_attr(str)\fR
.RS 4
HTML escapes for an attribute and writes "str\*(Aq to the webpage\&.
.RE
.PP
\fIhtml_url_path(str)\fR
.RS 4
URL escapes for a path and writes
\fIstr\fR
to the webpage\&.
.RE
.PP
\fIhtml_url_arg(str)\fR
.RS 4
URL escapes for an argument and writes
\fIstr\fR
to the webpage\&.
.RE
.PP
\fIhtml_include(file)\fR
.RS 4
Includes
\fIfile\fR
in webpage\&.
.RE
.sp
Parameters are provided to filters as follows\&.
.PP
about filter
.RS 4
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\&.
.RE
.PP
auth filter
.RS 4
The authentication filter receives 12 parameters:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
filter action, explained below, which specifies which action the filter is called for
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
http cookie
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
http method
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
http referer
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
http path
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
http https flag
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cgit repo
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cgit page
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cgit url
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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 invalid, in the exit code / close function\&. If the filter action is "authenticate\-post", this filter receives POST\(cqd 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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Please see `filters/simple\-authentication\&.lua` for a clear example
script that may be modified\&.
.fi
.if n \{\
.RE
.\}
.RE
.RE
.PP
commit filter
.RS 4
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\&.
.RE
.PP
email filter
.RS 4
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\&.
.RE
.PP
owner filter
.RS 4
This filter is given no arguments\&. The owner text is available on standard input and the filter is expected to write to standard output\&. The output is included in the Owner column\&.
.RE
.PP
source filter
.RS 4
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\&.
.RE
.sp
All filters are handed the following environment variables:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_URL (from repo\&.url)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_NAME (from repo\&.name)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_PATH (from repo\&.path)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_OWNER (from repo\&.owner)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_DEFBRANCH (from repo\&.defbranch)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_SECTION (from repo\&.section)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CGIT_REPO_CLONE_URL (from repo\&.clone\-url)
.RE
.sp
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\&.
.SH "MACRO EXPANSION"
.sp
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cache\-root
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
include
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
project\-list
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
scan\-path
.RE
.sp
Macro expansion will also happen on the content of $CGIT_CONFIG, if defined\&.
.sp
One usage of this feature is virtual hosting, which in its simplest form can be accomplished by adding the following line to /etc/cgitrc:
.sp
.if n \{\
.RS 4
.\}
.nf
include=/etc/cgitrc\&.d/$HTTP_HOST
.fi
.if n \{\
.RE
.\}
.sp
The following options are expanded during request processing, and support the environment variables defined in "FILTER API":
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
clone\-url
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
repo\&.clone\-url
.RE
.SH "CACHE"
.sp
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\&.
.SH "SIGNATURES"
.sp
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:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
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:
.sp
.if n \{\
.RS 4
.\}
.nf
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"
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.SH "EXAMPLE CGITRC FILE"
.sp
.if n \{\
.RS 4
.\}
.nf
# Enable caching of up to 1000 output entries
cache\-size=1000


# Specify some default clone urls using macro expansion
clone\-url=git://foo\&.org/$CGIT_REPO_URL git@foo\&.org:$CGIT_REPO_URL

# Specify the css url
css=/css/cgit\&.css


# Show owner on index page
enable\-index\-owner=1


# Allow http transport git clone
enable\-http\-clone=1


# Show extra links for each repository on the index page
enable\-index\-links=1


# Enable blame page and create links to it from tree page
enable\-blame=1


# Enable ASCII art commit history graph on the log pages
enable\-commit\-graph=1


# Show number of affected files per commit on the log pages
enable\-log\-filecount=1


# Show number of added/removed lines per commit on the log pages
enable\-log\-linecount=1


# Sort branches by date
branch\-sort=age


# Add a cgit favicon
favicon=/favicon\&.ico


# Use a custom logo
logo=/img/mylogo\&.png


# Enable statistics per week, month and quarter
max\-stats=quarter


# Set the title and heading of the repository index page
root\-title=example\&.com git repositories


# Set a subheading for the repository index page
root\-desc=tracking the foobar development


# Include some more info about example\&.com on the index page
root\-readme=/var/www/htdocs/about\&.html


# Allow download of tar\&.gz, tar\&.bz2 and zip\-files
snapshots=tar\&.gz tar\&.bz2 zip


##
## List of common mimetypes
##

mimetype\&.gif=image/gif
mimetype\&.html=text/html
mimetype\&.jpg=image/jpeg
mimetype\&.jpeg=image/jpeg
mimetype\&.pdf=application/pdf
mimetype\&.png=image/png
mimetype\&.svg=image/svg+xml


# Highlight source code with python pygments\-based highlighter
source\-filter=/var/www/cgit/filters/syntax\-highlighting\&.py

# Format markdown, restructuredtext, manpages, text files, and html files
# through the right converters
about\-filter=/var/www/cgit/filters/about\-formatting\&.sh

##
## Search for these files in the root of the default branch of repositories
## for coming up with the about page:
##
readme=:README\&.md
readme=:readme\&.md
readme=:README\&.mkd
readme=:readme\&.mkd
readme=:README\&.rst
readme=:readme\&.rst
readme=:README\&.html
readme=:readme\&.html
readme=:README\&.htm
readme=:readme\&.htm
readme=:README\&.txt
readme=:readme\&.txt
readme=:README
readme=:readme
readme=:INSTALL\&.md
readme=:install\&.md
readme=:INSTALL\&.mkd
readme=:install\&.mkd
readme=:INSTALL\&.rst
readme=:install\&.rst
readme=:INSTALL\&.html
readme=:install\&.html
readme=:INSTALL\&.htm
readme=:install\&.htm
readme=:INSTALL\&.txt
readme=:install\&.txt
readme=:INSTALL
readme=:install


##
## List of repositories\&.
## PS: Any repositories listed when section is unset will not be
##     displayed under a section heading
## PPS: This list could be kept in a different file (e\&.g\&. \*(Aq/etc/cgitrepos\*(Aq)
##      and included like this:
##        include=/etc/cgitrepos
##


repo\&.url=foo
repo\&.path=/pub/git/foo\&.git
repo\&.desc=the master foo repository
repo\&.owner=fooman@example\&.com
repo\&.readme=info/web/about\&.html


repo\&.url=bar
repo\&.path=/pub/git/bar\&.git
repo\&.desc=the bars for your foo
repo\&.owner=barman@example\&.com
repo\&.readme=info/web/about\&.html


# The next repositories will be displayed under the \*(Aqextras\*(Aq heading
section=extras


repo\&.url=baz
repo\&.path=/pub/git/baz\&.git
repo\&.desc=a set of extensions for bar users

repo\&.url=wiz
repo\&.path=/pub/git/wiz\&.git
repo\&.desc=the wizard of foo


# Add some mirrored repositories
section=mirrors


repo\&.url=git
repo\&.path=/pub/git/git\&.git
repo\&.desc=the dscm


repo\&.url=linux
repo\&.path=/pub/git/linux\&.git
repo\&.desc=the kernel

# Disable adhoc downloads of this repo
repo\&.snapshots=0

# Disable line\-counts for this repo
repo\&.enable\-log\-linecount=0

# Restrict the max statistics period for this repo
repo\&.max\-stats=month
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.sp
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:
.sp
.if n \{\
.RS 4
.\}
.nf
robots=index  # allow indexing
.fi
.if n \{\
.RE
.\}
.sp
will generate the following html element:
.sp
.if n \{\
.RS 4
.\}
.nf
<meta name=\*(Aqrobots\*(Aq content=\*(Aqindex  # allow indexing\*(Aq/>
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.sp
Lars Hjemli <hjemli@gmail\&.com> Jason A\&. Donenfeld <Jason@zx2c4\&.com>