Diffstat (limited to 'cgitrc.5.txt')
| -rw-r--r-- | cgitrc.5.txt | 120 |
1 files changed, 115 insertions, 5 deletions
diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 6f3e952..527233d 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 @@ -218,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 @@ -250,7 +277,7 @@ 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.png". + on all cgit pages. Default value: "/cgit.svg". logo-link:: Url loaded when clicking on the cgit logo image. If unspecified the @@ -468,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". @@ -503,6 +546,10 @@ 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. @@ -706,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 @@ -772,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 ----- @@ -820,8 +921,15 @@ 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 @@ -856,7 +964,8 @@ enable-log-linecount=1 branch-sort=age -# Add a cgit favicon +# Add cgit favicons +favicon=/favicon.svg favicon=/favicon.ico @@ -1016,3 +1125,4 @@ AUTHOR ------ Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com> +Saya Andy <saya.andy@posteo.com> |