Backport a bug fix to a release branch with git cherry-pick
Short answer: When a bug fix is merged into main but customers are running an older release, use git cherry-pick to copy just that fix onto the release branch. Check out the release branch, run git cherry-pick -x <commit>, test and tag a patch release. The -x option records which commit the fix came from, which makes later audits much easier. Cherry-pick small, self-contained commits; if a fix is tangled up with feature work, cherry-picking will drag in conflicts or half a feature.
Why release branches need this
Many software businesses keep more than one version alive. A mobile app has versions in the app stores and on phones that haven't updated. A self-hosted product has customers on last year's release. An agency maintains a client site on a stable branch while building the next version on main.
When a bug is found, the fix is usually written against main, where development happens. But you can't ship main to the customers on version 3.2, because it contains unfinished features. You need the fix, and only the fix, on the release/3.2 branch.
What cherry-pick does
git cherry-pick takes the changes introduced by one or more existing commits and applies them as new commits on your current branch. The new commit has the same changes and message but a different hash, because it sits on a different parent.
Git's documentation describes the -x option: it appends a line saying "(cherry picked from commit ...)" to the commit message. That one line is what lets anyone reading the release branch later trace each fix back to its original commit and pull request.
Step by step
- Find the fix on
main:git log --oneline mainand note the commit hash. If the fix spans several commits, note all of them in order. - Check out the release branch:
git switch release/3.2andgit pullto make sure it's current. - Create a branch for the backport if your team reviews changes through pull requests:
git switch -c backport/fix-receipt-total. - Cherry-pick:
git cherry-pick -x a1b2c3d. For several commits, list them oldest first. - Resolve conflicts if any. Edit the files,
git addthem, thengit cherry-pick --continue. If it's going badly,git cherry-pick --abortreturns you to where you started. - Build and test on the release branch. Code around the fix may have changed between versions, so a clean cherry-pick isn't proof that it works.
- Merge, tag and release a patch version, for example 3.2.1.
Fix forward, then backport
A reliable habit: always fix on main first, then cherry-pick back to release branches. The alternative, fixing on the release branch and forgetting to bring it forward, means the bug reappears in the next major version. If a fix truly has to be written on the release branch first, cherry-pick it forward to main straight away with the same -x note.
Make commits easy to cherry-pick
How you write fixes on main decides how painful backports will be:
- One fix per commit. Don't combine a bug fix with a refactor or a new feature.
- Keep fixes small. The fewer lines touched, the fewer conflicts on older code.
- Include the test in the same commit, so the backport carries its own proof.
- Label pull requests that need backporting, so they're not forgotten.
- Mind squash merges. If your host squashes pull requests into one commit on merge, that single commit is usually the cleanest thing to cherry-pick.
Cherry-picking merges
If the fix came in as a merge commit rather than a squashed one, Git needs to know which side to treat as the base. As with revert, the -m option names the parent number; -m 1 usually means "relative to the branch it was merged into". Often it's simpler to cherry-pick the individual commits from the feature branch instead.
When cherry-pick is the wrong tool
- Large or interlinked changes. If a fix depends on three earlier refactors, backporting it means backporting those too. Consider writing a smaller, separate fix for the old version.
- Regular syncing between branches. If you find yourself cherry-picking dozens of commits each week, a merge strategy or a different branching model may suit you better.
- Database migrations. Backported migrations must fit the old version's schema history. Check carefully that numbering and order won't clash when customers later upgrade.
Testing the backport properly
Run the release branch's own test suite, not just the new test, because older code may rely on behaviour the fix changes. If you have a staging environment for the release version, deploy the patch there and check the original bug report's steps. For mobile apps, test on the oldest operating system version that release supports.
Keeping track
For each patch release, keep a short list of the fixes it includes with links to their original pull requests. The -x lines make this easy to generate from history. Customers and support staff appreciate clear patch notes, and your team avoids shipping the same fix twice or missing one.
A worked example
Take a hypothetical Dublin restaurant software company whose tablet ordering app was on version 4.1 for most customers while main was heading towards 5.0. A rounding bug on printed receipts was fixed on main in a single commit with a test. A developer created a backport branch from release/4.1, ran git cherry-pick -x on the fix, resolved a small conflict in a file that had been renamed since, ran the receipt tests and opened a pull request. After review, the team tagged 4.1.3 and listed the fix in the patch notes with a link to the original change.
FAQ
Does cherry-pick move the commit?
No. It copies the changes into a new commit. The original stays on its branch.
Will cherry-picked commits cause duplicate changes when I merge later?
Git usually handles identical changes without conflict, but history will show both commits. The -x note helps explain why.
Can I cherry-pick from another repository?
Yes, if you fetch that repository as a remote first, though conflicts are more likely.
Is there a way to automate backports?
Some Git hosts and community tools can open backport pull requests automatically from a label. Check what your host supports.
If your team maintains several versions and backports have become a headache, tell us how you release and we'll help simplify it.