When you run a comparison, Gearset will show you the metadata differences between your source and target. See what changes have been made, when and by whom at a glance, without the need for manual XML diff or change tracking documents.
Comparison results table
A typical comparison will look similar to the screenshot below. Individual metadata items are shown in the table with the following columns:
Name: the name of the metadata item
Metadata type: the type of metadata item (e.g.
ProfileorApex class)Changed on: the last modified date for the item*, the most recent date out of the source or target org
Changed by: Salesforce user who made the last change to the item*Difference type: whether the item is
New,Different,Deleted, orNo difference
* For details on why this tab may show as blank or display "Unknown", check:
Why 'Unknown' is sometimes displayed as the 'Changed by' value in the results table
And for why the information may occasionally be incorrect, check:
Why is the 'Changed on' or 'Changed by' sometimes incorrect?
In all cases, Gearset displays the information returned to our app by the Salesforce metadata API.
Results table - tabs
Items are grouped by their change type via the tabs in the results table. These tabs line up with the metadata change type listed in the section above.
On below screenshot, we're previewing All items tab (that's why it's highlighted in blue).
Usually, when looking at your comparison results if you want to narrow down the search to either New or Changed or Deleted items - you'd want to select one of the tabs below.
"All items" - By default, when you first run a comparison, you'll be taken to this tab, which is designed to show all the retrieved metadata types.
Remember, the metadata types that are retrieved in the comparison are based on your metadata filter configuration.
The diff viewer
Clicking on any metadata item will select it and show you the line-by-line comparison between your source and target in the XML diff viewer in the bottom half of the screen.
Depending on the metadata type, there may be alternative, simplified views for you to choose from. For example, you can select a Layout view if the selected metadata item is a picklist:
If there are multiple changes, you can quickly move between them using these buttons in the top right hand side of the diff viewer: 
Below image shows where to locate the buttons. It also points to the picklist values you'd be able to navigate between when clicking on the buttons.
Metadata change types: Different, New, Deleted, No difference.
Gearset groups changes to your metadata by their type:
New - the item only exists in your source; deploying it will add this item to your target
Different (under "Changed items" tab) - the item exists in both source and target, but there are differences between your source and target. Deploying it will update the target with the version from the source.
Deleted - the item only exists in your target. Deploying it will remove (delete) this item from your target.
No difference - the item exists in both source and target and is identical; you can't select it as there would be no changes to deploy
Examples of "New", "Changed", "Deleted" and "No difference" items in comparison results
In this section you'll find practical and visual examples (supported with screenshots) of what it means to preview either New, Changed or Deleted items in your comparison results. And how a deployment of these type of items would affect your target environment.
Click on the black arrow on your left to preview the examples.
Click on the black arrow on your left to preview the examples.
"New" - This tab will show all the metadata items that are new in the source environment, and don't exist in the target environment of your comparison.
For example, below image shows a new Custom object named VideoCall - this object was created in the source org. If selected for deployment, it will be created in the target org:
"Changed" - This tab will show all the metadata items that exist both in the source and target environments of your comparison. But we've detected differences between compared items.
For example, on below image we're seeing that "Case" Custom object exists in both source and target org. But one of the differences shows is that "Case" object has a different primary Compact Layout assigned in the source org (Test_Layout_Assingment used in the source instead of system default SYSTEM layout).
And a preview from the source org:
"Deleted" - this tab shows you all the metadata types that exist only in the target environment. That's why the XML preview of a metadata item you click on is blank (as on image below).
This example shows Dashboard_Pal installed package. This package exists only in the target org, so if we select it for the deployment - Gearset will delete the installed package from the target org.
The package will remain unchanged in the source org. It's because a deployment of deleted items doesn't affect the state of these items in the source environment.
"No difference" - indicates items that are the same in the source and target.
It's important to know that Gearset app doesn't prioritise the display of any metadata items/components that are identical in both source and target environments that you're comparing.
Therefore, these items may will show in your results as top-level components unless you configure your comparison's filters to display such items.
For example, below we're seeing a "Property" Custom object that is identical in both source and target environments. Therefore, it shows as No difference.
One way to quickly identify your identical items is to narrow down the Difference type filter to only these components that show No difference in the results:
In addition to that, you can also narrow down further by selecting the same filter on the Metadata type tab, then untick all the retrieved metadata types, and leave only Custom object selected.
And once you have these two filters configured, you can opt to look for your component by selecting the filter option on Changed on or Changed by tabs - if you know when or by whom (which Salesforce user) the changed was made.
But often a much simpler way of narrowing down is simply by combining Difference type + Metadata type + Name filters. Because the Name filter can be configured to look up only the components named 'Property' - and this is how the result shown in above screenshot was achieved.
Sorting comparison results
If you click on Metadata type tab - you'll notice that by default, the metadata items are sorted alphabetically by metadata type.
By clicking on this tab, you control whether you want the metadata types retrieved to be sorted in an ascending or descending alphabetical order.
- arrow facing upwards means that Metadata type column sorts all the metadata items in an ascending alphabetical order (from A-Z).
- arrow facing downwards means that Metadata type column sorts all metadata items in a descending alphabetical order (from Z-A)
Note: The arrows on Metadata type tab indicate you're sorting only Metadata type column items by the name (ascending or descending).
This option doesn't automatically sort the Name column items in an alphabetical order, so that both Metadata type and Name columns could be sorted alphabetically at the same time.
It's because Gearset doesn't support multi-column filtering in the comparison results.
How to apply multi-column filtering
In a note above we've explained how multi-column filtering cannot be configured in our app.
Now we're going to explain a workaround you can apply to customize our filters to sort in an alphabetical order Name components that belong to a specific Metadata type.
On below example, we've narrowed down Metadata type specifically to Custom object - at that stage the Name column is not yet sorted alphabetically.
Next step: We then click on Name tab to sort the Name column items in an alphabetical order (whether ascending or descending).
Currently, without a more advanced multi-column filtering option in our app this is the only way you can achieve it.
Searching and filtering comparison results
If you have a large number of differences, you may wish to filter the comparison results to make it easier to find the changes you're interested in.
There are three main ways to search or filter the comparison results:
- Using the global search filter in the top right corner
- Viewing results by compared metadata type
- Using the filtering available on each of these columns: Name, Metadata type, Changed on, Changed by, and Difference type.
Global Search Filter
This is the main filter available in the top right corner of your comparison results page.
Example
On below image we're using the filter on the top right to specifically search for all components with "Account" in their name.
And because we've selected to preview all the Compared types of metadata (as highlighted in red; menu on the left hand side), Gearset will display all the relevant components with "Account" in their name across all 207 retrieved metadata types.
Note: When you start typing in the global filter on the top right corner, you'll notice that Gearset will begin adjusting your comparison results in real time by moving relevant components to the top of the screen.
The keyword you type in the global filter applies to all columns. So when you type in "Account" - Gearset will look for relevant Name or Metadata type.
And depending on which tab you're currently viewing (All items, New, Changed or Deleted), you'll see results adjusted to the tab you're currently on.
If you're not sure how to locate the change you're looking for, we recommend to always start with All items tab. For example, in scenarios when you don't know if it's a new or changed component in your source environment.
Viewing results by compared metadata type
Following up from the example above, you can also switch from Compared types tab to Custom object metadata (or any other metadata type) while keeping everything else as it is.
This way we're still searching by component name "Account", but only across all the Custom object metadata type.
This includes all the Custom object's sub-components like Business process, Compact Layout, Custom field, Field Set, Index, List view, Record type, Sharing reason, Validation rule and WebLink.
Custom object is the only metadata type in our filter that has as many as 10 sub-components. Most of other metadata types don't usually have any sub-components.
Selecting a metadata type in the left hand window will show only that metadata type in the comparison grid.
Note: Selecting a specific metadata type on the menu (left hand side) will show only that metadata type in the comparison grid. For example, on above image we're showing only Custom object metadata components.
If you want to switch back to previewing all retrieved metadata types - simply click on Compared types.
Column filtering
Comparison results can also be filtered on a per-column level. Select the menu icon on any column to specify which items you'd like to be displayed in the results.
'Name' column - allows you to filter results by text.
For example, if we want to find all components that contain the word "Type", we'd configure the filter accordingly:
Using regex (regular expression) filtering in 'Name' column
You can also use a regular expression in the filter. More information on this feature in our documentation: Using regex to filter comparison results.
"Metadata type", "Changed on", "Changed by" and "Difference type" column filtering
Metadata type column - allows you to filter results by metadata types retrieved in your comparison results. You can look up specific metadata types by text, or by ticking their names in checkboxes.
Example below where we've selected to filter only by Custom object, Custom object permission and Custom object translation types.
All the other metadata types retrieved in the comparison will not be considered and won't be shown in the comparison results.
Changed on column - allows you to filter by items changed either Today, in the Last 7 days, Last 14 days, Last 30 days, or All time ('All time' refers to items that were amended at any point in time).
On below example we're filtering items Changed on in the Last 30 days. Notice that the option selected Last 30 days is highlighted in bold.
Changed by column - allows you to filter metadata components by the Salesforce user who made a change.
Normally, you'd be able to select a specific user from the menu and make it with a tick. But in case there are multiple users on the list, you can use the filter to type user's name to narrow down the search.
It is expected that Gearset may not have information about all the metadata types that were amended by specific users.
Difference type column - allows you to filter by items that are New in the source environment, items that are Different in both environments, items that are Deleted (meaning they exist only in the source environment), and items that are identical in both environment, that's why they're retrieved as No difference in Gearset.
Note: If you want to preview both New and Changed items at the same time, make sure you're viewing them in the All items tab.
This is because tab New is exclusively for items that are new in the source environment. While tab Changed is exclusively for items that exist in both environments but show some differences.
Feedback
If you have any questions related to your comparison results and available filtering options, you're welcome to reach out to our support in the in-app chat.
Especially, if there is something you'd like to know that we didn't cover as part of this article.
Customer feedback and suggestions help us improve the documentation we create to help Gearset users get as familiar with our tool as possible.