Git Rebase Patterns

Advanced rebase techniques for maintaining linear history, managing stacked PRs, and cleaning up commit history.

When to Use This Skill

Use this skill when... Use something else when...

Rebasing feature branches onto updated main Creating branches → git-branch-naming

Cleaning up commit history before PR Creating PRs → git-branch-pr-workflow

Managing stacked PRs (PR chains) Simple commits → git-commit-workflow

Converting merge-heavy branches to linear Basic git operations → git-cli-agentic

Linear History Basics

Trunk-Based Development

Feature branch lifecycle (keep short - max 2 days)

git switch main git pull origin main git switch -c feat/user-auth

Daily rebase to stay current

git switch main && git pull git switch feat/user-auth git rebase main

Interactive cleanup before PR

git rebase -i main

Squash, fixup, reword commits for clean history

Push and create PR

git push -u origin feat/user-auth

Squash Merge Strategy

Maintain linear main branch history:

Manual squash merge

git switch main git merge --squash feat/user-auth git commit -m "feat: add user authentication system

• Implement JWT token validation
• Add login/logout endpoints
• Create user session management

Closes #123"

Interactive Rebase Workflow

Clean up commits before sharing:

Rebase last 3 commits

git rebase -i HEAD~3

Common rebase commands:

pick = use commit as-is

squash = combine with previous commit

fixup = squash without editing message

reword = change commit message

drop = remove commit entirely

Example rebase todo list:

pick a1b2c3d feat: add login form fixup d4e5f6g fix typo in login form squash g7h8i9j add form validation reword j1k2l3m implement JWT tokens

Advanced Rebase Flags

Reapply Cherry-Picks (--reapply-cherry-picks )

Problem: After merging trunk into your feature branch multiple times (via git merge main ), you want to rebase onto fresh trunk. Default rebase behavior may create conflicts or duplicate commits.

Solution: --reapply-cherry-picks detects commits that were already applied via merge and drops the merge commits, keeping only your original changes.

Scenario: You merged main into your branch a few times

git log --oneline

abc123 Merge branch 'main' into feat/auth

def456 feat: add login endpoint

ghi789 Merge branch 'main' into feat/auth

jkl012 feat: add user validation

Rebase onto fresh main, dropping merge commits

git fetch origin git rebase --reapply-cherry-picks origin/main

Result: Clean linear history with just your feature commits

jkl012 feat: add user validation

def456 feat: add login endpoint

When to use:

• After merging trunk into your branch to resolve conflicts

• Converting a merge-heavy branch to linear history

• Before creating a PR to clean up integration merges

Update Refs (--update-refs )

Problem: With stacked PRs (PR chains), rebasing one branch requires manually rebasing all dependent branches. Moving commits between branches in the stack is painful.

Solution: --update-refs automatically updates all branches in the chain when you rebase. Combined with interactive rebase, you can reorganize commits across your entire PR stack in one operation.

Scenario: Stacked PRs

main <- feat/auth-base <- feat/auth-oauth <- feat/auth-refresh

Rebase the entire stack onto updated main

git switch feat/auth-refresh git rebase --update-refs main

All three branches (auth-base, auth-oauth, auth-refresh) are updated

No manual rebasing of each branch needed

Interactive rebase to move commits between branches

git rebase -i --update-refs main

In the editor, move commit lines around to reorganize the stack:

pick abc123 feat: add auth base # Will update feat/auth-base

pick def456 feat: add OAuth support # Will update feat/auth-oauth

pick ghi789 feat: add token refresh # Will update feat/auth-refresh

Stacked PR workflow with update-refs:

Create PR stack

git switch main git pull origin main

First PR: Base authentication

git switch -c feat/auth-base

... make commits ...

git push -u origin feat/auth-base

Second PR: OAuth (depends on first)

git switch -c feat/auth-oauth

... make commits ...

git push -u origin feat/auth-oauth

Third PR: Token refresh (depends on second)

git switch -c feat/auth-refresh

... make commits ...

git push -u origin feat/auth-refresh

Main updated - rebase entire stack

git fetch origin git switch feat/auth-refresh git rebase --update-refs origin/main

All branches rebased in one command

git push --force-with-lease origin feat/auth-base git push --force-with-lease origin feat/auth-oauth git push --force-with-lease origin feat/auth-refresh

When to use:

• Managing stacked PRs (PR chains with dependencies)

• Reorganizing commits across multiple branches

• Keeping branch hierarchies in sync during rebase

Explicit Base Control (--onto )

Problem: Git's automatic base detection can be ambiguous or incorrect. You want precise control over where commits are rebased.

Solution: --onto explicitly specifies the new base, bypassing Git's base detection heuristics.

Syntax: git rebase --onto <newbase> <upstream> <branch>

Translates to: Take commits from <upstream>..<branch> and put them onto <newbase>

Common pattern: Rebase last N commits onto a specific branch

git rebase --onto origin/develop HEAD~5

Takes your last 5 commits and puts them on top of origin/develop

Equivalent to: git rebase --onto origin/develop HEAD~5 HEAD

Example: Move feature commits from old base to new base

Scenario: You branched from develop, but should have branched from main

git switch feat/payment git rebase --onto main develop feat/payment

Takes commits from develop..feat/payment and moves them onto main

Example: Rebase specific commit range

Move commits from abc123 to def456 onto main

git rebase --onto main abc123^ def456

The ^ includes abc123 in the range

Example: Extract commits to new branch

You have commits on feat/auth that should be on separate branch

git switch -c feat/auth-ui feat/auth # Create new branch git rebase --onto main feat/auth~3 feat/auth-ui

Takes last 3 commits from feat/auth and puts them on main

Common --onto patterns:

Pattern Command Use Case

Last N commits on trunk git rebase --onto origin/main HEAD~N

Rebase recent work onto updated trunk

Change branch base git rebase --onto <new-base> <old-base>

Fix branch created from wrong base

Extract commit range git rebase --onto <target> <start>^ <end>

Move specific commits to new location

Interactive with onto git rebase -i --onto <base> HEAD~N

Clean up and rebase last N commits

When to use:

• When you don't trust Git's automatic base detection

• Rebasing a specific number of recent commits (HEAD~N pattern)

• Changing the base of a branch after it was created

• Extracting a subset of commits to a new location

Combining Advanced Flags

These flags work together for powerful workflows:

Rebase stacked PRs with cherry-pick detection

git rebase --reapply-cherry-picks --update-refs origin/main

Interactive rebase with explicit base and branch updates

git rebase -i --onto origin/main HEAD~10 --update-refs

Clean up merged history and update dependent branches

git rebase --reapply-cherry-picks --update-refs --onto origin/develop origin/main

Conflict Resolution

When rebase conflicts occur

git rebase main

Fix conflicts in editor

git add resolved-file.txt git rebase --continue

If rebase gets messy, abort and merge instead

git rebase --abort git merge main

Safe Force Pushing

Always use --force-with-lease to prevent overwriting others' work

git push --force-with-lease origin feat/branch-name

Never force push to main/shared branches

Use this alias for safety:

git config alias.pushf 'push --force-with-lease'

Quick Reference

Operation Command

Rebase onto main git rebase main

Interactive rebase git rebase -i HEAD~N

Rebase with cherry-pick cleanup git rebase --reapply-cherry-picks origin/main

Rebase stacked PRs git rebase --update-refs main

Rebase last N commits git rebase --onto origin/main HEAD~N

Change branch base git rebase --onto <new> <old>

Abort failed rebase git rebase --abort

Continue after conflict git rebase --continue

Skip problematic commit git rebase --skip

Troubleshooting

Rebase Conflicts Are Too Complex

Abort rebase and use merge instead

git rebase --abort git merge main

Branch Diverged from Remote

Pull with rebase to maintain linear history

git pull --rebase origin feat/branch-name

Or reset if local changes can be discarded

git fetch origin git reset --hard origin/feat/branch-name

Lost Commits After Rebase

Find lost commits in reflog

git reflog

Restore to previous state

git reset --hard HEAD@{N}