Gearset's customizable filters let you control the types of metadata that are displayed in your comparison results. To add another layer of granularity, you can use regex filtering to include or exclude specific named items. For more information on how to create or edit a custom metadata filter, see this article.
You can use regex filtering to either include or exclude items from your comparison results. In this article we'll demonstrate how to use this powerful feature to fine-tune your custom filters.
Switching to named items
First, find the metadata type you're after from the left-hand list, and switch the toggle to Named items.
You should note that when you switch to Named items, no items are included by default. You can select specific items to include in your filter and subsequent comparison either by using the checkboxes or by adding regex.
Including items based on regex
Imagine you want to include all items that begin with Metadata. Rather than selecting every item manually, you can add a regex rule to include all matching items. Select Regular expression from the left-hand dropdown and type the regex pattern ^Metadata.* into the text field. Click Add to save the rule.
Excluding items based on regex
Sets of items can be excluded by a regex pattern in much the same way as they are included above, by selecting the Exclude option on the right-hand dropdown when Regular expression is selected on the left.
Note: When using Exclude regex the items that match the pattern are excluded no matter what, regardless of whether they were included individually or via regex pattern. Exclude regex takes priority over any other filters.
Consider the below example:
The include regex will find Refund, RefundLinePayment and ReturnOrder, in addition to to the explicitly included ProductCategory and Seller. However, the exclude regex will match Refund, RefundLinePayment and Seller.
As a result, the final set of objects to be included in the comparison will be ProductCategory and ReturnOrder.
Building a complex filter with includes and excludes
Include and exclude filters can be layered to create complex metadata filters.
Take the first example in this doc, including Metadata items. Imagine you want to exclude MetadataChurner from the comparison, but include all other Apex classes.
Select Object name from the left dropdown, type the name of the item you want to exclude, and switch the right dropdown to Exclude. Hit Add to save the rule.
If you left things there, MetadataChurner would be excluded, but so would every other Apex class! Now you would need to add the regex term .* which includes all other items of this metadata type.
In this way, you can build up complex metadata filters to fine-tune your comparisons and control exactly which items you want to compare and deploy.
Complex filter - Managed Package example
One common use case for combining both Include and Exclude filters to make up a complex filter is interactions with Managed Packages.
There are certain modifications you can make to Managed Packages (for example: List Views, Reports, some Custom Field elements, etc.), and other modifications that aren't allowed (for example: Apex Classes, Apex Triggers, Lightning Web Components, etc.). If you include Managed Packages in your metadata filter, these items will still come through and be shown in the relevant Metadata areas, even though you can't/may not want to modify them. Using a combination of Include/Exclude filters can help combat this 'noise' in your Comparisons, as shown below:
By combing the Include filter as above, we can keep the Metadata Type 'Apex class' dynamic and ensure any new items we add are included in future comparisons without having to come back and edit the filter, but since we can't modify the Apex Classes present within the 'trailheadapp' Managed Package, the Exclude Filter ensures none of those are actually included, and the Comparison results are kept small.
Notes of caution
Please ensure you select
Regular expressionfrom the dropdown when you use regex, rather than leaving it on the defaultObject name. For example, if you want to add an include regex rule of.*, if this was set up as anInclude itemrule (from havingObject namein the dropdown) rather thanInclude regex, Gearset would look for an item called.*, and the regex rule wouldn't work.You can only use the
Named itemsand regex rules to specify top-level items, not subcomponents. For instance, you can set regex to exclude a specificCustom object, but not to exclude a specificList vieworCustom field.When comparing only Salesforce orgs, any components which are in nested subfolders (and therefore have more than one slash in their names) will appear in the autopopulated
Include itemlist with only the one parent folder in the name.For example a component whose full name is
FolderA/FolderB/ComponentAwill appear in the metadata named item list asFolderB/ComponentA; but appear in the comparison results asFolderA/FolderB/ComponentA.Attempting to include this component using the regex pattern
^FolderA.*will not work, but^FolderB.*will. This is due to the responses we get from the Salesforce Metadata API. However, this does not apply to Git-based repositories. If your comparison is between a Git repository and a Salesforce org, any regex pattern used should take into account both full and abbreviated component names.
Want to know more about regex?
The Mozilla developer site has a great introduction to regex rules to get you started. Find out more on it here.