Deploy Source From Your Project to the Scratch Org
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
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
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