From 522393b616095c87360ba029e1cf5aa0d58d15bc Mon Sep 17 00:00:00 2001 From: Bryce Kwon Date: Sat, 31 Oct 2026 14:53:34 -0700 Subject: Describe the cache's scan files and its locking The background rebuild points its stderr at /dev/null so the web server does not wait on it, which is why its failures never reach the log. --- MANUAL.txt | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index e3da45f..18c5129 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -921,13 +921,19 @@ 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. 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. +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 -- cgit