mirror of
https://github.com/renovatebot/renovate.git
synced 2025-01-11 05:39:10 +00:00
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# String Pattern Matching - Regex or Glob
|
|
|
|
Renovate string matching syntax for some configuration options allows you, as user, to choose between:
|
|
|
|
- [`minimatch`](https://github.com/isaacs/minimatch) glob patterns, including exact strings matches
|
|
- regular expression (regex) patterns
|
|
|
|
In cases where there are potentially multiple _inputs_, e.g. managers can have multiple categories, then the matcher will return `true` if _any_ of them match.
|
|
|
|
## Special case: Match everything
|
|
|
|
The value `*` is a special case which means "match everything".
|
|
It is not valid to combine `*` with any other positive or negative match.
|
|
|
|
```json title="Example of valid wildcard use"
|
|
{
|
|
"allowedEnv": ["*"]
|
|
}
|
|
```
|
|
|
|
```json title="Example of invalid wildcard use with additional match"
|
|
{
|
|
"allowedEnv": ["*", "ABC"]
|
|
}
|
|
```
|
|
|
|
```json title="Example of invalid wildcard use with negation"
|
|
{
|
|
"allowedEnv": ["*", "!ABC"]
|
|
}
|
|
```
|
|
|
|
In the latter case, the `*` can be ommitted and achieve the same thing.
|
|
|
|
## Regex matching
|
|
|
|
A valid regex pattern:
|
|
|
|
1. Starts with `/` or `!/`
|
|
1. Ends with `/` or `/i`
|
|
|
|
### Regex is case sensitive by default
|
|
|
|
By default, regex patterns are evaluated as case sensitive.
|
|
To ignore case sensitivity you must set the `i` flag, see the regex patterns table for an example.
|
|
|
|
### Renovate uses re2 syntax
|
|
|
|
Renovate uses the [`re2` library](https://github.com/google/re2) for regex matching.
|
|
`re2` is different from the full regex specification, because `re2` has a different sytax/support.
|
|
|
|
For the full `re2` syntax, read [the `re2` syntax wiki page](https://github.com/google/re2/wiki/Syntax).
|
|
|
|
### Example regex patterns
|
|
|
|
| Pattern | Regex pattern explanation |
|
|
| --------- | ----------------------------------------------------------------------- |
|
|
| `/^abc/` | matches any string starting with lower-case `abc` |
|
|
| `/^abc/i` | matches any string starting with `abc` in lower or upper case, or a mix |
|
|
| `!/^a/` | matches any string not starting with `a` in lower case |
|
|
|
|
### Use regex101 to test your patterns
|
|
|
|
If you want to test your patterns interactively online, we recommend [regex101.com](https://regex101.com/?flavor=javascript&flags=ginst).
|
|
You can use the Code Generator in the sidebar and copy the regex in the generated "Alternative syntax" comment into JSON.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! warning "Escape the backslashes from regex101"
|
|
Before you copy/paste the regex from regex101 into your Renovate config, you must escape the backslashes (`\`) first.
|
|
For example: `\n\s` --> `\\n\\s`.
|
|
|
|
## Glob matching
|
|
|
|
If the string provided is not a regex pattern then it will be treated as a glob pattern and parsed using the `minimatch` library.
|
|
Although glob patterns were designed originally for file name matching, many users find glob syntax easier to understand than regex so prefer it.
|
|
|
|
### Glob patterns always ignore casing
|
|
|
|
Glob patterns are always evaluated with case _insensitivity_ and you can not change this.
|
|
If you need a case-sensitive pattern you must use a regex pattern.
|
|
|
|
### Example glob patterns
|
|
|
|
| Pattern | Glob pattern explanation |
|
|
| ----------- | ------------------------------------------------------------ |
|
|
| `abc123` | matches `abc123` exactly, or `AbC123` |
|
|
| `abc*` | matches `abc`, `abc123`, `ABCabc`, but not `abc/def` |
|
|
| `abc**/*` | matches `abc/def` but not `abc`, `abcd`, or `abc/def/ghi`, |
|
|
| `abc**/**` | matches `abc/def` and `abc/def/ghi`, but not `abc` or `abcd` |
|
|
| `abc{/,}**` | matches `abc`, `abcd`, `abc/def`, and `abc/def/ghi` |
|
|
|
|
All matches above are case-insensitive, even if not shown.
|
|
|
|
## Negative matching
|
|
|
|
Renovate has a specific approach to negative matching strings.
|
|
|
|
"Positive" matches are patterns (in glob or regex) which do _not_ start with `!`.
|
|
"Negative" matches are patterns starting with `!`, like `!/^a/` or `!b*`.
|
|
|
|
For an array of patterns to match, the following must be true:
|
|
|
|
- If any _positive_ matches are included, at least _one_ must match
|
|
- If any _negative_ matches are included, _none_ must match
|
|
|
|
For example, the pattern `["/^abc/", "!/^abcd/", "!/abce/"]`:
|
|
|
|
- matches `"abc"` and `"abcf"`
|
|
- does _not_ match `"foo"`, `"abcd"`, `"abce"`, or `"abcdef"`
|
|
|
|
If you find yourself in a situation where you need to positive-match a string which starts with `!`, then you need to do so using a regular expression pattern.
|
|
For example, `["/^!abc$/"]` will positively match against the string `"!abc"`.
|
|
|
|
One limitation of negative matching is when there may be multiple inputs to match against.
|
|
For example, a manager may have multiple categories, such as `java` and `docker`.
|
|
If you have a rule such as `"matchCategories": ["!docker"]` then this will return `true` because the `java` category satisfies this rule.
|
|
|
|
## Usage in Renovate configuration options
|
|
|
|
Renovate has evolved its approach to string pattern matching over time, but this means that existing configurations may have a mix of approaches and not be entirely consistent with each other.
|
|
|
|
The configuration options that support "regex or glob" syntax mention this in their documentation, and also link to this page.
|