Diff options
Diffstat (limited to '')
| -rw-r--r-- | MANUAL.txt | 326 |
1 file changed, 150 insertions, 176 deletions
@@ -18,15 +18,11 @@ Global settings about-filter:: Specifies a command which will be invoked to format the content of about - pages (both top-level and for each repository). The command will get the - content of the about-file on its stdin and the name of the file, with - the tree url its links resolve against, as arguments, and the stdout - from the command will be included verbatim on the about page. Default - value: none. When no about-filter is set, a repository's readme is - escaped and served as plain text, while root-readme is included - verbatim. A bundled Lua filter, about-render.lua, renders markdown, man - pages and plain text when about-filter points at it. See also: "Filter - API". + pages (both top-level and for each repository). When no about-filter is + set, a repository's readme is escaped and served as plain text. A + bundled Lua filter, about-render.lua, renders markdown, man pages and + plain text when about-filter points at it. Default value: none. See + also: "Filter API". age-file:: Specifies a path, relative to each repository path, which can be used to @@ -37,9 +33,8 @@ age-file:: auth-filter:: Specifies a command that will be invoked for authenticating repository - access. Receives 12 arguments, with request data on stdin and its answer - on stdout, as described under "Filter API". If no auth-filter is - specified, no authentication is performed. Default value: none. + access. 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 @@ -48,24 +43,24 @@ branch-sort:: cache-about-ttl:: Number which specifies the time-to-live, in minutes, for the cached - version of the repository about page. See also: "The cache". Default - value: "15". + version of the repository about page. Default value: "15". See also: + "The cache". cache-dynamic-ttl:: Number which specifies the time-to-live, in minutes, for the cached - version of repository pages accessed without a fixed object id. See - also: "The cache". Default value: "5". + version of repository pages accessed without a fixed object id. Default + value: "5". See also: "The cache". cache-index-ttl:: Number which specifies the time-to-live, in minutes, for the cached - version of the repository index page. See also: "The cache". Default - value: "5". + version of the repository index page. Default value: "5". See also: "The + cache". cache-max-slot-size:: Number which specifies the largest response, in kilobytes, that a cache slot may keep. A larger response is still served but not kept, so one archive cannot take a slot's worth of disk. Set to "0" to remove the - limit. See also: "The cache". Default value: "65536" (64 MB). + limit. Default value: "65536" (64 MB). See also: "The cache". cache-root:: Path used to store the cgit cache entries. Default value: @@ -74,32 +69,32 @@ cache-root:: cache-scan-ttl:: Number which specifies the time-to-live, in minutes, for the result of - scanning a path for git repositories. See also: "The cache". Default - value: "15". + scanning a path for git repositories. Default value: "15". See also: + "The cache". cache-size:: The maximum number of entries in the cgit cache. When set to "0", - caching is disabled. See also: "The cache". Default value: "0". + caching is disabled. Default value: "0". See also: "The cache". cache-snapshot-ttl:: Number which specifies the time-to-live, in minutes, for the cached version of snapshots. A snapshot requested with a fixed object id uses - "cache-static-ttl" instead, since its content can never change. See - also: "The cache". Default value: "5". + "cache-static-ttl" instead, since its content can never change. Default + value: "5". See also: "The cache". cache-static-ttl:: Number which specifies the time-to-live, in minutes, for the cached - version of repository pages accessed with a fixed object id. See also: - "The cache". Default value: "-1". + version of repository pages accessed with a fixed object id. Default + value: "-1". See also: "The cache". cache-summary-ttl:: Number which specifies the time-to-live, in minutes, for the cached - version of the repository summary page. See also: "The cache". Default - value: "5". + version of the repository summary page. Default value: "5". See also: + "The cache". case-sensitive-sort:: - Sort items in the repository list case sensitively. Default value: "1". - See also: repository-sort, section-sort. + Sort items in the repository 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 @@ -113,10 +108,11 @@ clone-url:: "Macro expansion", "Filter API". commit-filter:: - Specifies a command which will be invoked to format commit messages. The - command will get the message on its stdin, and the stdout from the - command will be included verbatim as the commit message, which is one - way to link a bug tracker. Default value: none. See also: "Filter API". + Specifies a command which will be invoked to format commit messages, for + example to link a bug tracker. A ready filter linking object names and + configurable text references ships as + custom/extensions/link-commits.lua. Default value: none. See also: + "Filter API". commit-sort:: Flag which, when set to "date", enables strict date ordering in the @@ -125,11 +121,11 @@ commit-sort:: none. 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. Setting this - to an empty string will disable generation of the link to this file in - the head section. + Url which specifies the CSS document to include in all cgit pages. May + be given multiple times, and each CSS url path is added in the head + section of the document in turn. Setting this to an empty string will + disable generation of the link to this file in the head section. Default + value: "/cgit.css". date-format:: Format used for the calendar dates in the age columns of the log, refs @@ -147,14 +143,14 @@ date-format:: 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". + places throughout the cgit interface. Ready filters adding a Gravatar or + Libravatar icon ship as custom/extensions/email-gravatar.lua and + custom/extensions/email-libravatar.lua. Default value: none. See also: + "Filter API". embedded:: - Flag which, when set to "1", makes cgit generate a html fragment - suitable for embedding in other html pages. Default value: "0". See + Flag which, when set to "1", makes cgit generate an HTML fragment + suitable for embedding in other HTML pages. Default value: "0". See also: "enable-header". enable-blame:: @@ -164,9 +160,8 @@ enable-blame:: enable-cache-list:: Flag which, when set to "1", exposes the "ls_cache" page. That page - lists the cache directory path and the URLs of requests other visitors - made, so it is disabled by default and should stay off on any instance - where that disclosure matters. Default value: "0". + lists the cache directory path and the urls other visitors requested. + Default value: "0". enable-commit-graph:: Flag which, when set to "1", makes cgit print an ASCII-art commit @@ -177,10 +172,8 @@ enable-commit-trailers:: Flag which, when set to "1", makes the commit page split the trailer block, the Signed-off-by lines and their kin, off the end of the commit message and show it as a table under the message. The block is found the - way git finds it for "git interpret-trailers", so the last paragraph is - taken when every line in it is a trailer, or when it holds a - Signed-off-by and at least a quarter of its lines are trailers. Default - value: "0". See also: "trailer-filter", "repo.enable-commit-trailers". + way "git interpret-trailers" finds it. Default value: "0". See also: + "trailer-filter", "repo.enable-commit-trailers". enable-follow-links:: Flag which, when set to "1", allows users to follow a file in the log @@ -194,7 +187,8 @@ enable-git-config:: repo.section, and repo.desc respectively. All git config keys that begin with "cgit." are mapped to the corresponding "repo." key in cgit, subject to "trust-scan-config" the way a repository's cgitrc is. Default - value: "0". See also: scan-path, section-from-path, trust-scan-config. + value: "0". See also: "scan-path", "section-from-path", + "trust-scan-config". enable-gitmodules-links:: Flag which, when set to "1", makes submodule listings derive a link from @@ -223,15 +217,11 @@ enable-html-serving:: "repo.enable-html-serving". enable-http-clone:: - If set to "1", cgit acts as a dumb HTTP endpoint for git clones. Adding - "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url exposes it. - The files it serves come straight off the disk and are never cached. - Most sites can leave this as it is, though the dumb transport is git's - older one and is not recommended. cgit does not speak the smart - protocol git prefers, so a site that wants it routes clone requests to - git-http-backend in its web server, and smart clients use that - instead. A site that serves git repositories another way can turn this - off. Default value: "1". + If set to "1", cgit acts as a dumb HTTP endpoint for git clones, which + adding "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url + exposes. Its files are never cached. cgit does not speak the smart + protocol git prefers, which a site can offer by routing clone requests + to git-http-backend in its web server. Default value: "1". enable-index-links:: Flag which, when set to "1", makes cgit generate extra links for each @@ -293,8 +283,8 @@ enable-tree-linenumbers:: enable-version-info:: Flag which, when set to "1", names the cgit and git versions in the - standard page footer and the generator meta tag, and the cgit version - in the signature that ends each patch. Exact versions help someone + standard page footer, and the cgit version in the generator meta tag + and in the signature that ends each patch. Exact versions help someone match a site against published advisories, so they are left out unless a site asks for them, and a footer set with footer replaces the standard one either way. Default value: "0". @@ -312,25 +302,24 @@ footer:: head-include:: The content of the file specified with this option will be included - verbatim in the html HEAD section on all pages. Default value: none. + verbatim in the HTML head section on all pages. Default value: none. header:: The content of the file specified with this option will be included verbatim at the top of all pages. Default value: none. include:: - Name of a configfile to include before the rest of the current - configfile is parsed. Includes may nest eight levels deep, and anything + Name of a config file to include before the rest of the current + config file is parsed. Includes may nest eight levels deep, and anything deeper is ignored. 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". May be given multiple times, each - script URL path is added in the head section of the document in turn. - Each is loaded with defer, so it runs once the page has been parsed, - still in the order given. - Setting this to an empty string will disable generation of the link to - this file in the head section. + Url which specifies the JavaScript document to include in all cgit + pages. May be given multiple times, and each script url path is + added in the head section of the document in turn. Each is loaded with + defer, so it runs once the page has been parsed, still in the order + given. Setting this to an empty string will disable generation of the + link to this file in the head section. Default value: "/cgit.js". local-time:: Flag which, if set to "1", makes cgit print commit and tag times in the @@ -350,9 +339,11 @@ max-atom-items:: max-blob-size:: Specifies the maximum size in KBytes of a blob that cgit will read into - memory to serve. It caps both the HTML blob page and the raw "plain" and - "blob" output, and a larger object is refused rather than loaded whole. - Default value: "10240" (10 MB). Set to "0" to disable the limit. + memory to serve. The tree page's file view, the blame page, a tracked + readme, a snapshot signature and the raw "plain" and "blob" output all + refuse a larger object rather than load it whole, and the diff and patch + pages show it as binary. Set to "0" to disable the limit. Default value: + "10240" (10 MB). max-commit-count:: Specifies the number of entries to list per page in "log" page. Default @@ -361,14 +352,14 @@ max-commit-count:: max-diff-files:: If a commit changes more files than this, the "commit" and "diff" pages show only the diffstat, where each file links to its own diff page. The - "rawdiff" and "patch" pages are never limited. Default value: "200". Set - to "0" to always render every file inline. + "rawdiff" and "patch" pages are never limited. Set to "0" to always + render every file inline. Default value: "200". max-diff-lines:: If a single file's diff spans more lines than this, the whole-commit pages print a note in its place linking to the file's own diff page, - which always renders in full. Default value: "1000". Set to "0" to - always render oversized files inline. + which always renders in full. Set to "0" to always render oversized + files inline. Default value: "1000". max-message-length:: Specifies the maximum number of commit message characters to display in @@ -377,13 +368,13 @@ max-message-length:: max-patch-count:: Specifies the maximum number of commits emitted as a series by the "patch" page when an explicit revision range is requested. A single - commit is unaffected. Default value: "50". Set to "0" for no limit. + commit is unaffected. Set to "0" for no limit. Default value: "50". max-ref-count:: Specifies the number of branches and tags to list per section on the "refs" page, and per page on the dedicated branch and tag pages that its - overflow links lead to. Default value: "200". A value of "0" or less lists - every ref on one page. + overflow links lead to. A value of "0" or less lists every ref on one + page. Default value: "200". max-repo-count:: Specifies the number of entries to list per page on the repository index @@ -405,10 +396,7 @@ mimetype-file:: Specifies the file to use for automatic mimetype lookup. If specified then this field is used as a fallback when no "mimetype.<ext>" match is found. If unspecified then no such lookup is performed. The typical file - to use on a Linux system is /etc/mime.types. Each line in the file holds - a mimetype, like image/png, followed by one or more file extensions, - like jpg, separated by whitespace. Empty lines and lines whose first - non-blank character is a hash are ignored. Default value: none. See + to use on a Linux system is /etc/mime.types. Default value: none. See also: "mimetype.<ext>". mimetype.<ext>:: @@ -417,27 +405,28 @@ mimetype.<ext>:: "mimetype-file". module-link:: - Text which will be used as the formatstring for a hyperlink when a + Text which will be used as the format string for a hyperlink when a submodule is printed in a directory listing. The arguments for the - formatstring are the name of the submodule directory and the object id + format string are the name of the submodule directory and the object id of the submodule commit. Default value: none. project-list:: - A list of subdirectories inside of scan-path, relative to it, that + A file listing the subdirectories of scan-path, relative to it, that should be loaded as git repositories. This must be defined prior to - scan-path. Default value: none. See also: scan-path, "Macro expansion". + scan-path. Default value: none. See also: "scan-path", "Macro + expansion". readme:: Text which will be used as default value for "repo.readme". Multiple config keys may be specified, and cgit will use the first found file in this list. This is useful in conjunction with scan-path. Default value: - none. See also: scan-path, repo.readme. + none. See also: "scan-path", "repo.readme". remove-suffix:: If set to "1" and scan-path is enabled, if any repositories are found with a suffix of ".git", this suffix will be removed for the url and name. This must be defined prior to scan-path. Default value: "0". See - also: scan-path. + also: "scan-path". rename-limit:: Maximum number of files to consider when detecting renames. The value @@ -448,7 +437,7 @@ repository-sort:: The way in which repositories in each section are sorted. Valid values are "name" for sorting by the repository name or "age" for sorting by the most recently updated repository. Default value: "name". See also: - section, case-sensitive-sort, section-sort. + "section", "case-sensitive-sort", "section-sort". robots:: Text used as content for the "robots" meta-tag. Default value: "index, @@ -473,7 +462,7 @@ scan-hidden-path:: directories whose name starts with a period ('.'). Otherwise, scan-path skips such directories as hidden. The ".git" directory of a non-bare repository is still found. This must be defined prior to scan-path. - Default value: "0". See also: scan-path. + Default value: "0". See also: "scan-path". scan-path:: A path which is scanned for repositories. If caching is enabled, the @@ -487,8 +476,8 @@ scan-path:: filters and the enable flags, not only the entries that say so explicitly. The readme list is the exception, since a repository with none of its own follows the global list as the whole cgitrc leaves it. - Default value: none. See also: cache-scan-ttl, project-list, - strict-export, "Macro expansion". + Default value: none. See also: "cache-scan-ttl", "project-list", + "strict-export", "Macro expansion". section:: The name of the current repository section. All repositories defined @@ -498,14 +487,16 @@ section:: section-from-path:: A number which, if defined prior to scan-path, specifies how many path elements from each repository path to use as a default section name. If - negative, cgit discards the specified number of path elements above the - repository directory. Default value: "0". + negative, cgit instead drops that many path elements from the end, the + repository directory included, so "-1" uses every directory above the + repository. Default value: "0". section-sort:: Flag which, when set to "1", sorts the sections on the repository listing by name, along with the repositories within each section. Set this flag to "0" to preserve the order in the cgitrc file. Default - value: "0". See also: section, case-sensitive-sort, repository-sort. + value: "0". See also: "section", "case-sensitive-sort", + "repository-sort". side-by-side-diffs:: If set to "1" shows side-by-side diffs instead of unidiffs by default. @@ -515,19 +506,17 @@ 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. + and "zip". The special value "all" enables all snapshot formats. All + compressors use default settings. Some settings can be influenced with + environment variables, for example set ZSTD_CLEVEL=10 in the web server + environment for higher (but slower) zstd compression. Default value: + none. source-filter:: Specifies a command which will be invoked to format plaintext blobs in - the tree and blame pages. The command will get the blob content on its - stdin and the name of the blob as its only command line argument. The - stdout from the command will be included verbatim as the blob contents, - which is how syntax highlighting is done. When no source-filter is - configured, cgit serves the text plain. A ready syntax highlighter using - the Scintillua lexer collection ships as + the tree and blame pages, which is how syntax highlighting is done. When + no source-filter is configured, cgit serves the text plain. A ready + syntax highlighter using the Scintillua lexer collection ships as custom/extensions/syntax-highlight.lua, see the comments in that file for its dependencies. Default value: none. See also: "Filter API". @@ -536,11 +525,11 @@ strict-export:: for cgit to allow access to that repository. This can be used to emulate gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's repositories to match those exported by git-daemon. This option must be - defined prior to scan-path. Default value: none. See also: scan-path. + defined prior to scan-path. Default value: none. See also: "scan-path". summary-branches:: Specifies the number of branches to display in the repository "summary" - page. Default value: "10". A value of "0" or less lists every branch. + page. A value of "0" or less lists every branch. Default value: "10". summary-log:: Specifies the number of log entries to display in the repository @@ -548,19 +537,17 @@ summary-log:: summary-tags:: Specifies the number of tags to display in the repository "summary" - page. Default value: "10". A value of "0" or less lists every tag. + page. A value of "0" or less lists every tag. Default value: "10". trailer-filter:: Specifies a command which will be invoked to format the value of a - commit trailer when "enable-commit-trailers" is set. The command will - get the trailer key and an origin page string as its command line - arguments and the value on its stdin, and the stdout from the command - will be included verbatim as the value. Trailers whose value is a name - and email address, such as Signed-off-by, go through the email-filter - instead, and when no trailer-filter is configured the remaining values - go through the commit-filter. A ready filter linking Fixes, Reverts, - Closes, Bug and URL values ships as custom/extensions/link-trailers.lua. - Default value: none. See also: "Filter API". + commit trailer when "enable-commit-trailers" is set. Trailers whose + value is a name and email address, such as Signed-off-by, go through + the email-filter instead, and when no trailer-filter is configured the + remaining values go through the commit-filter. A ready filter linking + Fixes, Reverts, Closes, Bug and URL values ships as + custom/extensions/link-trailers.lua. Default value: none. See also: + "Filter API". trust-scan-config:: Flag which, when set to "1", honours every setting in a repository's own @@ -568,16 +555,16 @@ trust-scan-config:: whoever can push to the repository, so without it the settings that run a command, put raw markup on the page, serve a file as markup, place a link or read a file off the disk are ignored with a warning. Those are - the filters, head-content, module-link, logo, logo-link, clone-url, - enable-html-serving and a readme that names a file rather than a git - object. Settings in the main cgitrc, the "repo.<option>" form included, - never need this. Default value: "0". See also: "scan-path", - "enable-git-config". + the filters, head-content, module-link, module-link.<path>, logo, + logo-link, clone-url, enable-html-serving and a readme that names a file + rather than a git object. Settings in the main cgitrc, the + "repo.<option>" form included, never need this. Default value: "0". See + also: "scan-path", "enable-git-config". virtual-root:: - Url which, if specified, is used as root for all cgit links. cgit then - generates virtual urls such as "/cgit/tree/README" in place of - "?url=cgit/tree/README". Default value: none. + Url used as root for all cgit links, such as "/cgit/" for links like + "/cgit/repo/tree/README". Default value: SCRIPT_NAME followed by a + slash. Repository settings @@ -588,9 +575,7 @@ repo.about-filter:: also: "Filter API", "trust-scan-config". repo.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: <branch-sort>. + Override the default branch-sort. Default value: <branch-sort>. repo.clone-url:: A list of space-separated urls which can be used to clone this @@ -601,10 +586,7 @@ repo.commit-filter:: also: "Filter API", "trust-scan-config". repo.commit-sort:: - Flag which, when set to "date", enables strict date ordering in the - commit log, and when set to "topo" enables strict topological ordering. - If unset, the default ordering of "git log" is used. Default value: - <commit-sort>. + Override the default commit-sort. Default value: <commit-sort>. repo.defbranch:: The name of the default branch for this repository. If no such branch @@ -667,7 +649,7 @@ repo.enable-subject-links:: "enable-subject-links". Default value: <enable-subject-links>. repo.head-content:: - This value will be added verbatim to the html HEAD section of each page + This value will be added verbatim to the HTML head section of each page displayed for this repository. Default value: none. See also: "head-include". @@ -682,12 +664,10 @@ repo.ignore:: 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 repository's pages. Default value: <logo>. + Override the default logo. Default value: <logo>. repo.logo-link:: - Url loaded when clicking on the cgit logo image. Default value: - <logo-link>. + Override the default logo-link. Default value: <logo-link>. repo.max-stats:: Override the default maximum statistics period. Valid values are equal @@ -696,15 +676,12 @@ repo.max-stats:: <max-stats>. 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 - formatstring are the name of the submodule directory and the object id - of the submodule commit. Default value: <module-link>. + Override the default module-link. Default value: <module-link>. repo.module-link.<path>:: - Text which will be used as the formatstring for a hyperlink when a + Text which will be used as the format string for a hyperlink when a submodule with the specified subdirectory path is printed in a directory - listing. The only argument for the formatstring is the object id of the + listing. The only argument for the format string is the object id of the submodule commit. Default value: none. repo.name:: @@ -764,10 +741,7 @@ When the option "scan-path" is used to auto-discover git repositories, cgit tries to parse the file "cgitrc" within any found repository. Such a file may contain any of the repository settings described above, except "repo.url" and "repo.path", with the "repo." prefix dropped, so "repo.desc" becomes "desc". The -options that run a command, put raw markup on the page, serve a file as markup, -place a link or read a file off the disk are only honoured when -"trust-scan-config" is set to "1", since the file belongs to whoever can push to -the repository. +settings "trust-scan-config" guards are only honoured when it is set to "1". Filter API @@ -806,9 +780,9 @@ specification with one of these strings. '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. + 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. + Url escapes for an argument and writes 'str' to the webpage. 'html_include(file)':: Includes 'file' in webpage. @@ -922,15 +896,11 @@ environment variable. Macro expansion will also happen on the content of $CGIT_CONFIG, if defined. -The set of available variables is not fixed by cgit. The options above are -expanded while the configuration is parsed, against whatever environment the web -server hands the cgit process, so any variable the server sets can be used. A -CGI server provides the standard request variables, among them $HTTP_HOST, -$HTTPS, $PATH_INFO, $QUERY_STRING, $REQUEST_METHOD, $SCRIPT_NAME, $SERVER_NAME -and $SERVER_PORT, and server directives such as SetEnv (Apache), fastcgi_param -(nginx) or setenv.add-environment (lighttpd) can add anything else. cgit unsets -$HOME and $XDG_CONFIG_HOME before reading its configuration, so those two never -expand. +The options above are expanded while the configuration is parsed. Any variable +in the environment the web server hands cgit can be used, from the CGI request +variables such as $HTTP_HOST to anything set with SetEnv (Apache), fastcgi_param +(nginx) or setenv.add-environment (lighttpd). cgit unsets $HOME and +$XDG_CONFIG_HOME before reading its configuration, so those two never expand. One usage of this feature is virtual hosting, which in its simplest form can be accomplished by adding a line like this one to /etc/cgitrc. @@ -948,20 +918,24 @@ The 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 +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. The files of the dumb transport are never cached, since they already -sit on the disk, and a response larger than "cache-max-slot-size" is served but -not kept. - -The cache directory holds one file per slot plus transient lock files, all -created by cgit itself. Create the directory ahead of time, owned by the account -the web server runs cgit as, with mode 0700. cgit creates its files by name -without guarding against links planted beside them, so a directory other -accounts can write to would let those accounts redirect the writes. A directory -other accounts can read exposes every cached page along with the URLs visitors -asked for. +page type. A response larger than "cache-max-slot-size" is served but not kept. + +The cache directory holds one file per slot and the cached results of scan-path +as rc-* files, plus transient lock files, all created by cgit itself. Create the +directory ahead of time, owned by the account the web server runs cgit as, with +mode 0700. cgit creates its files by name without guarding against links planted +beside them, so a directory other accounts can write to would let those accounts +redirect the writes. A directory other accounts can read exposes every cached +page along with the urls visitors asked for. + +A slot or a scan result is rebuilt only by the process holding an flock on its +lock file. A request that finds the lock held serves the expired copy, or goes +without the cache when there is none, and logs nothing. Any other failure to +open, lock or write a lock file is logged with its path, apart from one in the +background rebuild of an expired scan result, whose output is discarded. Signatures |