Salesforce DX Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
How Salesforce Developer Experience (DX) Tooling Changes the Way You Work
Provide Developers Access to Salesforce DX Tools
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
Scratch Org Snapshots
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
Work with Data
Development
Build and Release Your App
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Deploy Source From Your Project to the Scratch Org

After changing the source, you can sync the changes to your scratch org by deploying the changed source to it with the project deploy start command.

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. 

sf org create scratch --definition-file config/project-scratch-def.json --no-track-source

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

Note

The first time you deploy source to the org, all source in the package directories in the sfdx-project.json file is deployed to the scratch org to complete the initial setup. At this point, Salesforce CLI starts source-tracking locally on the file system and remotely in the scratch org to determine which metadata has changed. Let’s say you deployed an Apex class to a scratch org and then decide to modify the class in the scratch org instead of your local file system. Salesforce CLI tracks in which local package directory the class was created, so when you retrieve it back to your project, it knows where it belongs.

To run the deploy 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 Deployment

Before you deploy source to an org, you can preview the components that will be deployed, the potential conflicts, and the ignored files by executing project deploy preview. For example, this command displays a preview of deploying all the source in your project to a scratch org with alias MyGroovyScratchOrg. 

sf project deploy preview --target-org MyGroovyScratchOrg

Use flags to target the source you want to preview, such as only the source listed in a manifest. In this example, --target-org points to the scratch org’s username.

sf project deploy preview --manifest package.xml --target-org test-am6xqkossaq8@example.com

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

Deploy Source to a Scratch Org

To deploy changed local source to your default scratch org, run this command.

sf project deploy start

The command displays what it deployed. This sample output shows a deployment of the PropertyController Apex class.

Deploying v58.0 metadata to test-am6xqkossaq8@example.com using the v59.0 SOAP API.
Deploy ID: 0Af7e00001WsuoSCAR
Status: Succeeded | ████████████████████████████████████████ | 1/1 Components (Errors:0) | 0/0 Tests (Errors:0)

Deployed Source
=====================================================================================================
| State   Name               Type      Path                                                           
| ─────── ────────────────── ───────── ────────────────────────────────────────────────────────────── 
| Changed PropertyController ApexClass force-app/main/default/classes/PropertyController.cls          
| Changed PropertyController ApexClass force-app/main/default/classes/PropertyController.cls-meta.xml

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

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

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

Select Files to Ignore During Deploys

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 deploy command.

If the Deploy Detects Warnings

If you run project deploy start, and warnings occur, Salesforce CLI doesn’t deploy the source. Warnings can occur, for example, if your project source is using an outdated version. If you want to ignore these warnings and deploy the source to the scratch org, run:

sf project deploy start --ignore-warnings

Although you can successfully deploy using this option, we recommend addressing the issues in the source files. For example, if you see a warning because a Visualforce page is using an outdated version, consider updating your page to the current version of Visualforce. This way, you can take advantage of new features and performance improvements.

Tip

If the Deploy Detects File Conflicts

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

However, if you run project deploy start, and conflicts are detected, Salesforce CLI terminates the operation and doesn’t deploy 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.

sf project deploy start
 STATE    FULL NAME          TYPE      FILE PATH                                                                                                 
 ──────── ────────────────── ───────── ───────────────────────────────────────────────────────────────────────────────────────────────────────── 
 Conflict PropertyController ApexClass <dir>/force-app/main/default/classes/PropertyController.cls-meta.xml 
 Conflict PropertyController ApexClass <dir>/force-app/main/default/classes/PropertyController.cls          
Error (1): There are changes in the org that conflict with the local changes you're trying to deploy.

First decide which change you want to keep. To keep the local change, rerun the deploy and specify the --ignore-conflicts flag.

sf project deploy start --ignore-conflicts

To keep the change that’s in the org, run the project retrieve start command to retrieve the change to your local project, and specify the --ignore-conflicts flag. 

sf project retrieve start --ignore-conflicts