Directory flag in project deploy start command does not respect source tracking

[ogardnercertinia]

Summary

Our project is so big that we have > 30 packageDirectories in our sfdx-project.json file to workaround the Metadata API limit.

To deploy to our scratch orgs, we have to manipulate the sfdx-project.json at run time so that only a single package directory is present in the sfdx-project.json at once . We do this via custom tooling and the result is that we deploy our package directories individually.

We were reading the Salesforce DX Project Configuration docs recently and noticed that it states:

To deploy packages sequentially, and in a specific order, use separate project deploy start commands in the desired order.

We presume this means we should use multiple sf project deploy start commands in conjunction with the -d flag.

When using sf project deploy start with -d, we've noticed that source tracking is not respected which means we are unable to remove our custom tooling and follow the guidance in the docs.

Steps To Reproduce

• Create a project with multiple directories under force-app e.g. force-app/directory1, force-app/directory2, and force-app/directory3.
• Add each of these directories as separate packageDirectories in the sfdx-project.json.
• Add some Apex classes to each of these sub-directories.
• Run sf project deploy start.
• Classes should be deployed successfully.
• Run sf project deploy start -d force-app/directory2 and observe that a full deploy of the directory is done rather than respecting source tracking.

Expected result

When running sf project deploy start -d force-app/directory2 in the last step, we'd expect the CLI to report that there are no changes to deploy.

Actual result

When running sf project deploy start -d force-app/directory2 in the last step, a full deploy of the directory is done.

Additional information

N/A

System Information

{
  "architecture": "darwin-arm64",
  "cliVersion": "@salesforce/cli/2.96.4",
  "nodeVersion": "node-v22.12.0",
  "osVersion": "Darwin 24.5.0",
  "rootPath": "/Users/ogardner/git/PSA/psenterprise/common/temp/node_modules/.pnpm/@[email protected]_@[email protected]_@[email protected][email protected]/node_modules/@salesforce/cli",
  "shell": "zsh",
  "pluginVersions": [
    "@oclif/plugin-autocomplete 3.2.31 (core)",
    "@oclif/plugin-commands 4.1.26 (core)",
    "@oclif/plugin-help 6.2.29 (core)",
    "@oclif/plugin-not-found 3.2.57 (core)",
    "@oclif/plugin-plugins 5.4.43 (core)",
    "@oclif/plugin-search 1.2.25 (core)",
    "@oclif/plugin-update 4.6.45 (core)",
    "@oclif/plugin-version 2.2.30 (core)",
    "@oclif/plugin-warn-if-update-available 3.1.42 (core)",
    "@oclif/plugin-which 3.2.37 (core)",
    "@salesforce/analytics 1.4.41 (link) /Users/ogardner/git/PSA/cpm/node_modules/@salesforce/analytics",
    "@salesforce/cli 2.96.4 (core)",
    "agent 1.23.2 (core)",
    "apex 3.6.19 (core)",
    "api 1.3.3 (core)",
    "auth 3.7.4 (core)",
    "community 3.3.28 (link) /Users/ogardner/git/PSA/cpm/node_modules/@salesforce/plugin-community",
    "data 4.0.42 (core)",
    "deploy-retrieve 3.22.27 (core)",
    "info 3.4.72 (core)",
    "lightning-dev 3.5.0 (user) published 38 days ago (Mon Jun 02 2025) (latest is 2.10.3)",
    "limits 3.3.58 (core)",
    "marketplace 1.3.8 (core)",
    "org 5.9.2 (core)",
    "packaging 2.18.0 (core)",
    "schema 3.3.69 (core)",
    "settings 2.4.33 (core)",
    "sobject 1.4.63 (core)",
    "telemetry 3.6.45 (core)",
    "templates 56.3.53 (core)",
    "trust 3.7.107 (core)",
    "user 3.6.27 (core)"
  ]
}

[github-actions[bot]]

Thank you for filing this issue. We appreciate your feedback and will review the issue as soon as possible. Remember, however, that GitHub isn't a mechanism for receiving support under any agreement or SLA. If you require immediate assistance, contact Salesforce Customer Support.

[WillieRuemmele]

hi @ogardnercertinia -

your presumption is correct, you'd do

sf project deploy start --source-dir force-app/directory1
sf project deploy start --source-dir force-app/directory2
sf project deploy start --source-dir force-app/directory3

it doesn't quite work like that though, when you specify what to deploy, via a flag, we'll deploy it, regardless of source tracking status... it's only when you DON'T specify a flag project deploy start where we'll calculate the differences and deploy.

If this is in a CI system, I'd recommend disabling source tracking, either when creating the org, or before deploying to it, to achieve better performance

[ogardnercertinia]

Thanks @WillieRuemmele.

Our use case is in CI. We have a system that creates scratch orgs and caches them future use. In our CI pipelines, we deploy to a cached scratch org so that we only deploy a diff of what has changed. Our project takes > 2 hours to deploy to from scratch since it's so big, so disabling source tracking isn't viable for us unfortunately.

As mentioned in my original post, we have built a custom CLI that manipulates the sfdx-project.json so that we can deploy package directories individually whilst respecting source tracking. Would it possible for my original post to be considered as a feature request please? Perhaps a new flag / env var could be added to respect source tracking whilst using the -d flag. Ideally, we want to remove our custom tooling and be as native as possible.

[ogardnercertinia]

@WillieRuemmele thanks for converting this to a discussion.

How do we get the ball rolling for this feature to be implemented into the cli?