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
Supported Scratch Org Editions and Allocations
Build Your Own Scratch Org Definition File
Create a Scratch Org Based on an Org Shape
Create Scratch Orgs
Select the Salesforce Release for a Scratch Org
Deploy Source From Your Project to the Scratch Org
Retrieve Source from the Scratch Org to Your Project
Scratch Org Users
Manage Scratch Orgs from the Dev Hub Org
Scratch Org Error Codes
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
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

Retrieve Source from the Scratch Org to Your Project

After you do an initial deploy, your changes are tracked between your local file system and your scratch org. If you change metadata in your scratch org, retrieve those changes to your local project to keep both in sync.

Scratch orgs have source tracking enabled by default. But sometimes you don’t want source tracking, such as in a continuous integration environment when you want to speed up deployments. You can opt out of source tracking when you create the scratch org by specifying the --no-track-source flag.

See Create Scratch Orgs for more reasons to disable source tracking.

Note

To run the retrieve commands described in the remainder of this topic, first open a terminal (macOS and Linux) or command window (Windows) and then change to your Salesforce DX project directory.

Preview a Retrieve

Before you retrieve metadata from an org, you can preview the components that will be retrieved, the potential conflicts, and the ignored files by executing project retrieve preview. For example, this command displays a preview of retrieving changed metadata from a scratch org with the alias MyGroovyScratchOrg to your local project.

You can create an alias for an org using alias set. To display the usernames and aliases of all the scratch orgs you’ve created, run org list.

Tip

Retrieve Metadata from Your Scratch Org

To retrieve changed source from your default scratch org to your project, run this command

The command displays what it retrieved and where in your local Salesforce DX project it puts it. This sample output shows a retrieve of the DiscountSpecial Apex class and DiscountPermSet permission set into the force-app/main/default directory.

Use flags to target the source you want to retrieve, rather than everything that’s changed.

  • Use the --metadata flag to retrieve specific metadata components, such as Apex classes.
  • Use the --manifest flag to retrieve components in a manifest file.
  • Use --source-dir to retrieve source in a package directory.

See the reference information about project retrieve start for examples and other flags you can specify.

Select Files to Ignore During Retrieves

It’s likely that you have some files that you don’t want to sync between the project and scratch org. Add these files to the .forceignore file so they’re ignored by the retrieve command.

If the Retrieve Detects File Conflicts

During development, you change files locally in your file system and change the scratch org using builders and editors. Usually, these changes don’t cause a conflict and involve unique files. Also, the project retrieve start command doesn’t handle merges. Projects and scratch orgs are meant to be used by one developer.

However, if you run project retrieve start, and conflicts are detected, Salesforce CLI terminates the operation and doesn’t retrieve the source. Instead, it displays conflict information, such as this sample output. The PropertyController Apex class has been changed both locally and in the org, but the changes are in conflict.

First decide which change you want to keep. To keep the change that’s in the org, rerun the retrieve and specify the --ignore-conflicts flag.

To keep the local change, run the project deploy start command to deploy the change to your org, and specify the --ignore-conflicts flag.