Salesforce SFDX projects are a great way to build both declaratively and through code for the Salesforce platform. It’s very common to want to ignore particular files from being pushed or pulled between Orgs and your local project, and this is achieved through .forceignore file. The file has some odd (and undocumented) syntax however, and the process is also known to have a few bugs, and getting the right entries in the file can be hard… and that’s where the SFignore SFDX plugin comes in.
The .forceignore file and the process behind it is sprinkled with black magic – Todd Halfpenny, 2020
I’ve created the SFignore plugin initially through an internal need for the work I’ve been doing with the Caddify project at MobileCaddy. A lot of this work has been around using Salesforce 2GP (second generation packaging) tools to create packages for our new product. Our workflow includes pushing, pulling, deploying to many different shape orgs and includes a fair bit of code and metadata that is used solely for non-production scenarios (test setup, demo data, org cleaning, etc) and we want to make sure that nothing accidentally gets put into our managed package releases. The .forceignore file that is used by the SFDX CLI tooling and tracking allows us to do this – or most of it at least… but it’s syntax is nuanced and is lacking in documentation.
The SFignore plugin gives me an easier way to add entries to the .forceignore file, by taking away the guessing of syntax and the need to remember the correct suffixes for the different metadata types. This is useful, as would you know (or remember) if the correct suffix for a SiteDotCom entry should be SiteDotCom, siteDotCom, or site? And what about AppMenu? Would you know whether to use appMenu, AppMenu, Menu, menu? Only one of these is right, and the syntax differs further depending on whether the change is local or remote. Oh you also need to encode (some) special characters too… if you didn’t know that then this could be why your entry for “Custom: Sales Profile.profile” isn’t working as you expected.
The initial release only supports entries for remote changes, and only a subset of metadata types that I’ve had to use so far… but the roadmap for it includes;
- Support for local syntax
- Wildcarding – currently only supports specific entries
- An extension for vscode.
Here’s an example of using the plugin, where we’re wanting to add an entry to ignore pulls for the profile Custom: Sales Profile.
sfdx sfignore:add -n "Custom: Sales Profile" -m Profile
This results in the following entry being added;
Custom%3A Sales Profile.profile
The -m flag specifies the metadata type, and the valid values should match those as seen on Salesforce’s metadata coverage report and the output of a sfdx force:source:status command.
It should also be noted that something’s appear to be impossible to achieve with the .forceignore file, including;
- Adding some tests – yeah, sorry
- Specifying specific custom fields
- Specifying specific custom metadata
- Specifying specific record types
If you know how to achieve the above I’d be very happy to hear about it.
You can find the source for SFignore SFDX plugin on github, and you can download it from the npm registry too
sfdx plugins:install sfignore
If you use the plugin and need more metadata types added then please raise an issue on github, or even better fork the repo and create a PR.
One Reply to “SFignore: The .forceignore Salesforce SFDX Plugin”