Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Salesforce CLI Configuration and Tips
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Authorize in to Your Production Org
Create a Sandbox Definition File
Create, Clone, or Delete a Sandbox
Track Changes Between the Project and the Sandbox (Beta)
Query the SourceMember Object to Get Change Information
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Track Changes Between the Project and the Sandbox (Beta)

When source tracking is enabled in a Developer or Developer Pro sandbox, the sandbox automatically tracks changes between the sandbox and the local workspace. When you pull sandbox changes into your project or push project changes to the sandbox, only the changed source is synched back. Sandboxes that exist at the time the feature is enabled in the production org won't have source tracking enabled until they're refreshed.

As a beta feature, Source Tracking in Sandboxes is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for the Source Tracking in Sandboxes feature by posting in Collaboration or Ideas in the Trailblazer Community.

This feature is available in Developer and Developer Pro Sandboxes only.

For setup instructions, see the Salesforce DX Setup Guide.

If you're working in a scratch org instead of a sandbox, see Track Changes Between the Project and Scratch Org.

Set the Environment Variable for Tracking Changes by Multiple Users

These instructions set up source tracking for Developer and Developer Pro sandboxes where multiple users are making changes. We recommend a development model where each user makes changes in their own development sandbox, but we understand that sometimes multiple users share a development sandbox.

To configure source tracking in sandboxes, set the environment variable SFDX_ENABLE_MULTIUDX to true.

If you're also working with a scratch org and you set the SFDX_ENABLE_MULTIUDX environment variable, the source tracking in that scratch org goes out of sync. To resync, push then pull the source files again. Alternatively, you can set SFDX_ENABLE_MULTIUDX to false temporarily to get the source back to a synched state. This behavior won't be an issue for scratch orgs that are created after the environment variable is set to true.

Note

Authenticate Your Sandbox in Salesforce CLI

Authenticating your Developer or Developer Pro sandbox in the local Salesforce CLI lets them communicate through CLI commands without requiring additional credentials.

If you haven't yet set an alias for your sandbox, now would be a good time to create one. Using aliases makes it simpler to issue commands. That's why it's a best practice to use sandbox aliases, especially if you're managing several sandboxes. For details, see Create, Clone, or Delete a Sandbox.

Note

We've given the sandbox in this example the alias MyDevSandbox. To authenticate your sandbox in the CLI, run the following command.

You use the -r flag to override the default login URL (which is the URL for the production org) with the login URL for the sandbox. The sandbox in the example uses the alias MyDevSandbox.

The sandbox login page opens in a web browser. Log into the sandbox using your normal sandbox credentials, accept the authentication request, then close the browser.

Create a New Salesforce DX Project

Sandbox source tracking syncs against a local workspace to identify what's been changed in the sandbox. From a working directory, create a new Salesforce DX project that can serve as the standard of comparison. Let's call our new project MyControlProject.

You're now set up to have the sandbox org track changes you make there.

Source Tracking in Sandboxes is fully reset when a sandbox is refreshed.

Note

Display Sandbox Changes Identified by Source Tracking

Make a few configuration changes in the sandbox org, then go to the project directory (MyControlProject in the previous section) and display a list of the changes you just made. Remember, MyDevSandbox was the alias assigned to the sandbox that was authenticated in Salesforce CLI.

You see that a list of changes posted to output:

Pull Changed Source from the Sandbox to Your Project

When source tracking is enabled in a sandbox, pulling source from the sandbox to your local source directory moves only the files that changed:

The format of source files pulled from a sandbox is a little different than you might be used to when retrieving metadata with Metadata API. To learn more, see Salesforce DX Project Structure and Source Format.

Note

Push Changed Source from Your Project to the Sandbox

If you make changes in a local environment or IDE and your sandbox is set up for source tracking, it's easy to synchronize the sandbox with the local environment. Push the local changes to the sandbox, and source tracking identifies which files have changes and automatically pushes only those files.

You can push local changes to a sandbox with source tracking enabled even if the changes are in a metadata source file that you retrieved to the local workspace. For example, let's say that you wanted to retrieve an ApexClass called MyApexClass to make some updates.

When you're ready to sync your local changes with the sandbox, you could use the force:source:deploy command, but you'd have the extra bother of explicitly specifying the files to deploy.

Instead, because your sandbox is set up for source tracking, a simple force:source:pushcommand automatically pushes only the changed files to the sandbox.

Tip: Let Source Tracking Help You Identify Change Set Components

If you're using change sets to migrate customizations, you can use the sfdx force:source:status command to help you identify which components need to be added to the change set. That way, when you're ready to build an outbound change set, you can use the sfdx force:source:status -u MyDevSandbox command to display a list of changed components.