From d74d6cfdf2d5f35add5ecd9c104817fe5d9a0eb9 Mon Sep 17 00:00:00 2001 From: CodeX Date: Fri, 10 Apr 2026 16:26:27 +0200 Subject: [PATCH] Distinguish qBittorrent and Cleanuparr pattern syntax in Lists --- Lists.md | 79 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/Lists.md b/Lists.md index 4243e1d..1e8a84d 100644 --- a/Lists.md +++ b/Lists.md @@ -90,27 +90,70 @@ has the entry, the entry stays gone (which is probably what you want). ## Pattern syntax -Each line in `blacklist` and `whitelist` is a pattern. The forms supported -are the same forms that qBittorrent's excluded file names accepts, since -that is where blacklist patterns ultimately end up via Cleanuparr's -Blocklist Sync: +The patterns in `blacklist` and `whitelist` are consumed by two tools with +different pattern capabilities. This section documents both and explains +which to use. -| Form | Example | Matches | -|---|---|---| -| `*example` | `*.srt` | File name ends with `example` | -| `example*` | `sample*` | File name starts with `example` | -| `*example*` | `*sample*` | File name contains `example` | -| `example` | `RARBG.txt` | File name is exactly `example` | -| `regex:` | `regex:.*\.srt$` | File name matches the regex | +### qBittorrent (via Blocklist Sync) -Cleanuparr's Malware Blocker accepts the same forms when reading the -whitelist for Sonarr/Radarr queue inspection, so a single set of pattern -forms covers both consumers. +qBittorrent's "Excluded file names" field uses Qt glob wildcards +(internally `QRegularExpression::fromWildcard()`). The following forms are +supported: -The forms are not interchangeable from the merge script's point of view. -`*.srt` and `regex:.*\.srt$` describe the same set of files but are -different strings. The whitelist subtraction (next section) is exact-string, -so picking one form and using it consistently in both files matters. +| Pattern | Meaning | Example | Matches | +|---|---|---|---| +| `*` | Zero or more characters | `*.srt` | Any file ending in `.srt` | +| `?` | Exactly one character | `*.r??` | `.r00`, `.r01`, ..., `.r99` | +| `[abc]` | One character from the set | `*.[rs]00` | `.r00` or `.s00` | +| `[a-z]` | One character in the range | `*.[r-z]??` | `.r00` through `.z99` | +| `[!abc]` | One character NOT in the set | `*.[!m]??` | Any 3-char ext not starting with `m` | +| Literal | Exact string match | `VOSTFR` | A file named exactly `VOSTFR` | + +**Not supported by qBittorrent:** regex syntax (`^`, `$`, `\d`, `\w`, +`(?i)`, `+`, etc.), backslash escapes (backslash is not an escape +character in Qt glob), and the `regex:` prefix. Any of these will be +silently ignored or matched literally, causing the pattern to fail. + +To match special glob characters literally, place them in brackets: +`[?]` matches a literal question mark, `[*]` matches a literal asterisk. + +Reference: [Qt 6 QRegularExpression::fromWildcard](https://doc.qt.io/qt-6/qregularexpression.html#fromWildcard) + +### Cleanuparr Malware Blocker (Sonarr/Radarr queue) + +Cleanuparr's Malware Blocker supports all the wildcard forms above plus +regex with the `regex:` prefix: + +``` +regex:.*\.srt$ +``` + +Regex patterns only work in Cleanuparr's Malware Blocker when it reads the +whitelist (or blacklist) directly for queue inspection. They do **not** +work when pushed to qBittorrent via Blocklist Sync, because qBittorrent +does not understand the `regex:` prefix. + +### Which forms to use + +Since the blacklist is pushed to qBittorrent via Blocklist Sync, all +entries in `blacklist` and `whitelist` should use **wildcard forms only** +(the first six rows in the table above). This ensures patterns work in +both consumers: + +- qBittorrent (via Blocklist Sync) -- wildcards only +- Cleanuparr Malware Blocker (direct) -- wildcards and regex both work + +Using wildcards everywhere is the safe default. Avoid `regex:` unless you +are certain the pattern will only be consumed by Cleanuparr's Malware +Blocker and never pushed to qBittorrent. + +### Merge script interaction + +The merge script subtracts the whitelist from the blacklist as exact +strings, not by pattern semantics. The forms are not interchangeable: +`*.srt` and `*.[s]rt` describe the same files but are different strings, +so putting one in the whitelist will not strip the other from the +blacklist. Pick one form and use it consistently in both files. ## Pattern matching