Skip to content

How to exclude metadata from a deploy or scratch push

Some metadata must reach a scratch org during the scratchinit context but never land during a deployment, some must land during a deployment but never get overwritten by a later scratch-org push, and some must stay untouched by local sf pushes you run yourself while still deploying whenever the deployment or scratchinit context applies. Use this guide to pick the right file for the exclusion you need. For why the mechanism is split this way, see per-context .forceignore profiles.

Pick the file

You do not usually pass a context yourself: deploy applies deployment, org scratch-create applies scratchinit — on its own push and on the pooled delta validation it runs (per-context .forceignore profiles). Pick the file by the exclusion you need:

You want to ignore something... Edit this file
On every push, whether it runs through the DIA scripts or a raw sf command .forceignore, above the KEEP_UNTIL_HERE_FOR_INITIAL_PUSH line
Only on raw sf project deploy start / sf project source push runs you invoke yourself, but not when the deploy orchestrator or org scratch-create push through the DIA scripts .forceignore, below the token
Whenever the deploy orchestrator applies its deployment context (its default) .forceignoreDeployment
Whenever org scratch-create applies its scratchinit context .forceignoreScratchInit (create it if it does not exist yet)
Only in generated destructive changes — the file deploys normally but is never deleted from the org when removed from source .forceignoreDestructive (create it if it does not exist yet)

Each file uses standard .forceignore glob syntax — one path pattern per line.

Protect files from destructive changes

Add the pattern to .forceignoreDestructive: the file keeps deploying normally but never enters the generated destructive manifest. The boundaries of that filter are in delta: deploy only the diff.

Run a deploy with an explicit context

Pass --forceignore-context on a manual deploy invocation to override the default:

npm run deploy -- --target-org my-scratch-org --forceignore-context scratchinit

Only deployment and scratchinit are accepted; any other value fails the run immediately.

Verify

  1. Run node scripts/dia-scripts/deploy/prepare-forceignore.mjs apply --context <context> standalone, then check .forceignore — it should contain only the lines up to the token plus the extra file's contents.
  2. Run node scripts/dia-scripts/deploy/prepare-forceignore.mjs restore and confirm .forceignore is back to its original, full contents.
  3. Run the real deploy (or org scratch-create) with the context you expect and confirm the excluded component is absent from the result, and present when you switch context (or target a scratch org instead of a stage org, or vice versa).
  4. After the run, confirm .forceignore is back to its original contents — restore runs automatically once the DIA-scripts-driven run finishes.