> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/building-artifacts/configuring-installation-behaviour-of-a-package/component-checksum-skip.md).

# Component checksum skip

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. | <ul><li>source</li><li>diff</li></ul> |

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

{% code title="sfdx-project.json" %}

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

{% endcode %}

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

{% hint style="info" %}
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](https://docs.flxbl.io/codev/inspect/change-validation) for the details.
{% endhint %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/building-artifacts/configuring-installation-behaviour-of-a-package/component-checksum-skip.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.