Git Rebase Patterns

Git Rebase Patterns

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

When to Use This Skill

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.

--update-refs is local-only: it moves the branches but leaves the PRs, their bases, and the force-pushes to you. For a stack registered with GitHub, gh stack rebase / gh stack sync do the cascade and the push and PR update — see git-plugin:git-stacked-prs.

# 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:

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

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}