backporting.md

Creating a Backport Branch

This guide explains how to create a backport branch from a tag and apply commits from a feature branch—whether it's still open or already merged.

Step 1: Check Out the Tag and Create a Backport Branch

First, check out the tag you want to backport to and create a new branch:

git checkout <tag-name>
git checkout -b <tag-name>-backport-<feature-name>

For example, if you're backporting a feature called user-auth to version v1.2.0:

git checkout v1.2.0
git checkout -b v1.2.0-backport-user-auth

Step 2: Identify the Commits to Cherry-Pick

Case A: Branch Has NOT Been Merged Yet

If the feature branch hasn't been merged into the main branch (e.g., develop), it's straightforward:

git log --oneline --no-merges <feature-branch> ^develop

Then cherry-pick the commits:

git rev-list --reverse --no-merges <feature-branch> ^develop | xargs git cherry-pick -x

Recovering a Deleted Branch from a PR

If the original branch has been deleted but the PR is still available on GitHub, you can fetch it using the PR number:

git fetch origin refs/pull/<pr-number>/head:<local-branch-name>
git checkout <local-branch-name>

For example, to fetch PR #1234 into a local branch:

git fetch origin refs/pull/1234/head:pr-1234
git checkout pr-1234

Case B: Branch Has Already Been Merged

If the branch has already been merged, we need to find the merge commit and extract the commits from there.

1. Find the merge commit

Option A: If you know a commit SHA that belonged to the feature branch:

MERGE=$(git rev-list --merges --ancestry-path <known-commit>..develop | tail -1)

Option B: Search for the merge commit by PR number or branch name:

# Search by PR number
git log --merges --oneline develop | grep "#1234"

# - or -

# Search by branch name
git log --merges --oneline develop | grep "feature-name"

Then set the MERGE variable to the commit SHA you found:

MERGE=<merge-commit-sha>

2. List the commits (optional, for verification)

git log --cherry --reverse --no-merges --oneline $(git merge-base $MERGE^1 $MERGE^2)..$MERGE^2

3. Cherry-pick the commits

git rev-list --reverse --no-merges $(git merge-base $MERGE^1 $MERGE^2)..$MERGE^2 | xargs git cherry-pick -x

Step 3: Handle Conflicts

If you encounter conflicts during cherry-picking:

# Resolve conflicts in your editor, then:
git add <resolved-files>
git cherry-pick --continue

To abort if things go wrong:

git cherry-pick --abort

Step 4: Push the Backport Branch

Once all commits are applied:

git push origin <tag-name>-backport-<feature-name>

Quick Reference

Scenario	Command
Branch not merged	git log --oneline --no-merges <branch> ^develop
Branch already merged	git log --oneline --no-merges $(git merge-base $MERGE^1 $MERGE^2)..$MERGE^2
Fetch deleted branch from PR	git fetch origin refs/pull/<pr-number>/head:<local-branch>

---

Happy backporting! 🚀