Salesforce CLI Setup Guide

Before You Begin
Install Salesforce CLI
Install the CLI Release Candidate
Run Salesforce CLI Using a Docker Image
Update Salesforce CLI
Salesforce CLI Plug-ins
Salesforce CLI Configuration and Tips
Uninstall Salesforce CLI or Plug-ins
Troubleshoot Salesforce CLI
CLI Deprecation Policy
Next Steps
Get Started with Salesforce CLI Unification
How sf and sfdx Work Together
Install and Update sf
Run Through the Dreamhouse Example
List of sf Commands with sfdx Equivalents
List of sfdx Commands with sf Equivalents
Environment Variables
Understand Source Tracking in sf
PDF

Newer Version Available

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

Understand Source Tracking in sf

Source tracking in sf works basically the same as in sfdx, but with a few small differences outlined in this topic.

These sf commands support source tracking:

  • sf deploy metadata
  • sf deploy metadata validate
  • sf retrieve metadata

Let’s start with deploying. The first time you run sf deploy metadata on a scratch or sandbox org that allows source-tracking, the command deploys all the source files from your local project. But when you next run the command, it deploys only the files that changed locally. If you use one of the flags to narrow the deploy list (--source-dir, --metadata, or --manifest), then the command deploys changed files only in the specified directory, metadata, or manifest. If you don’t specify any of the flags, then the command deploys all changes in the project, similar to how force:source:push in sfdx works.

The sf metadata deploy validate command works in a similar way, except the actual deployment and source tracking happens when you later run sf deploy metadata quick.

The sf retrieve metadata command is the same as deploy, but in reverse. The first time you retrieve, everything is retrieved; the next time only changes in the org are retrieved. If you don’t specify --source-dir, --metadata, or --manifest, then all changes in the org are retrieved, just like force:source:pull.

If one of these commands detects a conflict in the files you’re about to deploy or retrieve, the command displays the conflicts. Use the --ignore-conflicts flag to force the deployment or retrieval of the changes. This flag is similar to the --forceoverwrite parameter of many of the force:source commands in sfdx. For example:

1sf deploy metadata --source-dir force-app --ignore-conflicts

Determine If Your Org Allows Source Tracking

Source tracking works only if your target org allows it. Don’t worry, you can still deploy or retrieve metadata to and from the org in that case. But the commands don’t check for conflicts, and you must specify what you want to deploy or retrieve using an appropriate flag, such as --source-dir.

Here’s how to determine whether your org allows source tracking:

  • Production orgs, Partial Copy sandboxes, and Full sandboxes never allow source tracking.
  • Developer and Developer Pro sandboxes:
    • Allow source tracking if their associated production org has been enabled for source tracking.
    • You can opt out of source tracking when you create the sandbox with the --no-track-source flag of the sf env create sandbox command. For example:
      1sf env create sandbox -f config/dev-sandbox-def.json --target-org prodOrg --no-track-source
  • Scratch orgs allow source tracking by default.
    • You can opt out of source tracking when you create the scratch org with the --no-track-source flag of the sf env create scratch command. For example:
      1sf env create scratch --target-dev-hub=MyHub --definition-file config/project-scratch-def.json --no-track-source

Considerations

Keep these considerations in mind when using source tracking in sf:

  • The sf deploy metadata command doesn't support the pushPackageDirectoriesSequentially option of the sfdx-project.json file to deploy package directories sequentially. The command always deploys all package directories in a single transaction in undetermined order. If you must specify a deployment order of your package directories, run multiple sf deploy metadata commands, one for each package directory, in the required order.
  • The sfdx commands force:source:pull and force:source:push are compatible with source tracking in sf.
  • The sfdx commands force:source:deploy, force:source:delete, and force:source:retrieve are compatible with source tracking in sf as long as you use the --tracksource parameter. Unlike sf deploy and retrieve commands, these sfdx commands don’t track your source unless you use that parameter.
  • To make destructive changes, first delete the files locally and then run sf deploy metadata. Like force:source:push, the sf deploy metadata command deletes metadata from your org that you deleted locally.
  • You can use these sfdx commands to list your local and remote source file changes, or to reset or clear source tracking:
    • force:source:status
    • force:source:tracking:reset
    • force:source:tracking:clear

  • Don’t use the force:source:legacy commands with the sf deploy|retrieve metadata commands because they’re incompatible with each other.

    Warning