Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Salesforce CLI Configuration and Tips
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Scratch Org Definition File
Scratch Org Definition Configuration Values
Create Scratch Orgs
Salesforce DX Project Structure and Source 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
Track Changes Between the Project and Scratch Org
Scratch Org Users
Manage Scratch Orgs from Dev Hub
Development
Build and Release Your App
First-Generation Managed Packages
Unlocked Packages (Generally Available) and Second-Generation Managed 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

How to Exclude Source When Syncing or Converting

When syncing metadata between your local file system and a scratch org, you often have source files you want to exclude. Similarly, you often want to exclude certain files when converting source to Salesforce DX project format. In both cases, you can exclude individual files or all files in a specific directory with a .forceignore file.

Use your favorite text editor to create a .forceignore file to specify the files or directories you want to exclude.

The .forceignore file excludes files when running the source commands: force:source:convert, force:source:push, force:source:pull, and force:source:status.

Other Files That the Source Commands Ignore

The source commands ignore these files even if they aren’t included in your .forceignore file.
  • Any source file or directory that begins with a “dot”, such as .DS_Store or .sfdx
  • Any file that ends in .dup
  • package2-descriptor.json
  • package2-manifest.json

Exclude Remote Changes Not Yet Synced with Your Local Source

Sometimes, you make a change directly in a scratch org but you don’t want to pull that change into your local DX project. To exclude remote metadata changes, use the format <api name>.<metadata type> in .forceignore.

If you have a permission set named “dreamhouse,” add dreamhouse.permissionset to .forceignore.

Exclude the Same Metadata for Source Tracking Commands

To exclude the same metadata in your local DX project (file system) and in a scratch org, create two entries to cover source:status, source:push, and source:pull. For example, if you have a custom profile called Marketing Profile, include these two entries in .forceignore:
  • force-app/main/default/profiles/Marketing Profile.profile-meta.xml (ignores it during source:push or source:status)
  • Marketing Profile.profile (ignores it during source:pull or source:status)

Metadata with Special Characters

If a metadata name has special characters (such as forward slashes, backslashes, or quotation marks), we encode the file name on the local file system for all operating systems. For example, if you pull a custom profile called Custom: Marketing Profile, the colon is encoded in the resulting file name.

Custom%3A Marketing Profile.profile-meta.xml

If you reference a file name with special characters in .forceignore, use the encoded file name.

Where to Put .forceignore

Be sure the paths that you specify in .forceignore are relative to the directory containing the .forceignore file. For the .forceignore file to work its magic, you must put it in the proper location, depending on which command you are running.

  • Add the .forceignore file to the root of your project for the source tracking commands: force:source:push, force:source:pull, force:source:status, and force:source:convert.
  • Add the file to the Metadata retrieve directory (with package.xml) for force:mdapi:convert.

Sample Syntax

The .forceignore file has similar functionality to .gitignore. Here are some options for indicating which source to exclude. In this example, all paths are relative to the project root directory.