Use Branches in Unlocked Packaging

To identify which branch in your SCS a package version is based on, tag your package version with a branch name using --branch attribute in this Salesforce CLI command.

sf package version create --branch featureA

You can specify any alphanumeric value up to 240 characters as the branch name.

You can also specify the branch name in the package directories section of the sfdx-project.json file.

1"packageDirectories": [
2     {
3        "path": "util",
4        "default": true,
5        "package": "pkgA",
6        "versionName": "Spring ‘21",
7        "versionNumber": "4.7.0.NEXT",
8        "branch": "featureA"
9     }]

When you specify a branch, the package alias for that package version is automatically appended with the branch name. You can view the package alias in the sfdx.project.json file.

1"packageAliases": {
2    "pkgA@1.0.0.4-featureA":"04tB0000000IB1EIAW"}

Keep in mind that version numbers increment within each branch, and not across branches. For example, you could have two or more beta package versions with the version number 1.3.0.1.

Although more than one beta package version can have the same version number, there can be only one promoted and released package version for a given major.minor.patch package version.

Package Dependencies and Branches

By default, your package can have dependencies on other packages in the same branch. For package dependencies based on packages in other branches, explicitly set the branch attribute in the sfdx.project.json file.

1"dependencies": [
2    {
3    "package": "pkgB",
4    "versionNumber": "1.3.0.LATEST",
5    "branch": "featureC"
6}]

1"dependencies": [
2    {
3    "package": "pkgB",
4    "versionNumber": "2.1.0.RELEASED"
5}]

1"dependencies": [
2     {
3    "package": "pkgB",
4    "versionNumber": "1.3.0.LATEST",
5    "branch": ""
6}]

1"dependencies": [
2     {
3    "package": "pkgB@2.1.0-1-featureC"
4}]