branch-port

Branch Port

Port a feature from a source branch to a target branch when rebase or merge will not apply cleanly. Understand the feature first, then re-implement it. Never paste source files over the target.

When NOT to use

• git cherry-pick <sha> applies cleanly: do that.
• Rebase has a few conflicts: resolve them. Do not re-architect.
• The branches share a recent ancestor (hours or days): use a plain merge.
• The feature is one or two commits: cherry-pick each.

Use this skill for long-lived divergence, major target refactors, or features that mix code the target still needs with code the target has made obsolete.

Rules (read first)

• Never run git checkout <source-branch> -- <file>. It discards the target's evolution.
• Never run git diff <source> | git apply across diverged branches.
• Halt at Phase 4 (Port Plan). Wait for user confirmation before you write code.
• If a conflict is ambiguous, stop and ask.
• Verify schema and migration changes against the target's schema state.
• If Phase 5 discovery invalidates the Port Plan, stop and re-plan. Do not push through a broken plan.
• Do not mark failing ported tests @skip or xfail to get green. Rewrite them for target conventions or report the failure to the user.
• Keep the port as one reviewable commit or a small focused series.

Phase 1: Context

git fetch --all --prune
export BASE=$(git merge-base <source> <target>)
git log --oneline "$BASE"..<source>

Ask the user only for missing information (source, target, scope). If the trigger message provided it, skip the question.

Detect overlap. Has any part of the feature already reached the target?

git range-diff "$BASE"..<source> "$BASE"..<target>

Read the output:

• =: identical patch on target. Skip.
• !: similar but different patch on target. Inspect manually. It could be a partial backport, a whitespace tweak, or a different implementation. Do not skip it blind.
• -: only on source. Port.
• +: only on target. Not relevant to the port.