Diff Package

A diff package is a variant of a 'source package' where the package contains only the components that changed. sfp generates it by computing a git diff of the current commit against the package's baseline — a commit sfp records for the package on the sfp server.

A diff package mimics a Change Set model, where only changes are contained in the artifact. As such, this package is always an incremental package. It only deploys the changes incrementally compared to baseline and applied to the target org. Unless both previous version and the current version have the exact same components, a diff package can never be rolled back, as the impact on the org is unpredictable. It is always recommended to roll forward a diff package by fixing or creating a necessary change that counters the impact that you want on the target orgs.

Diff packages don't work with scratch orgs. They should be used with sandboxes only.

A diff package is the least consistent package among the various package types available within sfp, and should only be used for transitioning to a modular development model as prescribed by flxbl.

Marking a package as a diff package

Set "type": "diff" on the package entry in sfdx-project.json. All other attributes applicable to source packages are applicable to diff packages. In the example below, unpackaged is a diff package:

// sfdx-project.json

{
  "packageDirectories": [
    {
      "path": "util",
      "default": false,
      "package": "Expense-Manager-Util",
      "versionName": "Winter ‘24",
      "versionDescription": "Welcome to Winter 2024 Release of Expense Manager Util Package",
      "versionNumber": "4.7.0.NEXT"
    },
     {
      "path": "unpackaged",
      "default": true,
      "package": "unpackaged",
      "versionName": "v3.2",
      "type":"diff"
    }
  ],
  "sourceApiVersion": "58.0",
  "packageAliases": {
    "TriggerFramework": "0HoB00000004RFpLAM",
    "Expense Manager - Util": "0HoB00000004CFpKAM",
    "External Apex Library@1.0.0.4": "04tB0000000IB1EIAW",
    "Expense Manager": "0HoB00000004CFuKAM"
  }
}

The baseline

The baseline is the commit a diff build compares against. sfp maintains a baseline record per package, per branch, on the sfp server. A record has:

  • a fallback (default) baseline — the commit used until at least one environment registered for the branch has recorded a deployment;
  • an optional environment baseline per environment — the commit that environment last deployed.

Only a diff package builds from its baseline. For source, unlocked, and data packages the same record still exists, but it never limits what gets packaged — those types always build in full. There the record tracks the commit each environment has deployed and, until the package's first publish, anchors the range over which version intents and changelogs are computed.

How the baseline is registered

A package's baseline is registered automatically the first time it is built or when the project is preflighted — sfp records the last commit that touched the package's directory. Running sfp project preflight registers baselines for any package that does not yet have one; sfp project preflight --validate reports what would be registered without writing anything. On a branch that is not tracked, sfp resolves the baseline from the nearest tracked parent branch.

How the baseline is resolved for a build

At build time sfp resolves the commit the diff is computed from, using the environments registered for the branch:

  1. If no environment is registered, or none has recorded a deployment of the package yet, the fallback baseline is used.
  2. Otherwise the environment baseline furthest behind is used, so the diff covers everything not yet on every environment that has a deployment. An environment with no recorded deployment is skipped: it does not send the build back to the fallback baseline.
  3. A recorded commit that is not in the build's checkout is skipped as well. If no recorded commit is left, the fallback baseline is used.

The build log names the environments it compared and the ones it skipped:

core-crm: using most-behind commit from 2 of 3 environment(s) (prod) → 26d70a74; skipped, no baseline yet: uat

Environments ahead of the build start

A diff compares two end states. A change that was made and then undone after the build start, such as a reverted file or a deleted component that was restored, does not appear in the diff from the build start. An environment whose baseline is ahead of the build start can still hold the in-between state:

prod (build start)uat (ahead)Current commit
A classversion 1version 2version 1 (reverted)
An objectexistsdeletedexists (restored)

For each counted environment whose baseline is not the build start, the build also adds the files of the package that changed since that environment's baseline but not since the build start. These files have the same content at the current commit as at the build start, so deploying them to the environment at the build start leaves its components unchanged. When every environment only moves forward, nothing is added and the artifact is the same as without this step.

The build log names each environment and the files added for it:

core-crm: added 1 file(s) for uat (baseline 9f8e7d6c), changed since that baseline but not since the build start 26d70a74: src/core-crm/main/default/classes/Greeter.cls

Files that a component needs alongside an added file, such as its -meta.xml, are added with it.

The package's details in the build summary show an Added For environment row with the number of files and the baseline. The artifact records the added files per environment in baselineAdditions. Source Version From stays the build start.

A validation that starts the diff at the review org's installed commit also adds the files for the review org's commit. sfp sync org and a build from the working tree add nothing.

Files deleted since an environment's baseline

A file that the environment ahead has, that was deleted after its baseline and that the build start never had, is not deleted by the deployment. The build logs a warning naming these files:

core-crm: uat (baseline 9f8e7d6c) has 2 file(s) that were deleted after that baseline and that the build start 26d70a74 never had: src/core-crm/main/default/classes/Foo.cls, src/core-crm/main/default/classes/Foo.cls-meta.xml. This artifact doesn't delete them, so they stay in that environment. One that depends on what this artifact changes fails the deploy when it runs Apex tests, and is otherwise left invalid. To delete them before the deploy, add them to the package's pre-destructive folder.

A component that nothing in the artifact references stays in the environment and does not affect the deployment. To delete one before the deployment, add it to the package's pre-destructive folder. On the environment at the build start, which never had the component, the delete is reported as a warning and the deployment continues.

An environment deployed before these files were added

An artifact built by an sfp version that does not add these files leaves the environment ahead with its in-between state, and its baseline still advances to the deployed commit. sfp sync org finds nothing to sync for it, because the org's artifact records are already at that commit. To bring the files, an owner edits the environment's baseline back to the commit it had before that deployment; see Viewing and editing the baseline. The next build of the package then adds the files for it.

A new environment's first deployment

A newly registered environment has no baseline, so its first deployment installs the same artifact as the other environments: the changes since the furthest-behind recorded environment. sfp does not check what the new environment's org already contains. If the org is at least as current as that environment, for example a sandbox created or refreshed from production, nothing is missed. If the org is older, the changes between the org's state and that commit are not in the artifact.

When a deployment installs a diff package into an environment that has no baseline for it, the deployment log warns before the first baseline is recorded:

uat has no recorded baseline for core-crm; this artifact only contains changes since 26d70a74

If the org was deployed by other means, or is a copy of another org, its sfp artifact records (SfpowerscriptsArtifact2__c) may already name the commit each package was built from. A project owner can make those commits the environment's baselines in codev before the first deployment; see Adopting the org's state as baseline. The environment is then counted by the next diff build.

Renaming an environment

Renaming an environment moves its baselines to the new name, in the package baseline records of every branch of the repository. If the new name already has a baseline for a package, that baseline is kept.

How the baseline advances

After a successful deployment, the deployment pipeline advances that environment's baseline to the deployed commit. The next diff build for that environment then packages only what changed since it. This is automatic — the pipeline moves the baseline forward as the package progresses through environments.

For a diff package, the baseline advances only when the deployed artifact covers the environment, that is, when the artifact starts at or before the environment's baseline. Otherwise the baseline is held; see the next section.

When an artifact starts after an environment's baseline

A diff artifact contains the changes from its start commit (Source Version From in the build log) to the commit it was built from. If an environment's baseline is older than the start commit, the changes between the two are not in the artifact, and deploying it does not bring them to that environment. This is a baseline gap. It happens, for example, when a baseline was edited forward by hand before the build, or when the environment was not one of those counted when the artifact was built.

Before the deployment, sfp release and other deployments to a registered environment print a baseline check for each diff package. The check compares the artifact's start commit with the target environment's baseline:

Baseline check for prod
Package   Version   Source Version From  prod baseline  Result
core-crm  1.0.0.12  68e1501d             b5457e4c       Gap: 5 commits, 2 files in core-crm
ResultMeaning
CoveredThe artifact starts at or before the environment's baseline, and carries every file the environment needs from it.
Missing N filesThe artifact starts before the environment's baseline, but lacks files that changed since that baseline and not since the artifact's start. See Environments ahead of the build start.
GapThe environment's baseline is older than the artifact's start. The result counts the commits in between and the files they change in the package.
No baselineThe environment has no baseline for the package yet, so there is nothing to compare.
Couldn't checkThe baseline could not be read, or the commits could not be compared.

For each gap, a warning names both commits:

core-crm 1.0.0.12 starts at 68e1501d but prod is at b5457e4c: the changes in between (5 commits, 2 files in core-crm) are not in this artifact and won't reach prod. The server keeps prod's baseline at b5457e4c so the next build includes them.

For missing files, a warning names them:

core-crm 1.0.0.12 starts at 26d70a74, before uat's baseline 9f8e7d6c, but 1 file changed since that baseline without changing since the artifact's start, so they are not in it and uat keeps its own copy: src/core-crm/main/default/classes/Greeter.cls. Build core-crm again to carry them.

This happens with an artifact built before the environment's baseline moved ahead of the artifact's start, or built by an sfp version that does not add these files. A new build of the package adds them. For an environment ahead of the artifact's start, the check also names the files it keeps that were deleted after its baseline; see Files deleted since an environment's baseline.

The check only warns. The deployment goes ahead.

After the deployment, sfp server decides whether the environment's baseline moves. It reads the deployed version's start commit and asks the repository's git provider whether the environment's baseline is an ancestor of it:

  • The artifact starts at or before the baseline: the baseline advances to the deployed commit.

  • Gap: the baseline stays where it is and is marked as held. The deployed version is recorded, and the baseline history gets an entry for the hold. The deployment log says so:

    Baseline for core-crm in prod held at b5457e4c: this artifact starts at 68e1501d, so the changes in between haven't reached prod. The next build of core-crm on main starts there while prod is one of its registered environments.
  • The commits can't be compared (they have diverged, the start commit is not known, or the provider does not answer): a baseline that is not held advances as before. A held baseline stays held.

The server makes this decision, so it applies to every deployment that records a baseline. Because the baseline stays behind, the next diff build on the branch starts at or before it, and its artifact carries the changes the previous one missed.

A hold ends with the first deployment whose artifact starts at or before the held baseline. It also ends when an owner edits the baseline, or adopts the org's commit as the baseline, at or after the held artifact's start. In that case the changes in between are not deployed by a later build either.

codev shows baseline gaps on a release candidate before it is released. See Baseline gaps.

Viewing and editing the baseline

The baseline for each package is shown in codev's Workspace Explorer on the web — select a package to see its fallback baseline, latest published version, and per-environment baselines, and which commit the next build will use.

For a diff package, an owner can override the baseline: edit the fallback baseline, or the baseline of an environment that has recorded a deployment, by entering the full commit SHA to compare against. An environment without a recorded deployment has no baseline to edit; it is listed as awaiting a first deployment. An owner can give it baselines from its org's artifact records instead; see Adopting the org's state as baseline. The commit must be on the branch; everything after it lands in the next diff build. A source, unlocked, or data package baseline is read-only in the UI — it is advanced by the pipeline and cannot be edited manually.

On this page