> 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/concepts/supported-package-types/diff-package.md). # Diff Package A diff package is a variant of a '[source package](https://docs.flxbl.io/flxbl/sfp/concepts/supported-package-types/source-packages)' 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](https://help.salesforce.com/s/articleView?id=sf.changesets.htm\&type=5) 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. {% hint style="danger" %} Diff packages don't work with scratch orgs. They should be used with sandboxes only. {% endhint %} {% hint style="warning" %} 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. {% endhint %} ## 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](https://docs.flxbl.io/flxbl/codev/development/workspace-explorer-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. --- # 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/concepts/supported-package-types/diff-package.md?ask=&goal= ``` `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.