When comparing from a source control system, you have the option of filtering comparison results based on a package.xml file in your source branch. This article explains how to manage this setting and how Gearset applies the filtering to your results.
When you can apply filtering by package file
You can use a package file to filter your comparison results when:
You're running a comparison from a source control system; or
You're setting up a CI job from a source control system
Running a comparison from source control
When running a comparison, there is a checkbox below the branch selector with the option of filtering by package file. This is checked by default.
Setting up a CI job
When setting up a CI job, there is a checkbox below the branch selector. This is checked by default.
Location of your package file
The package file must be in the top level of your branch for Gearset to detect it.
Gearset does not support a branch with multiple package.xml files. Gearset may have problems parsing your branch if multiple package.xml files are present. For more details, please see this article.
How Gearset applies filtering
Filtering from a package file will be applied after the settings in your metadata filter in Gearset:
The metadata filter controls what gets downloaded from your repo/org
The package file is then applied to the downloaded results and affects what gets displayed - items not specified in your manifest will be hidden from the comparison results
Gearset uses your package file to filter by top level items. If you want subcomponents of a metadata type to appear in the results, all you need to include in your package file is the parent item.
It is not possible to filter subcomponents from a package file. For example, including a custom object will also include all its fields, even if only a few of those fields are explicitly listed in the package file.
To demonstrate, the two package files below will display both the Case object and all of its fields, even though the first package only lists the ExampleField on the Case object.
Whereas this package file will not show anything, as the parent Case object has not been included.
If you don't see items you are expecting in your comparison results when filtering using a package file, it's worth checking your package file to confirm that the parent item has also been included.
Troubleshooting errors
A common issue for package files is they may be incomplete or incorrectly formatted. If you experience errors when running comparisons using a package file, it's worth checking that your package file is correctly formatted (see Salesforce's documentation).
For example, the package file below contains two <name> fields for CustomFields.
The result in Gearset is a package parsing error.
Note for SFDX format repositories
If the repository is in SDFX format, Gearset does not use the package.xml file to filter the comparison results. The option will not be available.
If you get stuck, you can always contact us for help.