Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Project Setup
Authorization
Scratch Orgs
Scratch Org Definition File
Scratch Org Definition Configuration Values
Create Scratch Orgs
Supported Metadata API Types
Salesforce DX Project Structure and Source File Format
Push Source to the Scratch Org
How to Exclude Source When Syncing or Converting
Assign a Permission Set
Ways to Add Data to Your Scratch Org
Pull Source from the Scratch Org to Your Project
Scratch Org Users
Manage Scratch Orgs from the Dev Hub
Development
Build and Release Your App
Develop Second-Generation Packages (Beta)
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

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

Push Source to the Scratch Org

After changing the source, you can sync the changes to your scratch org by pushing the changed source to it.

The first time you push metadata to the org, all source in the folders you indicated as package directories is pushed to the scratch org to complete the initial setup. At this point, we start change-tracking locally on the file system and remotely in the scratch org to determine which metadata has changed. Let’s say you pushed an Apex class to a scratch org and then decide to modify the class in the scratch org instead of your local file system. The CLI tracks in which local package directory the class was created, so when you pull it back to your project, it knows where it belongs.

You can use force:source:push for scratch orgs only. If you’re synchronizing source to another org, use the Metadata API.

Warning

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.

The push command doesn’t handle merges. Projects and scratch orgs are meant to be used by one developer. Therefore, we don’t anticipate file conflicts or the need to merge. However, if the push command detects a conflict, it terminates the operation and displays the conflict information to the terminal. You can rerun the push command and force the changes in your project to the scratch org.

Before running the push command, you can get a list of what’s new, changed, and the conflicts between your local file system and the scratch org by using force:source:status. This way you can choose ahead of time which version you want to keep and manually address the conflict.

Pushing Source to a Scratch Org

To push changed source to your default scratch org:

1sfdx force:source:push
2
3STATE    FULL NAME      TYPE       PROJECT PATH
4───────  ─────────────  ─────────  ────────────────────────────────────
5Changed  MyWidgetClass  ApexClass  /classes/MyWidgetClass.cls-meta.xml
6Changed  MyWidgetClass  ApexClass  /classes/MyWidgetClass.cls

To push changed source to a scratch org that’s not the default, you can indicate it by its username or alias:

1sfdx force:source:push --targetusername scratchorg148@acme.com
1sfdx force:source:push -u scratchorg148@acme.com
1sfdx force:source:push -u MyGroovyScratchOrg

You can create an alias for an org using force:alias:set. Run force:org:list to display the usernames of all the scratch orgs you have created.

Tip

Selecting Files to Ignore During Push

It’s likely that you have some files that you don’t want to sync between the project and scratch org. You can have the push command ignore the files you indicate in .forceignore.

If Push Detects Warnings

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

1sfdx force:source:push --ignorewarnings

Although you can successsfully push 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 Push Detects File Conflicts

If you run force:source:push, and conflicts are detected, the CLI doesn’t push the source. 

1STATE    FULL NAME      TYPE       PROJECT PATH
2───────  ─────────────  ─────────  ─────────────────────────────────
3Conflict NewClass       ApexClass  /classes/CoolClass.cls-meta.xml
4Conflict NewClass       ApexClass  /classes/CoolClass.cls

Notice that you have a conflict. CoolClass exists in your scratch org but not in the local file system. In this new development paradigm, the local project is the source of truth. Consider if it makes sense to overwrite the conflict in the scratch org.

If conflicts have been detected and you want to override them, here’s how you use the power of the force (overwrite) to push the source to a scratch org.

1sfdx force:source:push --forceoverwrite

Next steps:

  • To verify that the source was uploaded successfully to the scratch org, open the org in a browser.
  • Add some sample test data.