sf-package-combiner


A Salesforce CLI plugin that merges multiple package.xml manifests into a single file—ideal for combining incremental manifests (e.g. from sfdx-git-delta) or multiple sources before deploy.

Table of Contents

- Quick start
- Why use this
- Command reference
- Usage details
- Manifest structure
- Example
- Invalid package.xml files
- Requirements
- Issues
- License

---

Quick start

``bash


Install (use a specific version in place of x.y.z)

sf plugins install sf-package-combiner@x.y.z

Combine two manifests into one

sf sfpc combine -f pack1.xml -f pack2.xml -c package.xml
`

You can mix files and directories: use -f for specific files and -d for directories that contain package.xml files.

---

Why use this

- Merge incremental manifests — Combine output from tools like sfdx-git-delta with other package.xml files before deploying.
- Single deploy manifest — One package.xml from many sources (scripts, manual lists, other tools).
- CI/CD friendly — Generate a combined manifest in pipelines and deploy with sf project deploy start -x package.xml.

---

Command reference

$3

Combine Salesforce manifest files into one package.xml.

`
USAGE
$ sf sfpc combine [-f ] [-d ] [-c ] [-v ] [-n] [--json]

FLAGS
-f, --package-file= Path to a package.xml file. Can be repeated.
-d, --directory= Path to a directory containing package.xml files. Can be repeated.
-c, --combined-package= Path for the output file. Default: package.xml
-v, --api-version= API version for the combined package (e.g. 62.0).
-n, --no-api-version Omit the element in the output.

GLOBAL FLAGS
--json Output as JSON.
`

Examples

`bash


Two files → package.xml

sf sfpc combine -f pack1.xml -f pack2.xml -c package.xml

Files + directory

sf sfpc combine -f pack1.xml -f pack2.xml -d "test/sample_dir" -c package.xml

Pin API version

sf sfpc combine -f pack1.xml -f pack2.xml -v "62.0" -c package.xml

No version in output

sf sfpc combine -f pack1.xml -f pack2.xml -n -c package.xml
`

---

Usage details

$3

- Metadata types — (type) values are normalized via Salesforce’s metadata registry (e.g. correct casing, deduped).
- Type order — CustomObject is always listed before any other types in the combined manifest; all other types are sorted alphabetically. This ordering avoids deployment issues when combining manifests (see scolladon/sfdx-git-delta#76).
- Members — values keep their original case (Salesforce is case-sensitive for these).
- API version — By default, the highest from the input manifests is used. If none have a version, it is omitted.
- Overrides: use -v to set a specific version, or -n to omit version entirely.

$3

Salesforce package.xml format:

- Root: Package with xmlns="http://soap.sforce.com/2006/04/metadata".
- Types: Each block has (API names) and (metadata type, e.g. ApexClass, CustomObject).
- Version (optional): for the Metadata API version.

---

Example

Input: package1.xml

`xml



MyApexClass
ApexClass

60.0

`

Input: package2.xml

`xml



MyTrigger
ApexTrigger

62.0

`

Command

`bash
sf sfpc combine -f "package1.xml" -f "package2.xml" -c "package.xml"
`

Output: package.xml

`xml



MyApexClass
ApexClass


MyTrigger
ApexTrigger

62.0

`

(Highest input version 62.0 is used.)

---

Invalid package.xml files

Files that don’t match the expected manifest structure or have no are skipped with a warning. When processing fails, the underlying error from @salesforce/source-deploy-retrieve (e.g. unknown metadata types not in the registry) is appended:

`
Warning: Invalid or empty package.xml: .\test\samples\invalid2.xml. [SDR] Missing metadata type definition in registry: CustomFields
`

> Note: A missing metadata type definition can also occur if the type is newer than the @salesforce/source-deploy-retrieve version bundled with this plugin. Upgrading the plugin may resolve the issue for newly released metadata types.

If every input is invalid or empty, the combined file will have no . To avoid deploying an empty package, check for before deploying:

`bash
sf sfpc combine -f "package/package.xml" -f "package.xml" -c "package.xml"
if grep -q '' ./package.xml; then
echo "---- Deploying added and modified metadata ----"
sf project deploy start -x package.xml
else
echo "---- No changes to deploy ----"
fi
`

---

Requirements

- Salesforce CLI (sf`)
- Node.js 20.x or later (for the plugin)

---

Issues

Bugs and feature requests: GitHub Issues.

---

License

MIT. See LICENSE in this repo.