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.

1# Specify a relative path to a directory from the project root
2helloWorld/main/default/classes
3
4# Specify a wildcard directory - any directory named “classes” is excluded
5**classes
6
7# Specify file extensions
8**.cls
9**.pdf
10
11# Specify a specific file
12helloWorld/main/default/HelloWorld.cls

Salesforce DX Developer Guide