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 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.

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.

Structure of the .forceignore File

The .forceignore file structure mimics the .gitignore structure. Each line in .forceignore specifies a pattern that corresponds to one or more files. The files typically represent metadata components, but can be any files you want to exclude, such as LWC configuration JSON files or tests.

The force:source:* commands, when parsing the .forceignore file, use the same rules and patterns as the .gitignore file. A few common examples of these rules and patterns include:

Always use the forward slash (/) as a directory separator, even on operating systems that use back slashes, such as Microsoft Windows.
An asterisk (*) matches anything except a forward slash (/).
Two consecutive asterisks (**) in patterns have special meaning, depending on where they’re located in the pathname. See for examples.
For readability, use blank lines as separators in the .forceignore file.

There are many more rules and patterns. See the git documentation for details.

Determine the Exact Filename for a Metadata Component

As you build your .forceignore file, you need the exact name of the metadata components that you want to exclude. Use this pattern to determine the filename of a particular metadata component:

1<component-API-name>.<md-type-file-suffix>-meta.xml

<component-API-name> is the unique name of the component used by the Salesforce APIs. API names contain only alphanumeric characters or underscores.
<md-type-file-suffix> is the file suffix for the metadata type. See the Declarative Metadata File Suffix and Directory Location section for the specific metadata type in the Metadata API Developer Guide.

For example, the filename for the profile with API name NotUsedProfile is NotUsedProfile.profile-meta.xml. To specify that the force:source:* commands exclude this component, add this entry to your .forceignore:

1**/NotUsedProfile.profile-meta.xml

Another way to determine the exact name of a metadata component is to look at the output of the force:source:* commands if you’re also using source tracking. For example, if you have either local or remote changes, run the force:source:status command to display the full pathname of the changed components. This command output displays the filename of the Dreamhouse permission set and the Settings custom tab in the PROJECT PATH column:

1STATE        FULL NAME       TYPE            PROJECT PATH
2──────────   ───────────     ─────────       ─────────────────────────────
3Local Add    Settings        CustomTab       ./tabs/Settings.tab-meta.xml
4Local Add    Dreamhouse      PermissionSet   ./permissionsets/Dreamhouse.permissionset-meta.xml

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, add an entry to .forceignore that represents the metadata source file that would be created if you did retrieve it.

For example, if you have a permission set named Dreamhouse, add this entry to .forceignore:

1**/Dreamhouse.permissionset-meta.xml

Exclude MetadataWithContent Types

Metadata components that include content, such as ApexClass or EmailTemplate, extend the MetadataWithContent type. These components have two source files: one for the content itself, such as the Apex code or email template, and the accompanying metadata file. For example, the source files for the HelloWorld Apex class are HelloWorld.cls and HelloWorld.cls-meta.xml.

To exclude a MetadataWithContent component, such as an ApexClass, either list both source files in the .forceignore file, or use an asterisk. For example:

1# Explicilty list the HelloWorld source files to be excluded
2helloWorld/main/default/HelloWorld.cls
3helloWorld/main/default/HelloWorld.cls-meta.xml
4
5# Exclude the HelloWorld Apex class using an asterisk
6helloWorld/main/default/HelloWorld.cls*

Exclude Bundles and File Groups

Use two consecutive asterisks (**) to exclude multiple files with just one .forceignore entry.

For example, to exclude all resource files related to a Lightning web component named myLwcComponent, add this entry to exclude the entire component bundle:

1**/lwc/myLwcComponent

To exclude all Apex classes:

1**/classes

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

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