Diffstat (limited to 'cgitrc.5.txt')
| -rw-r--r-- | cgitrc.5.txt | 365 |
1 files changed, 283 insertions, 82 deletions
diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 633cb00..7c39bf9 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -42,53 +42,64 @@ agefile:: 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-root:: - Path used to store the cgit cache entries. Default value: - "/var/cache/cgit". See also: "MACRO EXPANSION". - -cache-static-ttl:: +cache-about-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 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. 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:: + Path used to store the cgit cache entries. Default value: + "/var/cache/cgit". See also: "MACRO EXPANSION". 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". - -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". - -cache-size:: - The maximum number of entries in the cgit cache. Default value: "0" - (i.e. caching is disabled). + 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. 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 @@ -115,13 +126,27 @@ commit-sort:: css:: Url which specifies the css document to include in all cgit pages. - Default value: "/cgit.css". + Default value: "/cgit.css". May be given multiple times, each + css URL path is added in the head section of the document in turn. + +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 @@ -131,10 +156,32 @@ 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-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, 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. + enable-http-clone:: - If set to "1", cgit will act as an dumb HTTP endpoint for git clones. - If you use an alternate way of serving git repositories, you may wish - to disable this. Default value: "1". + 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 @@ -170,16 +217,6 @@ 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-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, - respectivly. 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 the value "/favicon.ico" since certain browsers will ignore other @@ -202,17 +239,10 @@ include:: Name of a configfile to include before the rest of the current config- file is parsed. Default value: none. See also: "MACRO EXPANSION". -index-header:: - The content of the file specified with this option will be included - verbatim above the repository index. This setting is deprecated, and - will not be supported by cgit-1.0 (use root-readme instead). Default - value: none. - -index-info:: - The content of the file specified with this option will be included - verbatim below the heading on the repository index page. This setting - is deprecated, and will not be supported by cgit-1.0 (use root-desc - instead). Default value: none. +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 @@ -231,6 +261,10 @@ max-atom-items:: Specifies the number of items to display in atom feeds view. Default value: "10". +max-blob-size:: + Specifies the maximum size of a blob to display HTML for in KBytes. + Default value: "0" (limit disabled). + max-commit-count:: Specifies the number of entries to list per page in "log" view. Default value: "50". @@ -241,16 +275,13 @@ max-message-length:: max-repo-count:: Specifies the number of entries to list per page on the repository - index page. Default value: "50". + 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-blob-size:: - Specifies the maximum size of a blob to display HTML for in KBytes. - Default value: "0" (limit disabled). - max-stats:: Set the default maximum statistics period. Valid values are "week", "month", "quarter" and "year". If unspecified, statistics are @@ -278,11 +309,6 @@ module-link:: formatstring are the path and SHA1 of the submodule commit. Default value: none. -nocache:: - If set to the value "1" caching will be disabled. This settings is - deprecated, and will not be honored starting with cgit-1.0. Default - value: "0". - noplainemail:: If set to "1" showing full author email addresses will be disabled. Default value: "0". @@ -291,6 +317,15 @@ noheader:: Flag which, when set to "1", will make cgit omit the standard header on all pages. Default value: none. See also: "embedded". +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". + 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 @@ -314,10 +349,6 @@ renamelimit:: "-1" uses the compiletime value in git (for further info, look at `man git-diff`). Default value: "-1". -repo.group:: - Legacy alias for "section". This option is deprecated and will not be - supported in cgit-1.0. - 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 @@ -381,10 +412,14 @@ side-by-side-diffs:: 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.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 @@ -456,10 +491,26 @@ repo.defbranch:: 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-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. @@ -476,6 +527,23 @@ 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.homepage:: + The value to show as repository homepage. Default value: none. + +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. @@ -509,6 +577,10 @@ repo.owner:: A value used to identify the owner of the repository. Default value: none. +repo.owner-filter:: + Override the default owner-filter. Default value: none. See also: + "enable-filter-overrides". See also: "FILTER API". + repo.path:: An absolute path to the repository directory. For non-bare repositories this is the .git-directory. Default value: none. @@ -518,20 +590,28 @@ repo.readme:: 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 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.snapshots:: - A mask of allowed snapshot-formats for this repo, restricted by the - "snapshots" global setting. Default value: <snapshots>. + 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". @@ -556,6 +636,47 @@ 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 @@ -563,11 +684,49 @@ about filter:: 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 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. + 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. + +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 to filter. The filter can use the filename to determine (for @@ -575,7 +734,8 @@ source filter:: 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: + +All filters are handed the following environment variables: - CGIT_REPO_URL (from repo.url) - CGIT_REPO_NAME (from repo.name) @@ -592,8 +752,8 @@ environment variable will be unset. MACRO EXPANSION --------------- -The following cgitrc options supports a simple macro expansion feature, -where tokens prefixed with "$" are replaced with the value of a similary +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 @@ -616,11 +776,48 @@ 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. + +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. + EXAMPLE CGITRC FILE ------------------- .... -# Enable caching of up to 1000 output entriess +# Enable caching of up to 1000 output entries cache-size=1000 @@ -636,13 +833,17 @@ enable-index-owner=1 # Allow http transport git clone -enable-git-clone=1 +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 @@ -700,7 +901,7 @@ mimetype.png=image/png mimetype.svg=image/svg+xml -# Highlight source code with python pygments-based highligher +# 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 |