docs: string pattern matching (#27387)

Co-authored-by: RahulGautamSingh <rahultesnik@gmail.com>
Co-authored-by: Sebastian Poxhofer <secustor@users.noreply.github.com>

docs/usage/.pages

@@ -50,6 +50,7 @@ nav:
       - 'Security and Permissions': 'security-and-permissions.md'
       - 'Merge Confidence': 'merge-confidence.md'
       - 'Templates': 'templates.md'
+      - 'String Pattern Matching': 'string-pattern-matching.md'
       - 'Frequently Asked Questions': 'faq.md'
       - 'Known Limitations': 'known-limitations.md'
       - 'Release notes for major versions': 'release-notes-for-major-versions.md'

docs/usage/configuration-options.md

@@ -2574,7 +2574,7 @@ Use this field to restrict rules to a particular repository. e.g.
 }
 ```
 
-This field supports Regular Expressions if they begin and end with `/`, otherwise it will use `minimatch`.
+For more details on supported syntax see Renovate's [string pattern matching documentation](./string-pattern-matching.md).
 
 ### matchBaseBranches
 
@@ -2627,22 +2627,8 @@ For the full list of available managers, see the [Supported Managers](modules/ma
 ### matchMessage
 
 For log level remapping, use this field to match against the particular log messages.
-You can match based on any of the following:
-
-- an exact match string (e.g. `This is the string`)
-- a minimatch pattern (e.g. `This*`)
-- a regex pattern (e.g. `/^This/`)
 
-```json
-{
-  "logLevelRemap": [
-    {
-      "matchMessage": "Manager explicitly enabled*",
-      "newLogLevel": "warn"
-    }
-  ]
-}
-```
+For more details on supported syntax see Renovate's [string pattern matching documentation](./string-pattern-matching.md).
 
 ### matchDatasources
 

docs/usage/self-hosted-configuration.md

@@ -70,6 +70,7 @@ By default, all headers starting with "X-" are allowed.
 If needed, you can allow additional headers with the `allowedHeaders` option.
 Any set `allowedHeaders` overrides the default "X-" allowed headers, so you should include them in your config if you wish for them to remain allowed.
 The `allowedHeaders` config option takes an array of minimatch-compatible globs or re2-compatible regex strings.
+For more details on this syntax see Renovate's [string pattern matching documentation](./string-pattern-matching.md).
 
 Examples:
 

docs/usage/string-pattern-matching.md

@@ -0,0 +1,37 @@
+# String Pattern Matching - Regex or Glob
+
+Renovate string matching syntax for some configuration options allows the user to choose between [`minimatch`](https://github.com/isaacs/minimatch) glob patterns, including exact strings matches, or regular expression (regex) patterns.
+
+## Regex matching
+
+Users can choose to use regex patterns by starting the pattern string with `/` and ending with `/` or `/i`.
+Regex patterns are evaluated with case sensitivity unless the `i` flag is specified.
+
+Renovate uses the [`re2`](https://github.com/google/re2) library for regex matching, which is not entirely the same syntax/support as the full regex specification.
+For a full list of re2 syntax, see [the re2 syntax wiki page](https://github.com/google/re2/wiki/Syntax).
+
+Example regex patterns:
+
+- `/^abc/` is a regex pattern matching any string starting with lower-case `abc`.
+- `^abc/i` is a regex pattern matching any string starting with `abc` in lower or upper case, or a mix.
+
+If you want to test your patterns interactively online, we recommend [regex101.com](https://regex101.com/?flavor=javascript&flags=ginst).
+Be aware that backslashes (`\`) of the resulting regex have to still be escaped e.g. `\n\s` --> `\\n\\s`. You can use the Code Generator in the sidebar and copy the regex in the generated "Alternative syntax" comment into JSON.
+
+## 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 are evaluated with case _insensitivity_ and this is not configurable, so if you require a case-sensitive pattern then you should use a regex pattern instead.
+
+Examples:
+
+- `abc123` matches `abc123` exactly, or `AbC123`.
+- `abc*` matches `abc`, `abc123`, `ABCabc`, etc.
+
+## Usage in Renovate configuration options
+
+Renovate has matured 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 which support this "regex or glob" syntax have it noted in their documentation with a link to this page for more details.