The `regex` manager is designed to allow users to manually configure Renovate for how to find dependencies that aren't detected by the built-in package managers.
With the `regex` manager you can configure Renovate so it finds dependencies that are not detected by its other built-in package managers.
This manager is unique in Renovate in that:
The `regex` manager is unique in Renovate because:
- It is configurable via regex named capture groups
- It is configurable via regex named capture groups
- Through the use of the `regexManagers` config, multiple "regex managers" can be created for the same repository
- It can extract any `datasource`
- It can extract any `datasource`
- By using the `regexManagers` config, you can create multiple "regex managers" for the same repository
We have [additional Handlebars helpers](https://docs.renovatebot.com/templates/#additional-handlebars-helpers)which help you perform common transformations on the regex manager's template fields.
We have [additional Handlebars helpers](https://docs.renovatebot.com/templates/#additional-handlebars-helpers)to help you perform common transformations on the regex manager's template fields.
Also read the documentation for the [`regexManagers` config option](https://docs.renovatebot.com/configuration-options/#regexmanagers).
Also read the documentation for the [`regexManagers` config option](https://docs.renovatebot.com/configuration-options/#regexmanagers).
### Required Fields
### Required Fields
The first two required fields are `fileMatch` and `matchStrings`.
The first two required fields are `fileMatch` and `matchStrings`:
`fileMatch` works the same as any manager, while `matchStrings` is a `regexManagers` concept and is used for configuring a regular expression with named capture groups.
In order for Renovate to look up a dependency and decide about updates, it then needs the following information about each dependency:
-`fileMatch` works the same as any manager
-`matchStrings` is a `regexManagers` concept and is used for configuring a regular expression with named capture groups
Before Renovate can look up a dependency and decide about updates, it needs this information about each dependency:
- The dependency's name
- The dependency's name
- Which `datasource` to look up (e.g. npm, Docker, GitHub tags, etc)
- Which `datasource` to use: npm, Docker, GitHub tags, and so on. For how to format this references see [datasource overview](https://docs.renovatebot.com/modules/datasource/#supported-datasources)
- Which version scheme to apply (defaults to `semver`, but also may be other values like `pep440`)
- Which version scheme to use: defaults to `semver`, but you may set another value like `pep440`. Supported versioning schemes can be found in the [versioning overview](https://docs.renovatebot.com/modules/versioning/#supported-versioning)
Configuration-wise, it works like this:
Configuration-wise, it works like this:
...
@@ -35,9 +37,10 @@ Configuration-wise, it works like this:
...
@@ -35,9 +37,10 @@ Configuration-wise, it works like this:
### Regular Expression Capture Groups
### Regular Expression Capture Groups
To be fully effective with the regex manager, you will need to understand regular expressions and named capture groups, although sometimes enough examples can compensate for lack of experience.
To be effective with the regex manager, you should understand regular expressions and named capture groups.
But enough examples may compensate for lack of experience.
Consider this `Dockerfile`:
Take this `Dockerfile` as an example:
```Dockerfile
```Dockerfile
FROM node:12
FROM node:12
...
@@ -45,19 +48,19 @@ ENV YARN_VERSION=1.19.1
...
@@ -45,19 +48,19 @@ ENV YARN_VERSION=1.19.1
RUN curl -o--L https://yarnpkg.com/install.sh | bash -s----version${YARN_VERSION}
RUN curl -o--L https://yarnpkg.com/install.sh | bash -s----version${YARN_VERSION}
```
```
You would need to capture the `currentValue`using a named capture group, like so: `ENV YARN_VERSION=(?<currentValue>.*?)\\n`.
You would need to capture the `currentValue`with a named capture group, like this: `ENV YARN_VERSION=(?<currentValue>.*?)\\n`.
If you're looking for an online regex testing tool that supports capture groups, try [https://regex101.com/](<https://regex101.com/?flavor=javascript&flags=g®ex=ENV%20YARN_VERSION%3D(%3F%3CcurrentValue%3E.*%3F)%5Cn&testString=FROM%20node%3A12%0AENV%20YARN_VERSION%3D1.19.1%0ARUN%20curl%20-o-%20-L%20https%3A%2F%2Fyarnpkg.com%2Finstall.sh%20%7C%20bash%20-s%20--%20--version%20%24%7BYARN_VERSION%7D>).
If you're looking for an online regex testing tool that supports capture groups, try [https://regex101.com/](<https://regex101.com/?flavor=javascript&flags=g®ex=ENV%20YARN_VERSION%3D(%3F%3CcurrentValue%3E.*%3F)%5Cn&testString=FROM%20node%3A12%0AENV%20YARN_VERSION%3D1.19.1%0ARUN%20curl%20-o-%20-L%20https%3A%2F%2Fyarnpkg.com%2Finstall.sh%20%7C%20bash%20-s%20--%20--version%20%24%7BYARN_VERSION%7D>).
Be aware that backslashes (`'\'`) of the resulting regex have to still be escaped e.g. `\n\s` --> `\\n\\s`.
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.
You can use the Code Generator in the sidebar and copy the regex in the generated "Alternative syntax" comment into JSON.
The `regex` manager uses [RE2](https://github.com/google/re2/wiki/WhyRE2) which does not support [backreferences and lookahead assertions](https://github.com/uhop/node-re2#limitations-things-re2-does-not-support).
The `regex` manager uses [RE2](https://github.com/google/re2/wiki/WhyRE2) which **does not support**[backreferences and lookahead assertions](https://github.com/uhop/node-re2#limitations-things-re2-does-not-support).
The `regex` manager matches are done per-file and not per-line, you should be aware when using the `^` and/or `$` regex assertions.
The `regex` manager matches are done per-file and not per-line, you should be aware when using the `^` and/or `$` regex assertions.
### Configuration templates
### Configuration templates
In many cases, named capture groups alone won't be enough and you'll need to configure Renovate with additional information about how to look up a dependency.
In many cases, named capture groups alone aren't enough and you'll need to give Renovate more information so it can look up a dependency.
Continuing the above example with Yarn, here is the full config:
Continuing the above example with Yarn, here is the full Renovate config:
```json
```json
{
{
...
@@ -74,8 +77,9 @@ Continuing the above example with Yarn, here is the full config:
...
@@ -74,8 +77,9 @@ Continuing the above example with Yarn, here is the full config:
### Advanced Capture
### Advanced Capture
Let's say that your `Dockerfile` has many `ENV` variables you want to keep updated and you prefer not to write one `regexManagers` rule per variable.
Say your `Dockerfile` has many `ENV` variables that you want to keep up-to-date.
Instead you could enhance your `Dockerfile` like the following:
But you don't want to write a `regexManagers` rule for _each_ variable.
The above (obviously not a complete `Dockerfile`, but abbreviated for this example), could then be supported accordingly:
This `Dockerfile` is meant as an example, your `Dockerfile` may be a lot bigger.
You could configure Renovate to update the `Dockerfile` like this:
```json
```json
{
{
...
@@ -113,9 +119,14 @@ The above (obviously not a complete `Dockerfile`, but abbreviated for this examp
...
@@ -113,9 +119,14 @@ The above (obviously not a complete `Dockerfile`, but abbreviated for this examp
}
}
```
```
In the above the `versioningTemplate` is not actually necessary because Renovate already defaults to `semver` versioning, but it has been included to help illustrate why we call these fields _templates_.
We could drop the `versioningTemplate` because Renovate defaults to `semver` versioning.
They are named this way because they are compiled using Handlebars and so can be composed from values you collect in named capture groups.
But we included the `versioningTemplate` config option to show you why we call these fields _templates_: because they are compiled using Handlebars and so can be composed from values you collect in named capture groups.
You will usually want to use the triple brace `{{{ }}}` template (e.g. `{{{versioning}}}`) to be safe because Handlebars escapes special characters by default with double braces.
You should use triple brace `{{{ }}}` templates like `{{{versioning}}}` to be safe.
This is because Handlebars escapes special characters with double braces (by default).
By adding `renovate: datasource=` and `depName=` comments to the `Dockerfile` you only need _one_ `regexManager` instead of _four_.
The `Dockerfile` is documented better as well.
By adding the comments to the `Dockerfile`, you can see that instead of four separate `regexManagers` being required, there is now only one - and the `Dockerfile` itself is now somewhat better documented too.
The syntax in the example is arbitrary and you can set your own syntax.
The syntax we used there is completely arbitrary and you may choose your own instead if you prefer - just be sure to update your `matchStrings` regex.
