Merge pull request #127 from ganto/feature/readme-update

Readme: Document newly added 'exclude' attribute

Author: ganto

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
 

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 `<pkgproxy>` with the host name of the pkgproxy instance: