Tips for comparing metadata in source control repositories

4 tips on working with source controlled metadata, structuring your repository, and working with package.xml files

Valerio Chang avatar
Written by Valerio Chang
Updated over a week ago

With Gearset, you can compare and deploy metadata contained in source control repositories with your Salesforce orgs. To make this process as smooth as possible, there are a few general best practices to follow.  

Please note, this article is based on the original Metadata API format. Repositories in the DX format have a different structure. (For more information on this, see our article on structuring your source control repository.)

Want to know how to run a comparison to or from source control in Gearset? Read our feature guide for more information.

Initialize your repository first

Gearset can't deploy your metadata to a totally blank repository - you'll need to initialize your repository first (with a README).

Structure of the metadata in your repository

Metadata in source control should be in the same format as you use for Ant or Eclipse deployments. Within a branch, each metadata type should sit within its own folder. You can place all of these folders within a single unpackaged folder if you wish, but you should not create a nested folder structure. 

For more information on structuring your metadata, see this further explanation or the Salesforce documentation on package creation.

Working with package.xml files

If Gearset detects a valid package.xml file in your source control repository, by default we will use that to filter your comparison results (with Filter comparison by package.xml ticked). This will build on top of the comparison filter you have selected in the app. This can be a great way to reduce noise when comparing orgs and source control, but it can sometimes mean that you may not see all the metadata you expect when running a comparison.

You can turn off filtering by package.xml file as part of your comparison configuration by unchecking the box underneath the branch (see more in this article).

If you've run a comparison, and you're not seeing metadata you would expect in the results, check if a package.xml file exists in your branch. If it does, confirm that it is listing all the metadata types you wish to see, or disable the package filtering option. For further information, see our support doc.

Commit messages when deploying to source control

When running a deployment into your repository, Gearset can enter a commit message for you. Any text you enter into the deployment notes section in the pre-deployment summary will be included as your commit message. Your team owner can also make deployment notes compulsory in the deployment settings, helping to make sure your team maintains a clear record of every deployment.

Did this answer your question?