Do you sometimes feel that Gearset is not following the definition in your package.xml?

Is the package.xml below not returning the comparison results you expect?

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>Account.Phone</members>
    <name>CustomField</name>
  </types>
  <version>56.0</version>
</Package>

This article explains how Gearset reads your package.xml for comparisons and CI jobs.

How does Gearset read the package.xml?

Gearset will only read and understand the top-level metadata types referenced in the package.xml. These are the objects specified by the Salesforce Metadata API, and in general, are the metadata types you can select in Gearset's custom metadata filter.

(Gearset has now made it possible for you to select individual subcomponents from Custom Object, such as Custom Fields, in your metadata filter for retrieval. However, these are still not top-level items as defined by Salesforce).

Gearset will recognize the Custom object metadata type and its named members, but will not recognize subcomponents like Custom field, Record type or List view in your package.xml. This can be the reason that even though you have a metadata type (e.g. Custom field) specified in your package.xml, you aren't seeing it in the Gearset comparison result. The solution is to specify the top-level metadata type instead (e.g. Custom object).

Note for SFDX format Git repositories

If the repository is in SDFX format, Gearset does not use the package.xml file to filter the comparison results.

Metadata filter and package.xml

The metadata filter determines what is requested and downloaded from your org to present in the comparison results. The package.xml filter takes the metadata info returned from the org and further filters the rows, to only show you the items (and associated subcomponents) specified in your package.xml.

Therefore, if the Filter comparison by package.xml is ticked, the Gearset comparison results will only show items:

included in your metadata filter, and
that have the top-level metadata type referenced in the package.xml.

If the Filter comparison by package.xml is unticked, or if the package.xml does not exist in your repo, the Gearset comparison results will show all items included in your metadata filter.

If there are further questions about this topic not covered by this article, please don't hesitate to ask us in the in-app chat!