How to Resolve Salesforce Metadata Conflicts During a Merge

To resolve a Salesforce metadata conflict during a merge, treat the file as XML nodes rather than lines: open the conflicted file, keep both sides' independent changes, drop only the truly clashing edit, then validate the XML and deploy to a scratch org or sandbox before committing. Most Salesforce conflicts are false positives caused by XML ordering, not real disagreements, so the goal is to reconcile, not to pick a winner. Here is how to do it cleanly.

What is a Salesforce metadata merge conflict?

A merge conflict happens when two Git branches change the same file and Git cannot decide which version wins, so it stops and hands the file back to you with conflict markers. On Salesforce that file is almost always declarative metadata stored as XML, a profile, permission set, flow, or layout. Git compares text line by line, and XML does not play nicely with that model.

Why do Salesforce metadata conflicts happen so often?

Three properties of Salesforce metadata make conflicts far more frequent than in ordinary code:

• XML ordering is non-deterministic. The Metadata API can return the same elements in a different order between retrievals, so Git flags a difference where nothing actually changed.
• Big single files. Profiles, permission sets, and layouts pack hundreds of unrelated settings into one file, so two people editing different objects still collide on adjacent lines.
• Git sees lines, not keys. It cannot tell that two edits target different XML nodes; it only sees overlapping text and raises a conflict.

We go deeper on the root causes in why metadata conflicts happen and how to stop them.

How do you resolve a metadata conflict during a merge, step by step?

1. Read the markers. Open the conflicted file and find <<<<<<<, =======, and >>>>>>>. Everything above the divider is your branch; everything below is the incoming branch.
2. Identify the metadata type. For a profile or permission set, work at the XML node level: each <fieldPermissions> or <objectPermissions> block is a unit, not the lines around it.
3. Keep both independent changes. If one side added a field permission and the other changed a different object, keep both nodes. Whoever merged first should not silently "win" the line, that is how real edits get lost.
4. Drop only the genuine clash. When both sides edited the exact same node differently, that is the one human decision the tool cannot make. Choose the correct value deliberately.
5. Validate the XML. Confirm the file is well-formed and that node keys are not duplicated, then remove every conflict marker.
6. Deploy and test before committing. Push the resolved metadata to a scratch org or sandbox, run your tests, and only then commit and complete the merge.

For the discipline of never losing a teammate's change, see how to resolve conflicts without losing anyone's work.

How do you stop resolving the same conflicts by hand?

Manual line-by-line merges do not scale. The durable fix is a metadata-aware merge that understands XML structure. A Salesforce-aware Git merge driver compares files node by node, auto-merging anything that changed on only one side and flagging only the genuine clashes; we walk through the setup in how to set up a Salesforce-aware Git merge driver. DevOps platforms take the same idea further: Gearset, Copado, Flosum, and Blue Canvas all ship semantic or smart-merge features that ignore non-functional XML ordering and surface only real conflicts. Serpent applies the same principle inside GitHub-native pipelines, so your team reviews decisions, not noise. Good source hygiene helps too, and managing Salesforce metadata covers the habits that prevent conflicts in the first place: short-lived branches, frequent merges, keeping environments in sync, and giving shared components like profiles a single owner. Browse the full SF Guides library for more, and compare tooling options on our pricing page.

FAQ

Why does Git flag conflicts when nothing really changed?

Because the Metadata API returns XML elements in non-deterministic order, so Git sees reordered lines as differences even when the actual settings are identical.

Can I just pick one side of the conflict?

Only when both sides edited the exact same node. If the changes touch different nodes, picking one side silently deletes a teammate's real work.

Should I resolve profile conflicts in the profile file?

Where possible, move object and field permissions into permission sets instead of profiles. Smaller, focused files collide far less often.

Do I need a special tool, or is plain Git enough?

Plain Git works for small teams, but a metadata-aware merge driver or a DevOps platform with semantic merge removes most manual work once more than a couple of developers share metadata.