Component checksum skip

How sfp skips byte-identical components when installing a changed source or diff package, and the controls that turn it off.

When sfp installs a source or diff package whose version differs from the one recorded in the target org, it fetches the previously installed artifact from the registry and skips the components whose source bytes are unchanged, deploying only the components that actually differ. On a release that changes a few components in a large package, this removes the unchanged majority from the Metadata API payload.

The optimisation is on by default and strictly additive: whenever the previous artifact or its checksums are unavailable, the install falls back to deploying the full component set, exactly as before.

Attribute	Type	Description	Package Types Applicable
disableChecksumSkip	boolean	Turns component checksum skip off for this package. The package always deploys its full component set.	source diff

How it works

At build time, sfp build records a SHA-256 hash for every file in the package's source/ directory into the artifact's artifact_metadata.json. Artifacts built by an older sfp have no such record and are handled by the fallback below.

At install time, when sfp is about to install version N+1 of a package and the org already records version N as installed, it:

1. Fetches the version N artifact from the same registry as the new one.
2. Compares the two per-file checksum maps.
3. Removes from the deploy every component whose files are all present in both maps with matching hashes.

The version N record comes from the org's own sfp_artifact__c data — the same source the existing package-level skip already uses — so no additional data is written into the target org.

When it applies

Situation	What deploys
Package version changed, previous artifact fetchable, both carry checksums	Only the changed components, plus the always-retained types below
First install of the package into this org	Full component set
Package version unchanged	Nothing — the existing package-level skip runs before this filter
Previous artifact cannot be fetched (registry error, version removed)	Full component set
Previous artifact predates this feature (no checksums recorded)	Full component set
Every component matched (nothing left to deploy)	Full component set — see below

Empty-filter fallback. If the filter would remove every component, sfp deploys the original component set instead. A version bump the operator made deliberately stays observable in the org, and the sfp_artifact__c record advances to the new version.

What is always deployed

The filter errs toward deploying. A component is skipped only when every file it owns is present in both checksum maps with matching hashes; any other case keeps it in the deploy.

Always-retained component types. Profile, PermissionSet, PermissionSetGroup, and CustomLabels are always deployed. sfp mutates these at install time based on the target org's current state, so the raw source hash is not a sound proxy for what would be sent.

Bundle parents. Lightning web component, Aura, static-resource, and custom-object parents are retained, because their content resolves to a directory rather than a hashed file. Salesforce reports no changes for the unchanged files in the bundle.

Package-level bypass. The filter is skipped for the whole package — every component deploys — when the package's descriptor or artifact indicates install-time mutation that a build-time hash cannot represent:

• replacements configured, or a runtime --replacementsoverride — file content is rewritten per org.
• aliasfy — install selects per-alias subdirectory content.
• alwaysDeploy: true — full deploy regardless of org state.
• ignoreLayoutAssignments: true, or a mutators/layout-assignments.yml in the package — layout assignments are composed from org state at install.
• A runtime --pathToReplacementForceIgnore, or a .forceignore (or forceignores/.deployignore) that differs between the two artifact versions — the set of deployable files at install differs from what was hashed at build.
• disableChecksumSkip: true — the per-package opt-out.

Test level

When the filter reduces the deploy set for a package that contains Apex, sfp upgrades the deploy's test level to RunRelevantTests, so Salesforce runs only the tests the deployed components touch rather than the full local suite. The upgrade does not apply when testing is skipped, during validation, or when the test level was explicitly set to run no tests.

Turning it off

For one package — add disableChecksumSkip to the package descriptor in sfdx-project.json. The package always deploys in full.

sfdx-project.json

{
  "packageDirectories": [
    {
      "path": "src/territory-management",
      "package": "territory-management",
      "versionNumber": "1.2.0.NEXT",
      "disableChecksumSkip": true
    }
  ]
}

For one run — pass --no-checksum-skip to sfp install, sfp release, sfp validate org, or sfp validate pool. This is the same mental model as opting out of the existing skip when org drift is suspected.

For the install to fetch the previous artifact, sfp needs registry access. Supply it with --scriptpath, --scope, and --npmrcpath on sfp install, or run against an sfp server, which uses its internal registry automatically.

When sfp runs from a server — pull-request validation, release, build-on-merge — the optimisation can also be turned off per project, per environment, or per target branch. Those controls live in codev. See Change validation for the details.

Validation

sfp validate org and sfp validate pool run the skip by default, so a validation deploys the same reduced payload a release would — you validate what you will ship. (sfp prepare never runs it; pool orgs are built from full installs.)

For the skip to reduce the payload during validation, the review org must have a recorded artifact version that still exists in the registry, so sfp can fetch the previous artifact to compare against. Whether that holds across iterations depends on one validation setting:

• Artifact update on (the default). After the first validation, sfp records the locally built validation version on the review org. That version is never published, so the next iteration cannot fetch it — that package falls back to a full deploy. The skip helps only the first iteration on a reused org.
• disableArtifactUpdate set (in the validation workflow settings). The review org's records stay pinned to the published baseline, so every iteration fetches the same baseline and deploys only what changed.

Pair the skip with disableArtifactUpdate to keep validation deploying only the changed components on every pull-request iteration.

Drift

The optimisation assumes that a version recorded as installed matches the components built for that version — the same assumption the existing package-level skip already makes. It does not change drift safety. When drift is suspected, deploy that release with --no-checksum-skip.