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.

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 every environment that installs the package 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:

1. If no environment has installed the package, the fallback baseline is used.
2. If any registered environment has not yet recorded a deployment, the fallback baseline is used.
3. Once every environment has a deployment, the environment baseline furthest behind is used, so the diff covers everything not yet on every environment.

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.

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 a specific environment's baseline, by entering the full commit SHA to compare against. 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.