Workflows
Backporting with Cherry-pick
Backport precise fixes onto maintenance branches without merging an entire feature branch.
- Teams turning commands into repeatable routines
- Readers who need sequencing, branch, and sync discipline
- Basic understanding of fetch, pull, push, and branches
- A sense of how and why branches diverge
- Copying a workflow without checking branch state
- Choosing the wrong integration path on shared branches
Where this workflow fits
main (trunk)
main
ABC
feature
BDE
release/2.x (maintenance)
release
AR1E'
When a fix already landed on main but an older maintenance line still needs it, the usual problem is:
"I need this one repair, not the whole branch history."
That is when cherry-pick is a strong fit.
Suggested sequence
1. identify the exact commit
git log --oneline --decorate main
The first risk in backporting is not conflict. It is choosing the wrong commit.
2. switch to the maintenance branch and cherry-pick
git switch release/2.3
git cherry-pick <commit-sha>
3. validate the resulting diff and tests
git show --stat --oneline HEAD
git diff --stat origin/release/2.3...
Do not stop at "the command succeeded." Confirm the resulting change still makes sense on the older branch.
Why this order is safer
Backporting works best when the order is fixed:
- confirm the right commit
- confirm the target maintenance branch
- confirm the fix still stands alone after the pick
Common mistakes
- cherry-picking before checking dependency commits
- backporting multiple commits without thinking through order
- assuming a successful cherry-pick means the fix is release-ready
Special cases
- if the fix depends on earlier refactors, a single cherry-pick may not be enough
- if the old branch has different config or schema expectations, validate in branch context
- if multiple maintenance lines need the same repair, verify one branch before repeating the flow