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.
