Patching Releases
Availability
✅
✅
Overview
The sfp repo:patch command enables you to apply a specific release (or multiple releases) to a different branch by replacing the source code of packages with their corresponding versions from built artifacts. This is particularly useful for:
Hotfix scenarios - Apply production fixes to development branches
Release synchronization - Sync release branches with specific versions
Rollback preparation - Create branches with previous release states
Environment alignment - Ensure branches match deployed environments
How It Works
The repo patch process:
Creates a temporary clone of your repository at the source branch
Creates a new target branch from the source
Fetches all artifacts specified in the release definition(s)
Replaces package directories with the exact code from the artifacts
Commits the changes to the target branch
Pushes the patched branch to the remote repository
Command Usage
Basic Usage
With NPM Registry
With Custom Script (Without NPM)
When artifacts are stored in a custom registry or storage system (not npm), you can use a custom script:
The custom script receives three parameters:
Package name
Version
Target directory
Example script (scripts/fetch-artifact.sh):
Multiple Release Definitions
Command Flags
-p, --releasedefinitions
Path to release definition YAML file(s). Can be specified multiple times
Yes
-s, --sourcebranchname
Name of the source branch on which the alignment needs to be applied
Yes
-t, --targetbranchname
Name of the target branch to be created after the alignment
Yes
-f, --scriptpath
Path to script that authenticates and downloads artifacts from the registry (mutually exclusive with --npm)
No
--npm
Download artifacts from a pre-authenticated private npm registry (mutually exclusive with --scriptpath)
No
--scope
User or organization scope of the NPM package (required when using --npm)
No
--npmrcpath
Path to .npmrc file for authentication. Defaults to home directory
No
--loglevel
Logging level (trace, debug, info, warn, error, fatal)
No
Use Cases
1. Hotfix Application
When a production hotfix needs to be applied back to development:
After patching, you can:
Review the changes
Create a pull request
Merge the hotfix back into development
2. Environment Synchronization
Ensure a branch matches exactly what's deployed in an environment:
3. Rollback Preparation
Create a branch with a previous release state for potential rollback:
4. Release Branch Creation
Create a release branch with specific package versions:
Integration with Release Workflow
The repo patch command fits into the release workflow at several points:
After Production Release
During Hotfix Process
Important Considerations
Package Structure
The command replaces entire package directories
Any local changes in the target branch packages will be overwritten
Non-package files (configs, scripts) are preserved from the source branch
Version Alignment
Ensures exact version alignment with released artifacts
Useful for maintaining version consistency across branches
Helps prevent version drift between environments
Git History
Creates a clean commit with all package changes
Preserves the relationship to the source branch
Makes it easy to track what release was applied
Troubleshooting
Artifacts Not Found
Package Not in Project
If a package exists in the release but not in the source branch:
The package will be added to the project
Update sfdx-project.json after patching if needed
Merge Conflicts
After patching, if merging causes conflicts:
The patched branch has the exact release state
Carefully review conflicts
Generally, prefer the patched version for package code
Preserve local changes for configuration files
Example Workflow
Here's a complete example of using repo patch in a release workflow:
This ensures that your development branch always contains the exact code that's running in production, preventing drift between environments.
Last updated