Diffstat (limited to 'cgitrc.5.txt')
| -rw-r--r-- | cgitrc.5.txt | 152 |
1 files changed, 137 insertions, 15 deletions
diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 34b351b..6ddb977 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -100,6 +100,28 @@ cache-static-ttl:: 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". + +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". + clone-prefix:: Space-separated list of common prefixes which, when combined with a repository url, generates valid clone urls for the repository. This @@ -126,7 +148,8 @@ 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 @@ -217,9 +240,14 @@ enable-tree-linenumbers:: for plaintext blobs printed in the tree view. Default value: "1". 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 - values. Default value: "/favicon.ico". + 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". footer:: The content of the file specified with this option will be included @@ -238,13 +266,18 @@ 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. + local-time:: Flag which, if set to "1", makes cgit print commit and tag times in the servers timezone. Default value: "0". logo:: Url which specifies the source of an image which will be used as a logo - on all cgit pages. Default value: "/cgit.png". + on all cgit pages. Default value: "/cgit.svg". logo-link:: Url loaded when clicking on the cgit logo image. If unspecified the @@ -269,7 +302,8 @@ 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 @@ -407,9 +441,12 @@ 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.xz" and "zip". - The special value "all" enables all snapshot formats. - Default value: none. + 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 @@ -458,6 +495,22 @@ 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". @@ -485,10 +538,18 @@ 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. @@ -572,11 +633,11 @@ 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>. + 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: @@ -692,6 +753,20 @@ 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 @@ -758,6 +833,46 @@ 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 ----- @@ -810,6 +925,11 @@ clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL css=/css/cgit.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 enable-index-owner=1 @@ -842,7 +962,8 @@ enable-log-linecount=1 branch-sort=age -# Add a cgit favicon +# Add cgit favicons +favicon=/favicon.svg favicon=/favicon.ico @@ -1002,3 +1123,4 @@ AUTHOR ------ Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com> +Saya Andy <saya.andy@posteo.com> |