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.

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

Quick start

# Install (use a specific version in place of x.y.z)
sf plugins install [email protected]

# 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

sf sfpc combine

Combine Salesforce manifest files into one package.xml.

USAGE
  $ sf sfpc combine [-f <value>] [-d <value>] [-c <value>] [-v <value>] [-n] [--json]

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

GLOBAL FLAGS
  --json  Output as JSON.

Examples

# 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

How it works

• Metadata types — <name> (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 — <members> values keep their original case (Salesforce is case-sensitive for these).
• API version — By default, the highest <version> from the input manifests is used. If none have a version, it is omitted.
• Overrides: use -v <version> to set a specific version, or -n to omit version entirely.

Manifest structure

Salesforce package.xml format:

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

Example

Input: package1.xml

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>MyApexClass</members>
    <name>ApexClass</name>
  </types>
  <version>60.0</version>
</Package>

Input: package2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>MyTrigger</members>
    <name>ApexTrigger</name>
  </types>
  <version>62.0</version>
</Package>

Command

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

Output: package.xml

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>MyApexClass</members>
    <name>ApexClass</name>
  </types>
  <types>
    <members>MyTrigger</members>
    <name>ApexTrigger</name>
  </types>
  <version>62.0</version>
</Package>

(Highest input version 62.0 is used.)

Invalid package.xml files

Files that don’t match the expected manifest structure or have no <types> 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 <types>. To avoid deploying an empty package, check for <types> before deploying:

sf sfpc combine -f "package/package.xml" -f "package.xml" -c "package.xml"
if grep -q '<types>' ./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.