Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
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 your local workspace. When you pull sandbox changes into your project or push project changes to the sandbox, only the changed source is synched. Sandboxes that exist when the feature is enabled in the production org don't have source tracking enabled until they're refreshed.

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

For setup instructions, see the Salesforce CLI Setup Guide.

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

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.

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. 

1sfdx auth:web:login -r https://test.salesforce.com -a MyDevSandbox

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.

1sfdx force:project:create -n 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.

1cd MyControlProject
2sfdx force:source:status -u MyDevSandbox

You see that a list of changes posted to output:

1STATE                     FULL NAME      TYPE         PROJECT PATH
2─────────────             ─────────      ─────────     ───────────────────────────────────────────────────
3Local  Deleted            MyClass .      ApexClass    /MyClass.cls-meta.xml
4Local  Deleted            MyClass .      ApexClass    /MyClass.cls
5Local  Add                OtherClass     ApexClass    /OtherClass.cls-meta.xml
6Local  Add                OtherClass     ApexClass    /OtherClass.cls
7Local  Add                Event          QuickAction  /Event.quickAction-meta.xml
8Remote Deleted            MyWidgetClass  ApexClass    /MyWidgetClass.cls-meta.xml
9Remote Deleted            MyWidgetClass  ApexClass    /MyWidgetClass.cls
10Remote Changed (Conflict) NewClass       ApexClass    /NewClass.cls-meta.xml
11Remote Changed (Conflict) NewClass       ApexClass    /NewClass.cls

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:

1sfdx force:source:pull -u MyDevSandbox

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.

1sfdx force:source:push -u MyDevSandbox

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.

1sfdx force:source:retrieve -m ApexClass:MyApexClass -u MyDevSandbox

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.

1sfdx force:source:push -u MyDevSandbox

Working with Source Tracking in a Sandbox

When source tracking is enabled in a sandbox that multiple developers collaborate in, who sees who’s changes?

Local workspace changes on one developer’s machine are visible to only that developer. Other developers working in the sandbox aren’t notified by source tracking that another developer has pending changes. After a change is pushed to a sandbox, source tracking notifies other developers that they can pull the change.

Let’s walk through an example scenario.

Say that two developers, Sarah and Tracy, are working in the same sandbox and have identical local workspaces. Source tracking tells them that there are no pending changes between the sandbox and their local workspace.

Now say that Sarah creates an Apex class named SarahsClass in her local workspace.

Before Sarah pushes the Apex class to the sandbox, source tracking tells her that an Apex Class exists in her local workspace but not on the sandbox.

1=== Source Status
2STATE                     FULL NAME      TYPE         PROJECT PATH
3─────────────             ─────────      ─────────     ───────────────────────────────────────────────────
4Local  Add                SarahsClass    ApexClass    /SarahsClass.cls-meta.xml
5Local  Add                SarahsClass    ApexClass    /SarahsClass.cls-meta.xml

Source tracking tells Tracy that there are no pending changes between her local workspace and the sandbox.

1=== Source Status
2No results found

After Sarah pushes the Apex class SarahsClass to the sandbox, source tracking tells Sarah that there are no changes between her local workspace and the sandbox.

1=== Source Status
2No results found

Source tracking tells Tracy that there is an Apex class in the sandbox that isn’t in her local workspace.

1=== Source Status
2STATE                     FULL NAME      TYPE         PROJECT PATH
3─────────────             ─────────      ─────────     ───────────────────────────────────────────────────
4Remote  Add               SarahsClass    ApexClass     
5Remote  Add               SarahsClass    ApexClass

To get the Apex class Sarah created in her local workspace, Tracy now knows to run sfdx force:source:pull.

Retrieving and Pulling Changes to Profiles with Source Tracking

Retrieving and pulling profiles behaves a little differently with source tracking.

Without source tracking, retrieving profiles doesn’t return all profile information. Retrieving profiles returns information about profiles that pertains to other items specified in the packing.xml file.

For example, retrieving profiles with this package.xml file returns profile permissions for the MyCustomField__c custom field on the Account object.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3 <types>
4  <members>Account.MyCustomField__c</members>
5  <name>CustomField</name>
6 </types>
7 <types>
8  <members>*</members>
9  <name>Profile</name>
10 </types>
11 <version>50.0</version>
12</Package>

With source tracking, retrieving profiles returns profile information pertaining to anything else specified in the package.xml file plus any entities getting tracked by source tracking. That includes any entity for which a change exists between your local workspace and the org.

For example, say you create a custom field on the Opportunity object called OppCustomField__c in your local environment. Source tracking detects the change and reports it. Now you retrieve profiles using the same package.xml file as you did when source tracking was off.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3 <types>
4  <members>Account.MyCustomField__c</members>
5  <name>CustomField</name>
6 </types>
7 <types>
8  <members>*</members>
9  <name>Profile</name>
10 </types>
11 <version>50.0</version>
12</Package>

Even though the package.xml file doesn’t reference OppCustomField__c, because source tracking is tracking the new custom field, your retrieve returns profile permissions for both the MyCustomField__c custom field on the Account object and the OppCustomField__c on the Opportunity object.

For more information about retrieving profiles, see the Profile metadata type in the Metadata API Developer Guide.

Although pull requests don’t include package.xml files, both pull requests and retrieve requests return profile information pertaining to everything reported by source tracking.

Note

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.