From e9efe5a51d86fbf2166ade7ce941ef711b6c68e5 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Mon, 6 Apr 2026 17:21:52 +0200 Subject: [PATCH] Readme: Document newly added 'exclude' attribute --- CLAUDE.md | 1 + README.md | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9a312a9..39804a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,6 +34,7 @@ pre-commit run codespell --all-files - E2e tests must pass before a feature is considered complete. - Adding support for a new Linux distribution requires adding corresponding e2e tests. - Changes to client config snippets (sources.list, .repo files) must be replicated in the landing page snippets and in README.md. +- New or changed configuration options (CLI flags, repository config keys) must be documented in README.md. ## OpenSpec diff --git a/README.md b/README.md index be09959..9449f5a 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,8 @@ Each repository supports the following options: | Key | Required | Description | |-----|----------|-------------| -| `suffixes` | yes | File suffixes that are eligible for caching (e.g. `.rpm`, `.deb`) | +| `suffixes` | yes | File suffixes that are eligible for caching (e.g. `.rpm`, `.deb`). Use `"*"` to cache all files. | +| `exclude` | no | List of file names to exclude from caching, even when they match a suffix. Useful with the `"*"` wildcard suffix. | | `mirrors` | yes | Ordered list of upstream mirror URLs | | `retries` | no | Number of attempts per mirror before moving to the next one (default: `1`) | @@ -73,6 +74,29 @@ on to the next one. An exponential backoff is applied between retry attempts (1s, 2s, 4s, ...). Only 5xx (server error) responses trigger a retry — client errors like 404 are returned immediately. +### Cache exclusions + +When using the wildcard suffix `"*"` to cache all files, certain files (such as +metadata or timestamps) should not be cached because they change frequently. The +`exclude` option lets you list file names that will always be fetched from +upstream, bypassing the cache: + +```yaml +repositories: + gentoo: + suffixes: + - "*" + exclude: + - layout.conf + - timestamp.mirmon + - timestamp.dev-local + mirrors: + - https://distfiles.gentoo.org/ +``` + +Files whose name matches an entry in the `exclude` list are served directly from +the upstream mirror without being stored in the local cache. + ## Client Configuration With the provided configuration a number of Linux distributions are handled. See below where and how the clients must be adjusted to use your instance of pkgproxy. Replace `` with the host name of the pkgproxy instance: