How to Exclude Source When Syncing or Converting

When syncing metadata between your local file system and a target org, you often have source files you want to exclude. Similarly, you often want to exclude certain files when converting source to Salesforce DX source 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 all the force:source:* commands, such as force:source:push, force:source:pull, force:source:deploy, and force:source:retrieve.

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 force:source:status, force:source:push, force:source:pull, force:source:deploy, and force:source:retrieve. 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 force:source:push, force:source:deploy, or force:source:status)
Marketing Profile.profile (ignores it during force:source:pull, force:source:retrieve, or force: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’re running.

Add the .forceignore file to the root of your project for the force:source:* tracking commands.
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

List the Files and Directories Currently Being Ignored

Use the force:source:ignored command to list the files and directories in your project that the force:source:* commands are currently ignoring. The force:source:ignored command refers to the .forceignore file to determine the list of ignored files.

Run the command without any parameters to list all the files in all package directories that are ignored. Use the --sourcepath parameter to limit the check to a specific file or directory. If you specify a directory, the command checks all subdirectories recursively.

This example checks if a particular file is ignored.

1sfdx force:source:ignored:list --sourcepath=package.xml

This example gets a list of all ignored files in a specific directory.

1sfdx force:source:ignored:list --sourcepath=force-app/main/default

Sample output if the command finds ignored files:

1Found the following ignored files:
2force-app/main/default/aura/.eslintrc.json
3force-app/main/default/lwc/.eslintrc.json
4force-app/main/default/lwc/jsconfig.json

Sample output if the command doesn’t find the specified file:

1ERROR running force:source:ignored:list:  ENOENT: no such file or directory, stat 'package.xml'

Sample output if the file isn’t ignored:

1No ignored files found in paths:
2README.md

Salesforce DX Developer Guide