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.

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:

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

You can create an alias for an org using 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:

Although you can successfully 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.

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.

If Push Detects a Username Reference in the Source

Some metadata types include a username in their source. When you run force:source:push to push this source to a scratch org, the push command replaces the username with the scratch org’s administrator username. This behavior ensures that the push succeeds, even if the scratch org does not contain the original username.

For example, let’s say that you create a scratch org and use Lightning Experience to create a report folder. You then create a report and save it to the new folder. You run force:source:pull to pull down the source from the scratch org to your project. The *.reportFolder-meta.xml source file for the new ReportFolder is similar to this example; note the <sharedTo> element that contains the username test-ymmlqf5@example.com.

You then create a different scratch org whose administrator’s username is test-zuwlxy321@example.com. If you push the ReportFolder’s source file to the new scratch org, force:source:push replaces the test-ymmlqf5@example.com username with test-zuwlxy321@example.com.

This behavior applies only to force:source:push and scratch orgs. If you use force:mdapi:deploy to deploy metadata to a regular production org, for example, the deploy uses the username referenced in the source.

Next steps:

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

Salesforce DX Developer Guide