rebase-branch

Rebase Branch

Guides safe rebasing of feature branches with proper conflict resolution and post-rebase verification.

Default branch resolution: when the user doesn't name a target branch, read repo.default_branch from .genvid-agent.json; if absent, fall back to git symbolic-ref --short refs/remotes/origin/HEAD.

When NOT to Use

Stacked branches after a parent was squash-merged — use /genvid-dev:rebase-stack instead. If the user says "branch X was merged", that's a stacked-branch scenario requiring git rebase --onto, not a simple rebase or squash. Using this skill's squash approach re-introduces already-merged commits and causes conflicts.

Pre-Rebase Checklist

1. Understand the branch's intent — what is it trying to achieve, and which files did it add, modify, or delete?
2. Analyze the target branch:

   git fetch origin <target-branch>
   git diff origin/<default-branch>..origin/<target-branch> --stat
   

   Look for overlapping files and modify/delete patterns.
3. Identify potential conflicts — files modified by both branches, modify/delete conflicts, and whether the two branches achieve similar goals differently.

Squashing (Recommended, Requires Confirmation)

Squashing before rebasing simplifies conflict resolution by reducing the number of commits to replay. Always ask the user before squashing — they may have reasons to preserve individual commits.

Why squash first: fewer commits → fewer conflict points → easier to verify the final result.

Ask: "Would you like me to squash the commits before rebasing? This simplifies conflict resolution but combines all changes into one commit."

If approved:

Critical: squash onto the OLD merge-base, not the new target. Using git reset --soft origin/<target> captures the full diff against the new target, which silently re-introduces any changes that the target branch reverted.

git log --oneline origin/<default-branch>..HEAD  # commits to be squashed

# Find the OLD merge-base (where the branch diverged)
OLD_BASE=$(git merge-base HEAD origin/<target-branch>)

# Squash onto the old base — preserves the branch's actual delta
git reset --soft "$OLD_BASE"
git commit -m "<commit message following project's CLAUDE.md format>"

# Then rebase the squashed commit onto the new target
git rebase origin/<target-branch>

Rebase Process

git fetch origin <target-branch>
git rebase origin/<target-branch>

Resolving Conflicts

For each conflict, ask: "Which approach achieves the branch's intended outcome?"

Content conflicts (both modified): review both versions; keep changes that align with the branch's intent; incorporate target-branch improvements where appropriate.

Modify/delete conflicts:

• If the branch deleted a file the target modified — ask whether the branch's approach makes the file unnecessary. If yes: git rm <file>. If no: git checkout --ours <file> and integrate changes.
• If the branch modified a file the target deleted — ask whether the change is still needed given the target's approach. Decide whether to recreate the file or adapt.

Generated file conflicts (anything regenerated by a build step): accept either side to clear the conflict and regenerate after the rebase completes. git checkout --theirs <file> to accept the target-branch version.

After resolving each file:

git add <resolved-files>
git status              # verify all conflicts resolved
git rebase --continue

Post-Rebase Verification

After the rebase completes, check for stale references:

1. Search for references to removed functionality:

   grep -r "deleted-feature-name" --include="*.md" --include="*.ts" --include="*.json"
   

2. Check ignore files — .gitignore, .claudeignore, etc. — for entries pointing at files that no longer exist.
3. Check documentation — does it still reference removed scripts or commands?
4. Run the project's validate command (from .genvid-agent.json commands.validate) if defined. If not, run the project's test/lint commands directly.
5. Fix stale references and amend:

   git add <fixed-files>
   git commit --amend --no-edit
   

Common Mistakes

Mistake	Fix
Squashing onto the new target	Always squash onto the OLD merge-base first
Losing sight of intent	Achieve the branch's goal, don't just "merge code correctly"
Preserving deleted functionality	If the branch deleted something, ensure it stays deleted
Missing stale references	Conflicts only catch overlapping changes, not references elsewhere
Forgetting ignore files	.gitignore and friends often need cleanup

Recovery

git rebase --abort   # abandon and return to pre-rebase state
git reflog           # find previous commit if needed