X-Git-Url: https://git.cameronkatri.com/cgit.git/blobdiff_plain/b826537cb4aa2358027ffcb1dd6a87274734e962..94c02bbf732d938c92df4961026c4d8f6fd4c37e:/cgitrc.5.txt diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 682d8bb..94901bd 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -60,37 +60,41 @@ cache-root:: 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". @@ -146,6 +150,10 @@ 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-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 @@ -182,6 +190,13 @@ enable-subject-links:: 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". @@ -190,11 +205,11 @@ 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. + 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 @@ -243,6 +258,15 @@ logo-link:: 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". @@ -472,6 +496,9 @@ repo.defbranch:: 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". @@ -496,6 +523,20 @@ repo.enable-subject-links:: A flag which can be used to override the global setting `enable-subject-links'. Default value: none. +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. @@ -505,6 +546,10 @@ repo.logo-link:: 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 @@ -599,7 +644,7 @@ specification with the relevant string; available values are: 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)':: @@ -637,6 +682,11 @@ email filter:: 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 avilable 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 to filter. The filter can use the filename to determine (for @@ -645,7 +695,7 @@ source filter:: filtered contents is expected on standard output. auth filter:: - The authentication filter receives 11 parameters: + The authentication filter receives 12 parameters: - filter action, explained below, which specifies which action the filter is called for - http cookie @@ -656,13 +706,14 @@ auth filter:: - 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 "/?p=login". When + 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 request, preferably + 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. @@ -711,6 +762,16 @@ the environment variables defined in "FILTER API": - 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 -------------------