git-rebase

Git Rebase Assistant

Performs safe, effective rebases with intelligent conflict detection and resolution. The key differentiator is understanding the intent of both sides through commit message analysis before resolving any conflicts.

Core Principle: Intent Before Resolution

Never resolve a conflict mechanically. Before touching any conflict:

1. Understand what master/main changed and WHY
2. Understand what the feature branch changed and WHY
3. Only then decide how to combine the changes

Workflow Decision Tree

User request
    │
    ├─► "rebase", "update branch", "get latest main"
    │       └─► Full Rebase Workflow (below)
    │
    ├─► Conflict during rebase
    │       └─► Conflict Resolution Workflow (below)
    │
    └─► "squash", "clean up commits", "interactive rebase"
            └─► Interactive Rebase Workflow (below)

Full Rebase Workflow

Step 1: Validate Prerequisites

git status                    # MUST be clean
git fetch origin              # Get latest
git branch --show-current     # Confirm correct branch

Stop if: uncommitted changes exist, wrong branch, or detached HEAD.

Step 2: Create Safety Backup

git branch backup/$(git branch --show-current)-$(date +%Y%m%d-%H%M%S)

Step 3: Gather Full Context (MANDATORY)

Run scripts/rebase-context.sh or manually gather:

# What's NEW in main since we branched?
git log --oneline HEAD..origin/main

# What are OUR commits?
git log --oneline origin/main..HEAD

# Files likely to conflict
git diff --name-only origin/main...HEAD

# Preview specific file changes on BOTH sides
git log -p origin/main..HEAD -- <file>   # Our changes to file
git log -p HEAD..origin/main -- <file>   # Their changes to file

Read the commit messages. Understand:

• What problems were solved in main?
• What new patterns/APIs were introduced?
• What assumptions might have changed?

Step 4: Execute Rebase

git rebase origin/main           # Standard
git rebase -i origin/main        # Interactive (for squashing/reordering)

Step 5: Handle Conflicts

See Conflict Resolution Workflow below.

Step 6: Verify and Push

# Run tests/build
npm test        # or go test ./... or appropriate test command

# Verify log looks correct
git log --oneline -10

# Safe force push
git push --force-with-lease

Step 7: Clean Up

git branch -d backup/<branch-name>-*

Conflict Resolution Workflow

Before Resolving ANY Conflict

Read references/conflict-analysis.md for detailed guidance.

For each conflicted file:

# 1. See the conflict
git diff --name-only --diff-filter=U    # List conflicted files

# 2. Understand THEIR side (what main added)
git log -p ORIG_HEAD..origin/main -- <conflicted-file>

# 3. Understand OUR side (what we're replaying)
git log -p origin/main..ORIG_HEAD -- <conflicted-file>

Resolution Strategies

The Ours/Theirs Trap

Read references/ours-vs-theirs.md - this is critical.

During rebase, the meaning is REVERSED from merge:

• --ours = the base branch (main)
• --theirs = your commits being replayed

# Accept main's version (during rebase)
git checkout --ours <file>

# Accept our feature branch version (during rebase)
git checkout --theirs <file>

After Each Resolution

git add <resolved-files>
git rebase --continue

# Run tests after EACH commit if possible
git rebase -i --exec "npm test" origin/main

Interactive Rebase Workflow

For squashing, reordering, or editing commits:

git rebase -i origin/main     # Rebase onto main
git rebase -i HEAD~5          # Edit last 5 commits

Interactive Commands

Squashing Best Practice

When squashing multiple commits:

1. Read ALL commit messages being combined
2. Craft a new message that captures the full intent
3. Don't just keep the first message if others add context

Recovery

# Abort current rebase
git rebase --abort

# Restore from backup
git reset --hard backup/<branch-name>-*

# Find lost commits via reflog
git reflog
git reset --hard HEAD@{n}

Advanced Techniques

Autosquash Workflow

# During development, create fixup commits
git commit --fixup=<commit-hash>

# Later, autosquash during rebase
git rebase -i --autosquash origin/main

Run Tests After Each Commit

git rebase -i --exec "npm test" origin/main

Preserve Merge Commits

git rebase --rebase-merges origin/main

Enable Rerere (Reuse Recorded Resolution)

git config --global rerere.enabled true

Git remembers conflict resolutions and auto-applies them next time.

Resources

scripts/

• rebase-context.sh - Gathers context from both sides before rebase

references/

• conflict-analysis.md - Deep dive on understanding conflict intent
• ours-vs-theirs.md - Explains the confusing reversal during rebase