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
cache-static-ttl::
Number which specifies the time-to-live, in minutes, for the cached
- version of repository pages accessed with a fixed SHA1. Negative
- values have infinite ttl. Default value: -1".
+ version of repository pages accessed with a fixed SHA1. See also:
+ "CACHE". Default value: -1".
cache-dynamic-ttl::
Number which specifies the time-to-live, in minutes, for the cached
- version of repository pages accessed without a fixed SHA1. Negative
- values have infinite ttl. Default value: "5".
+ 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. Negative values have infinite
- ttl. Default value: "5".
+ version of the repository summary page. See also: "CACHE". Default
+ value: "5".
cache-root-ttl::
Number which specifies the time-to-live, in minutes, for the cached
- version of the repository index page. Negative values have infinite
- ttl. Default value: "5".
+ 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. Negative values have infinite
- ttl. Default value: "15".
+ of scanning a path for git repositories. See also: "CACHE". Default
+ value: "15".
cache-about-ttl::
Number which specifies the time-to-live, in minutes, for the cached
- version of the repository about page. Negative values have infinite
- ttl. Default value: "15".
+ version of the repository about page. See also: "CACHE". Default
+ value: "15".
+
+cache-snapshot-ttl::
+ Number which specifies the time-to-live, in minutes, for the cached
+ version of snapshots. See also: "CACHE". Default value: "5".
cache-size::
- The maximum number of entries in the cgit cache. Default value: "0"
- (i.e. caching is disabled).
+ The maximum number of entries in the cgit cache. When set to "0",
+ caching is disabled. See also: "CACHE". Default value: "0"
case-sensitive-sort::
Sort items in the repo list case sensitively. Default value: "1".
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 as its only command line argument, 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".
+ 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
Flag which, when set to "1", allows all filter settings to be
overridden in repository-specific cgitrc files. Default value: none.
+enable-follow-links::
+ Flag which, when set to "1", allows users to follow a file in the log
+ view. Default value: "0".
+
enable-http-clone::
If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
You can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url
in commit view. Default value: "0". See also:
"repo.enable-subject-links".
+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-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".
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.
+ 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.
favicon::
Url used as link to a shortcut icon for cgit. It is suggested to use
calculated url of the repository index page will be used. Default
value: none.
+owner-filter::
+ 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".
+
max-atom-items::
Specifies the number of items to display in atom feeds view. Default
value: "10".
default. Default value: "0".
snapshots::
- Text which specifies the default set of snapshot formats generated by
- cgit. The value is a space-separated list of zero or more of the
- values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip". Default value:
- none.
+ 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.xz" and "zip".
+ Default value: none.
source-filter::
Specifies a command which will be invoked to format plaintext blobs
repo.desc::
The value to show as repository description. Default value: none.
+repo.homepage::
+ The value to show as repository homepage. Default value: none.
+
repo.email-filter::
Override the default email-filter. Default value: none. See also:
"enable-filter-overrides". See also: "FILTER API".
A flag which can be used to override the global setting
`enable-subject-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.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.
calculated url of the repository index page will be used. Default
value: global logo-link.
+repo.owner-filter::
+ Override the default owner-filter. Default value: none. See also:
+ "enable-filter-overrides". See also: "FILTER API".
+
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
file. Default value: <readme>.
repo.snapshots::
- A mask of allowed snapshot-formats for this repo, restricted by the
- "snapshots" global setting. Default value: <snapshots>.
+ A mask of snapshot formats for this repo that cgit generates links for,
+ restricted by the global "snapshots" setting. Default value:
+ <snapshots>.
repo.section::
Override the current section name for this repository. Default value:
This is called whenever cgit writes data to the webpage.
'filter_close()'::
This is called when the current filtering operation is
- completed.
-
+ completed. It must return an integer value. Usually 0
+ indicates success.
+
Additionally, cgit exposes to the Lua the following built-in functions:
'html(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.
expected on standard output.
email filter::
- This filter is given a single parameter: the email address of the
- relevent user. 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.
+ 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.
+
+owner filter::
+ 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.
source filter::
This filter is given a single parameter: the filename of the source
file that is to be filtered is available on standard input and the
filtered contents is expected on standard output.
-Also, all filters are handed the following environment variables:
+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 invalid,
+ 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.
+
+ Please see `filters/simple-authentication.lua` for a clear example
+ script that may be modified.
+
+
+All filters are handed the following environment variables:
- CGIT_REPO_URL (from repo.url)
- CGIT_REPO_NAME (from repo.name)
- 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.
+
+
EXAMPLE CGITRC FILE
-------------------
git.ckatri.com / cgit.git / blobdiff