Choosing a package directory for new components in an SFDX project

If your SFDX project uses multiple package directories to organize your metadata into logical groupings, Gearset allows you to choose which package directory brand new components are committed to, right from the deployment summary page.

Why this matters

Splitting metadata across multiple package directories is a common way for teams to get clear ownership over different pieces of metadata and avoid conflicts - it's one of the main benefits teams look for when they're considering unlocked packages.

Previously, Gearset would always commit new components to your default package directory (the one marked "default": true in your sfdx-project.json), meaning you'd have to manually move files around in your repo afterwards if you wanted them somewhere else.

Now, users can can pick the right package directory as part of their deployment.

What counts as a "new component"

This choice applies to components that don't already exist anywhere in your target repository. For example, a brand new Apex class or Lightning Web Component (LWC).

It does not change how Gearset handles:

Changed or deleted items - these are always updated in their existing package directory.
New subcomponents on existing components (e.g. a new Custom field on a Custom object that already exists in your repo) - these always get deployed into the same package directory as their parent object.

For more detail on those rules, refer to our article on structuring your source control repository.

How to choose a package directory

On Compare and deploy page - compare and select the changes you want to commit, as normal.
On the deployment summary page, if your project has multiple package directories and your deployment includes new components, you'll see an option to choose which package directory to commit them to:
Select the package directory you'd like to use, then continue with your commit as usual.

Limitations and things to keep in mind

This is a per-deployment (per-commit) setting, meaning it applies to all new components in your deployment.
It isn't possible to deploy new components to different package directories within the same deployment. If you need new components split across different package directories, commit them separately.
If your project only has a single package directory, or your deployment doesn't include any new components, you won't see this option — Gearset will use the existing default behaviour.

FAQs

Does this setting apply to the whole deployment, or can I choose per component?

It's a per-deployment (per-commit) setting, meaning the package directory you choose applies to all new components included in that deployment.

Can I deploy new components to different package directories within the same deployment?

No. If you need new components to end up in different package directories, you'll need to commit them separately, selecting the appropriate package directory each time.

Why don't I see the option to choose a package directory?

You'll only see this option if your project has multiple package directories and your deployment includes at least one new component.

If your project has a single package directory, or your deployment doesn't include any new components, Gearset will use the existing default behaviour.

Summary table

Below table summarizes the default behaviors in Gearset applied when you commit to an SFDX project with multiple package directories.

Change type	Example	Gearset's deployment behavior / options
New components	A new Apex class	Default package directory (defined in sfdx-project.json), or user selects a package directory (when using our new feature)
Changed or deleted items	An existing Custom field is modified, or deleted	Update in its existing package directory
New subcomponents on existing objects	A new Custom field on a Custom object that already exists in the repo	Deployed to the same package directory as the parent object