Diffstat (limited to 'cgitrc.5.txt')
| -rw-r--r-- | cgitrc.5.txt | 383 |
1 files changed, 107 insertions, 276 deletions
diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 527233d..e21ece9 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -54,10 +54,14 @@ branch-sort:: list, and when set to "name" enables ordering by branch name. Default value: "name". -cache-about-ttl:: +cache-root:: + Path used to store the cgit cache entries. Default value: + "/var/cache/cgit". See also: "MACRO EXPANSION". + +cache-static-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". + 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 @@ -69,10 +73,6 @@ cache-repo-ttl:: 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. See also: "CACHE". Default @@ -83,44 +83,22 @@ cache-scanrc-ttl:: 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-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-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". - -ci-branch-url:: - Url template used by the "ci" tab when a branch is being viewed. If - unspecified, `ci-url` is used instead. Default value: none. See also: - "CI URL EXPANSION". - -ci-filter:: - Specifies a command which decides whether the "ci" tab is shown for - the ref currently being viewed, which is useful when only some refs - have a pipeline. Default value: none. See also: "FILTER API". - -ci-tag-url:: - Url template used by the "ci" tab when a tag is being viewed. If - unspecified, `ci-url' is used instead. Default value: none. See also: - "CI URL EXPANSION". +cache-size:: + The maximum number of entries in the cgit cache. When set to "0", + caching is disabled. See also: "CACHE". Default value: "0" -ci-url:: - Url template used by the "ci" tab for refs which are not covered by - `ci-branch-url` or `ci-tag-url`. When at least one of the three ci url - settings is specified, cgit adds a "ci" tab which redirects to the - expanded url for the ref currently being viewed. Default value: none. - See also: "CI URL EXPANSION". +case-sensitive-sort:: + Sort items in the repo list case sensitively. Default value: "1". + See also: repository-sort, section-sort. clone-prefix:: Space-separated list of common prefixes which, when combined with a @@ -148,8 +126,7 @@ commit-sort:: 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. + Default value: "/cgit.css". email-filter:: Specifies a command which will be invoked to format names and email @@ -164,11 +141,6 @@ embedded:: 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 @@ -178,33 +150,12 @@ 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 a dumb HTTP endpoint for git clones. + 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 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", @@ -239,15 +190,20 @@ 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, + 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 - always include the value "/favicon.ico" since certain browsers will - ignore other values. May be given multiple times, each favicon URL - path is added in the head section of the document in turn, letting - the browser pick the icon it prefers. The mimetype of each icon is - deduced from the extension of its url ("ico", "png", "svg", "gif", - "jpg", "jpeg", "webp" and "avif" are recognized) and emitted as a - "type" attribute. Default value: "/favicon.svg", "/favicon.ico". + 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". footer:: The content of the file specified with this option will be included @@ -266,10 +222,17 @@ 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. +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. local-time:: Flag which, if set to "1", makes cgit print commit and tag times in the @@ -277,21 +240,26 @@ local-time:: logo:: Url which specifies the source of an image which will be used as a logo - on all cgit pages. Default value: "/cgit.svg". + 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. +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". -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". @@ -302,13 +270,16 @@ max-message-length:: 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". + index page. 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 @@ -336,6 +307,11 @@ 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". @@ -344,15 +320,6 @@ 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 @@ -376,6 +343,10 @@ 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 @@ -441,12 +412,8 @@ side-by-side-diffs:: 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. + 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 @@ -495,22 +462,6 @@ repo.branch-sort:: list, and when set to "name" enables ordering by branch name. Default value: "name". -repo.ci-branch-url:: - Override the global setting `ci-branch-url' for this repository. - Default value: <ci-branch-url>. See also: "CI URL EXPANSION". - -repo.ci-filter:: - Override the default ci-filter. Default value: none. See also: - "enable-filter-overrides". See also: "FILTER API". - -repo.ci-tag-url:: - Override the global setting `ci-tag-url' for this repository. Default - value: <ci-tag-url>. See also: "CI URL EXPANSION". - -repo.ci-url:: - Override the global setting `ci-url' for this repository. Default - value: <ci-url>. See also: "CI URL EXPANSION". - repo.clone-url:: A list of space-separated urls which can be used to clone this repo. Default value: none. See also: "MACRO EXPANSION". @@ -538,22 +489,10 @@ 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. @@ -570,18 +509,11 @@ 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 @@ -596,6 +528,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 @@ -620,10 +556,6 @@ 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. @@ -633,27 +565,20 @@ 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 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. + 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 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.section:: + Override the current section name for this repository. Default value: + none. repo.source-filter:: Override the default source-filter. Default value: none. See also: @@ -727,6 +652,30 @@ about filter:: The about text that is to be filtered is available on standard input and the filtered text is expected on standard output. +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 relevent + 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 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 + 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. + auth filter:: The authentication filter receives 12 parameters: - filter action, explained below, which specifies which action the @@ -753,44 +702,6 @@ auth filter:: Please see `filters/simple-authentication.lua` for a clear example script that may be modified. -ci filter:: - This filter is given three parameters: the name of the branch or tag - being viewed, the string "branch" or "tag" to say which of the two it - is, and the ci url that the "ci" tab would redirect to. It decides - whether that tab is shown at all, by returning zero from the exit code - / close function to show it and non-zero to hide it. Nothing is written - to its standard input, and it must not write to standard output, since - that would land in the middle of the page being rendered. - - The filter is consulted while rendering every page of the repository, - not only ref pages, so a filter which contacts the ci system should - cache its verdict and use a short timeout. Please see - `filters/ci-jenkins.sh` for an example. - -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 - 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: @@ -833,48 +744,8 @@ the environment variables defined in "FILTER API": - repo.clone-url -CI URL EXPANSION ----------------- -The options `ci-url', `ci-branch-url' and `ci-tag-url' (and their -`repo.'-prefixed counterparts) are url templates in which the following -tokens are substituted when the "ci" tab is followed: - -$ref:: - The name of the branch or tag currently being viewed. - -$repo:: - The url of the repository, i.e. the value of `repo.url'. - -$slug:: - $repo with any ".git" suffix removed and all slashes replaced by - dashes, e.g. "sayauz/web.git" becomes "sayauz-web". - -Two consecutive dollar signs produce a single literal one, and any other -"$" is left untouched. Tokens are substituted verbatim, so the resulting -url must already be properly encoded. - -When a tag is being viewed, `ci-tag-url' is used; for anything else -`ci-branch-url' is used. Whichever of the two applies falls back to -`ci-url' when it is unset, and the "ci" tab yields "404 Not found" when -neither is set for the current ref. This makes it possible to point at a -Jenkins multibranch pipeline, where branches and tags live at different -locations: - - ci-branch-url=https://ci.example.org/job/$slug/job/$ref - ci-tag-url=https://ci.example.org/job/$slug/view/tags/job/$ref - -Setting `repo.ci-url' discards the values which the repository would -otherwise inherit from the global `ci-branch-url' and `ci-tag-url', so -that a single repository can be pointed at a different ci system without -having to override both of them. - -Note that cgit itself never contacts the ci system, so a tab shown for a -ref which has no pipeline only reveals that after being followed. Use -`ci-filter' to suppress the tab in that case. - - 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 @@ -882,33 +753,6 @@ 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 ------------------- @@ -921,15 +765,8 @@ 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 -css=/css/solarized.css - - -# Add a "ci" tab pointing at a Jenkins multibranch pipeline -ci-branch-url=https://ci.foo.org/job/$slug/job/$ref -ci-tag-url=https://ci.foo.org/job/$slug/view/tags/job/$ref # Show owner on index page @@ -944,10 +781,6 @@ enable-http-clone=1 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 @@ -964,8 +797,7 @@ enable-log-linecount=1 branch-sort=age -# Add cgit favicons -favicon=/favicon.svg +# Add a cgit favicon favicon=/favicon.ico @@ -1125,4 +957,3 @@ AUTHOR ------ Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com> -Saya Andy <saya.andy@posteo.com> |