SF Org Compare

Prepare, back up and verify a Salesforce deployment from VS Code.

Compare two orgs on a scope you choose, decide what to deploy, what to do by hand and what to leave out, then get the package.xml, the manual steps and a change set checklist. Back up the target before deploying and check the org afterwards. Every step is recorded in your workspace.

Available in English and French: the extension follows the VS Code display language. Screenshots use demo data.

Why

Before a release you need to know what differs between the reference org (UAT, staging) and the org to update (production), then turn those differences into a change set, a list of manual steps and a tracking sheet. Doing it by hand is slow and things get missed. SF Org Compare does the mechanical part and keeps a trace of every decision.

It never deploys anything: it only reads your orgs (list metadata, retrieve). You stay in control of the deployment, by change set or otherwise.

Features

One project per release

Each release is a project with its own tab: overview, scope, comparison, verification. The overview shows the 8 steps, what is done, what must be redone, and the history.

Pick the scope from the org

List the components of both orgs and filter by state in the target (missing, newer in source…), modification date, author and type. Or import an existing package.xml. Every saved scope is a new version you can start from later.

Compare, element by element

Each component is Different, New, Only in target or Identical. Layouts, Lightning pages, permission sets and profiles are compared element by element: fields, sections, related lists, actions, field and object permissions… Code is shown side by side, with a button to open the native VS Code diff.

Flows, step by step

Flow differences read like Flow Builder, not like XML: trigger, decisions and their rules, paths between steps, steps added or removed, resources. Canvas positions and display-only properties are ignored.

Open the flow diagram from the comparison: the flow is drawn top to bottom, with what was added, changed or removed in color. Drag to move, wheel to zoom, a mini-map for long flows, unchanged steps collapsed, and N/P to jump from one difference to the next. Click a step to see what changed.

Right-click a .flow-meta.xml file and choose Preview Flow to draw any local flow, then Compare with an org… to color what differs.

Refresh a component from the orgs

Someone fixed the layout in UAT while you were reviewing? Refresh from the orgs in the detail panel (or on the flow diagram) retrieves just that component from both orgs and updates its line in seconds, without running the whole comparison again. The refresh is recorded in the project history, and validated decisions on that comparison are flagged for review.

Compare a file or folder with an org

Right-click a file or folder of your Salesforce project (or use the editor menu) and choose Compare with Org…. The org version is retrieved in the background and compared file by file: a single file opens straight in the VS Code diff (org on the left, your editable file on the right); a folder lists the files that differ, exist only locally or only in the org. Nothing is written to your project.

Compare your local project with an org

The source can also be a local Salesforce project (a folder with sfdx-project.json), for example to check what is in your Git branch against UAT, or to find changes made directly in production. The project is converted with sf project convert source and compared like an org. Scope: the whole local project or a package.xml. Components listed in the scope but missing locally are reported.

Decide: deploy, manual or exclude

A default is proposed for each component:

For manual items, tick the differences to apply by hand; they become your manual steps. Validate the decisions to freeze a numbered version.

Deliverables

• package.xml of the components to deploy
• Manual steps in Markdown, ready for your release document
• Tab-separated lines to paste into a tracking spreadsheet
• Decisions as JSON, to share or reload

Change set checklist

Components to deploy grouped in three batches (data model, code, UI and access) with the exact Setup labels. Tick each one as you add it, and copy the list of test classes for "Run specified tests".

Back up the target

Before deploying, retrieve the current version of everything the release will change, plus a destructiveChanges.xml for everything it will create. A README gives the two rollback commands.

Verify after deployment

Run the comparison again: every deployed component must now be identical, and every ticked manual step must be gone. Anything missing is listed.

Getting started

1. Install the Salesforce CLI.
2. Log in to both orgs with an alias:

   sf org login web --alias MY_UAT
   sf org login web --alias MY_PROD
   

3. Open a folder in VS Code, click the Releases icon in the activity bar, then New release project.

The guided tour opens with the command SF Org Compare: Get started with SF Org Compare.

Requirements

• VS Code 1.85 or later
• Salesforce CLI (sf), with the orgs already authenticated

Reliability

• Nothing silent. Failed listings are retried once, then reported. Components missing from the source or unreadable are listed as warnings.
• Org checks. The connection is checked before each long operation, with clear messages (expired session, unknown alias).
• Safe files. Atomic writes with a backup copy; a corrupted file is kept aside, never reset.
• Consistency alerts. Scope changed since the comparison, decisions changed since validation, comparison older than 7 days. Backup and verification are blocked until decisions are validated and up to date.
• Cancellable. Inventory, comparison, backup and verification can be cancelled; partial folders are removed.

What is stored

Everything lives in your workspace, under mep/<date>-<name>/, as plain files you can commit:

Command line

npm install
node bin/compare.js --source MY_UAT --target MY_PROD --manifest manifest/package.xml --name "Sprint 12"

# local project against an org
node bin/compare.js --source-dir ./my-sfdx-project --target MY_UAT --manifest manifest/package.xml

The report opens in your browser.

Limitations

• No author or date for object sub-components (fields, record types, buttons…): the Metadata API does not return them.
• Flow diagram layout is computed automatically: very large flows stay readable with the mini-map and collapsing, but do not look exactly like Flow Builder.
• The scope picker states are based on modification dates, not content.
• Local source: no author or date per component, and the scope picker works only with an org (use the whole project or a package.xml).
• No deployment, by design.

Development

npm install
npm test          # unit tests, no org needed
npm run demo      # builds a demo project with fictitious data (add "-- demo-workspace fr" for French)
npm run package   # builds the .vsix (images point to GitHub)