The short version
Semantic merge is how Gearset combines your team’s Salesforce changes in your version control system (VCS).
Instead of comparing files line by line the way Git does, it understands what the changes actually mean in Salesforce terms, so two people can safely work on the same metadata item without overwriting each other’s work or breaking a deployment.
You don’t need to switch semantic merge on or configure anything. It runs automatically whenever Gearset merges changes in your Pipeline.
What is a semantic merge?
A semantic merge happens in Gearset when a change is technically a merge conflict, but Gearset is able to resolve it while keeping both changes.
When the changes in your pull request clash with what’s already in the target environment branch, Git would normally stop and report a conflict for you to resolve manually.
Instead, Gearset looks at the conflict and resolves it so that both changes are kept. If your two changes still can’t coexist, Gearset triggers a merge conflict that you’ll see in the Pipeline UI.
For the technical details of how semantic merge is handled, see What is Semantic Merge?
What is a reverse semantic merge?
A reverse semantic merge is Gearset taking the commits from previous pull requests, or changes that have been made directly to this branch, and merging them into your pull request.
This means:
Gearset can validate your PR alongside any other required commits from PRs that have already been merged into the target environment.
You don’t overwrite, or hit a merge conflict with work that is already in progress in the Pipeline.
Changes shown in a reverse semantic merge always come from the target environment branch. Gearset isn’t creating these changes.
For the technical details of how reverse semantic merge is handled, see Why do Gearset’s reverse merge commits contain lots of unrelated changes?
A reverse semantic merge is including changes in my validation and causing validation errors
To work out why a reverse semantic merge is including unexpected changes, start by finding where those changes came from:
Ask your team whether anyone else made these changes. This is often the simplest way to find the answer.
If you can’t find where the changes came from, open your PR’s branch directly from your repo and check the Git blame for the unexpected changes. How you do this varies between version control systems. Here is GitHub’s documentation on viewing Git blame. Instructions for other VCS providers, such as Azure DevOps and Bitbucket, can be found with a quick web search.
Confirm whether the change is active work in progress that’s needed, or an unexpected change from an old commit that’s no longer needed.
This change is part of another user story and must be kept
If the change is part of another user story, your change and your teammate’s change are incompatible, and one of you will need to make a new change so that the two PRs work together.
For example, you may be deleting a field that your teammate’s change requires.
In this case, work with your teammate to confirm the best way to resolve the error.
This change is unexpected and not needed
This issue occurs because there is an unexpected change in the target environment branch that doesn’t exist in your Main/Master branch and doesn’t belong to any of your other work in progress.
In this case we want to remove the commit from the target branch.
There are two ways to remove this commit. Which one you use depends on how often you see reverse semantic merges with unexpected changes, and how many changes are showing.
I rarely see these unexpected changes, and there are only a few
I rarely see these unexpected changes, and there are only a few
If this is the first time you’ve seen a reverse semantic merge with an unexpected change, it may be related to a small sync issue. In this case, you can manually overwrite the commit to remove it from the target branch, bringing the branch back in sync.
To do this, run a manual comparison with the following settings:
Source: The source feature branch, for exampleStory-12-New_FieldTarget: The promotion branch for this PR, for exampleStory-12-New_Field_-_INTMetadata filter: The Pipeline metadata filter
In this comparison, select only the changes that are unexpected and causing issues.
Important: if you select real changes from other PRs in your Pipeline, you’ll cause more unexpected reverse semantic merges in the future.
I often get reverse semantic merges with unexpected changes, or there are a large number of changes
I often get reverse semantic merges with unexpected changes, or there are a large number of changes
If you hit this issue regularly, it’s likely there are a large number of out-of-sync issues in this environment.
In this case, the best solution is to recreate the environment branch and CI job used for this environment.
This brings the environment back in sync with Main/Master, removing all commit drift issues.
To do this, follow scenario 2 in How to realign/fix an out of sync Pipeline.
How do I avoid reverse semantic merges with unexpected changes in the future?
Abandoned commits
The main reason unexpected commits get added to your environments when you close PRs in your Pipeline without rolling the changes back out of source control.
Those changes stay in that specific environment and never reach production, and continue to be brought into any future PRs opened against that environment.
To avoid this, rather than deleting the PR from your Pipeline, do one of the following:
Fix the existing PR rather than deleting it. See Edit or fix a user story in progress in pipelines.
Roll the change back out of your repo. See Rollback with Gearset Pipelines.
Changes made to promotion branches
Another common reason unexpected commits get added to your environments is when you make changes to a PR's promotion branch.
Any change made directly to a promotion branch will be merged into the target environment without passing it onto the next environment in the pipeline.
For this reason we do not recommend making changers directly to environment branches unless it's to remove an unexpected commit with this process.
FAQs
Why can’t Git do this on its own?
Semantic merges
Git is excellent at merging code, but it only sees text. Git has no idea that a file describes a Salesforce field, a Layout, or a Flow. It just compares lines of code.
Salesforce metadata files are structured XML, where a single component, such as a custom field, is described by a block of related lines. When two people change the same component, a line-by-line merge can easily produce a result that’s wrong in one of two ways:
Git sees a merge conflict when the two changes could happily live side by side.
Git merges the files without complaint, but the result isn’t valid Salesforce metadata and your deployment fails.
Semantic merges step in here to make sure these merges are Salesforce-aware.
Reverse semantic merges
When you run a validation from a PR’s promotion branch to your target org, that branch hasn’t been merged into the environment branch yet. With Git’s standard behavior, Gearset wouldn’t be able to test your change alongside the other PRs that have merged into the environment, so a PR could pass validation and then fail validation after it merges into the environment branch.
Reverse semantic merge solves this by bringing the relevant commits that have already been merged into the target environment branch into your PR for the validation.
Can I turn semantic merge off?
No, and you really wouldn’t want to.
Without semantic merge, changes your teammates have already promoted could be silently overwritten, and merges that look fine to Git could produce metadata that Salesforce won’t accept.
Semantic merge is what keeps your branches, environments, and team in sync.
If semantic merges seem to be pulling in changes you don’t expect, that’s almost always a sign of something else in the Pipeline, most commonly abandoned pull requests, or branches created from somewhere other than the Main/Master branch.
Any questions?
If you have any questions about the behavior mentioned in this article, feel free to reach out in our in-app chat and we can clarify anything you need help with.