From ce230b44c70144cb55d07c746cf0fb396b98038c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=B3bert=20Papp?= <papp.robert.s@gmail.com>
Date: Tue, 28 May 2024 06:22:49 +0100
Subject: [PATCH] docs: packageRules overview and evaluation details (#29264)
---
docs/usage/configuration-options.md | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md
index 90be5223c0..7f14d471c4 100644
--- a/docs/usage/configuration-options.md
+++ b/docs/usage/configuration-options.md
@@ -2384,6 +2384,24 @@ Renovate only queries the OSV database for dependencies that use one of these da
`packageRules` is a powerful feature that lets you apply rules to individual packages or to groups of packages using regex pattern matching.
+`packageRules` is a collection of rules, that are **all** evaluated.
+If multiple rules match a dependency, configurations from matching rules will be merged together.
+The order of rules matters, because later rules may override configuration options from earlier ones, if they both specify the same option.
+
+The matching process for a package rule:
+
+- Each package rule can include `match...` matchers to identify dependencies and `exclude...` matchers to filter them out.
+- If no match/exclude matchers are defined, everything matches.
+- If an aspect is both `match`ed and `exclude`d, the exclusion wins.
+- Multiple values within a single matcher will be evaluated independently (they're OR-ed together).
+- Combining multiple matchers will restrict the resulting matches (they're AND-ed together):
+ `matchCurrentVersion`, `matchCurrentValue`, `matchNewValue`, `matchConfidence`, `matchCurrentAge`,
+ `matchManagers`, `matchDatasources`, `matchCategories`, `matchDepTypes`, `matchUpdateTypes`,
+ `matchRepositories`/`excludeRepositories`, `matchBaseBranches`, `matchFileNames`
+- Two special groups of matchers provide alternatives (they're OR-ed within their respective groups, and AND-ed with others):
+ - Source URL: `matchSourceUrls`, `matchSourceUrlPrefixes`
+ - Package/Dep identifiers: `matchDepNames`/`excludeDepNames`, `matchDepPatterns`/`excludeDepPatterns`, `matchDepPrefixes`/`excludeDepPrefixes`, `matchPackageNames`/`excludePackageNames`, `matchPackagePatterns`/`excludePackagePatterns`, `matchPackagePrefixes`/`excludePackagePrefixes`
+
Here is an example if you want to group together all packages starting with `eslint` into a single branch/PR:
```json
@@ -2463,7 +2481,6 @@ For example you have multiple `package.json` and want to use `dependencyDashboar
<!-- prettier-ignore -->
!!! tip
- Renovate evaluates all `packageRules` and does not stop after the first match.
Order your `packageRules` so the least important rules are at the _top_, and the most important rules at the _bottom_.
This way important rules override settings from earlier rules if needed.
--
GitLab