Git Rebase

Git Rebase with Intelligent Conflict Resolution

Quick Start

For most rebases with multiple commits, use the squash-first strategy to resolve conflicts only once:

# Step 1: Backup current state
bash scripts/pre-rebase-backup.sh

# Step 2: Squash commits (interactive rebase on current branch)
git rebase -i $(git merge-base HEAD origin/main)

# Step 3: Rebase onto target
git rebase origin/main

# Step 4: If conflicts, resolve them once (see workflow below)
# Then continue: git rebase --continue

# Step 5: Force push safely
git push origin $(git rev-parse --abbrev-ref HEAD) --force-with-lease

This approach resolves conflicts once instead of per-commit, saving time and mental overhead.

Core Workflow: Conflict Analysis & Resolution

Copy this checklist and mark progress:

Rebase Workflow:
- [ ] Step 1: Create safety backup
- [ ] Step 2: Fetch latest from target branch
- [ ] Step 3: Analyze conflict scope
- [ ] Step 4: Choose resolution strategy
- [ ] Step 5: Apply conflict resolutions
- [ ] Step 6: Validate merged code
- [ ] Step 7: Run tests
- [ ] Step 8: Force push safely

Step 1: Create Safety Backup

ALWAYS do this first. If rebase goes wrong, you can recover:

# Use the bundled script
bash scripts/pre-rebase-backup.sh

# Or manually create timestamped backup branch
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
git branch backup-rebase-$TIMESTAMP

# Alternative: Create temporary ref to your current commit
git reflog  # Note your current HEAD SHA for manual recovery

This costs nothing and saves hours of work if something goes wrong.

Step 2: Fetch Latest Changes

Ensure you have the most recent remote state:

# Fetch without modifying local branches
git fetch origin

# View the divergence
git log --oneline origin/main..HEAD  # Your commits
git log --oneline HEAD..origin/main  # New commits on main

Understand how many commits you're rebasing and how much main has changed.

Step 3: Analyze Conflict Scope

Before starting the rebase, predict conflicts:

# See which files you changed
git diff --name-only origin/main...HEAD

# See which files main changed
git diff --name-only origin/main HEAD

# Likely conflict areas: files changed in both

Key insight: If you changed auth.ts and so did main, you WILL get conflicts in auth.ts.

Anticipating conflicts helps you understand how to resolve them.

Step 4: Choose Resolution Strategy

For detailed strategy comparison and decision matrix, see references/strategies.md.

Strategy A: Squash First (Recommended for 3+ commits)

When to use: Multiple feature commits with many conflicts expected

Why: Reduces conflicts to one resolution phase instead of per-commit

# Interactive rebase on current branch first
git rebase -i $(git merge-base HEAD origin/main)

# In editor, change all "pick" to "squash" (or 's') except first commit
# Save and exit - commits are squashed into one
# Edit commit message to describe the entire feature

# Now rebase the squashed commit
git rebase origin/main

# Resolve conflicts once, then git rebase --continue

Tradeoffs: Lose individual commit history, but simpler conflict resolution

Strategy B: Interactive Rebase with Conflict Awareness

When to use: 1-2 commits, clean history, or complex per-commit logic

git rebase -i origin/main

# In editor, you can:
# - Reorder commits to isolate conflict-prone ones
# - Drop commits that are already in main (git detects this)
# - Combine related commits before rebasing

# Save and exit - rebase proceeds, stopping at conflicts

Tradeoffs: More control, but more conflict-resolution iterations

Strategy C: Simple Linear Rebase (Fastest, Auto-Resolution)

When to use: Simple cases, no critical decisions, or in automated pipelines

# Rebase all commits at once
git rebase origin/main

# If no conflicts, done
# If conflicts, you resolve each one

Warning: Not recommended for complex scenarios. Use Strategies A or B instead.

Step 5: Apply Conflict Resolutions

When git rebase pauses with conflicts, use the analysis script:

# Analyze conflicts
bash scripts/analyze-conflicts.sh

# See which files conflict
git status

# For each conflicted file:
# - RECOMMENDED: Use merge tool for visual clarity
git mergetool --no-prompt

# - ALTERNATIVE: Manual edit in your editor
# Search for conflict markers: <<<<<<, ======, >>>>>>

Conflict Marker Anatomy

<<<<<<< HEAD
// Your current feature code
function authenticate(token) {
  validateToken(token);
  return true;
}
=======
// Main branch code (incoming)
function authenticate(token) {
  if (!token) throw new Error("No token");
  validateToken(token);
  setSession(token);
  return true;
}
>>>>>>> origin/main

Decision framework (before deleting markers):

1. Can you keep both? YES → Merge them intelligently

   function authenticate(token) {
     if (!token) throw new Error("No token"); // Keep main's validation
     validateToken(token);
     setSession(token); // Keep main's session setup
     return true; // Keep feature's return
   }

2. Conflicting logic? Understand WHY they differ, then decide

• Did main add critical security checks? → Keep main's version
• Did your feature add essential functionality? → Keep feature's version
• Are they trying to do different things? → Combine intentionally

3. Lost features? NEVER let a feature silently disappear

• If you added authentication logic, ensure it's in final version
• If main improved database access, ensure that's preserved

For detailed resolution patterns, see references/resolution-patterns.md.

Key Resolution Principles

✅ DO:

• Keep both versions' important functionality when possible
• Use the merge tool for visual representation
• Add comments explaining merged conflicts: // Merged from both versions: main's validation + feature's session setup
• Test each file after resolution

❌ DON'T:

• Mindlessly pick one version without understanding both
• Delete conflict markers without understanding the conflict
• Keep duplicate code - merge intelligently
• Skip testing before continuing

Step 6: Validate Merged Code

After resolving conflicts, validate the merged code:

# Use the validation script
bash scripts/validate-merge.sh

# Manual checks:
# 1. Check syntax
npm run lint  # or eslint, pylint, etc.

# 2. Check types (if TypeScript)
npm run type-check  # or tsc --noEmit

# 3. Spot-check key files
git diff HEAD origin/main -- <conflicted-file>

# If validation fails:
# 1. Fix the issue in the file
# 2. git add <file>
# 3. git rebase --continue

Important: Validation catches mistakes BEFORE you commit them.

Step 7: Run Tests

This is your safety net:

# Run full test suite
npm test

# Or specific tests for changed areas
npm test -- --testPathPattern=auth  # If auth.ts was changed

# If tests fail:
# 1. Understand what broke
# 2. Fix in the files
# 3. git add <files>
# 4. git rebase --continue

Rule: Never force-push code that fails tests.

Step 8: Force Push Safely

Use --force-with-lease instead of --force. It protects against accidentally overwriting others' work:

# SAFE: Protects others' commits
git push origin $(git rev-parse --abbrev-ref HEAD) --force-with-lease

# UNSAFE: Can overwrite others' work
git push origin your-branch -f  # Don't do this

# If force-with-lease fails:
# Someone else pushed to your branch
# Coordinate with them before forcing

Common Scenarios & Strategies

Scenario 1: Many Small Conflicts Across 5+ Commits

Use: Squash-first strategy

git rebase -i $(git merge-base HEAD origin/main)
# Mark all but first commit as 's' (squash)
# Save - commits squash into one

git rebase origin/main
# Resolve conflicts once
git rebase --continue

# Only one conflict-resolution phase!

Why: Each commit might have conflicts. Squashing before rebasing means one pass.

Scenario 2: One Specific Commit Has Conflicts

Use: Target that commit with interactive rebase

git rebase -i origin/main

# In editor, move the problematic commit to the end
# Save - rebase proceeds, stopping at that commit

# When it stops, you know exactly which commit conflicts
git status  # See what changed in this commit

# Resolve, then continue
git rebase --continue

Why: Isolating the commit helps you understand what it's trying to do.

Scenario 3: Conflicts Keep Repeating (Same File, Different Commits)

Use: Git rerere (reuse recorded resolution)

# Enable rerere globally (one-time setup)
git config --global rerere.enabled true

# Now when you hit the same conflict in a second commit,
# Git automatically applies the first commit's resolution

git rebase origin/main

# Git remembers your first conflict resolution
# and replays it automatically for similar conflicts

Why: When rebasing and hitting the same file repeatedly, rerere saves manual work.

Scenario 4: Rebase Conflicts Are Too Complex

Emergency escape plan:

# Abort the rebase - return to original state
git rebase --abort

# Fall back to merge (safer for complex scenarios)
git merge origin/main

# Or try a different approach:
# - Squash your entire feature branch first
# - Cherry-pick main's critical changes selectively

Important: It's okay to abort and rethink. Better than a broken rebase.

Bundled Scripts

This skill includes helper scripts in scripts/:

• `pre-rebase-backup.sh`: Creates a safety backup before rebasing
• `analyze-conflicts.sh`: Analyzes current conflicts and provides detailed information
• `validate-merge.sh`: Validates that merge/rebase is clean and ready for testing

Run scripts with bash scripts/<script-name>.sh.

Reference Files

For detailed information on specific topics:

• Strategies: references/strategies.md - Complete strategy comparison and decision matrix
• Resolution Patterns: references/resolution-patterns.md - Common conflict resolution patterns and heuristics
• Troubleshooting: references/troubleshooting.md - Solutions to common rebase problems
• Automation: references/automation.md - Automated conflict resolution for CI/CD
• Scripts & Tools: references/scripts-tools.md - Additional git commands and tool usage

Checklist: Before You Commit to Rebasing

• [ ] Understand why you're rebasing (cleaner history, syncing with main, etc.)
• [ ] Backup your current branch: bash scripts/pre-rebase-backup.sh
• [ ] Run tests on current branch - they should pass
• [ ] Fetch latest: git fetch origin
• [ ] Understand what you'll be rebasing (5 commits? 50?)
• [ ] Understand main's recent changes (1 commit? Major refactor?)
• [ ] Choose your strategy (see references/strategies.md)
• [ ] Have your merge tool ready (if using GUI)
• [ ] Block 30 mins - don't rush conflict resolution
• [ ] Have tests ready to run after rebase

When NOT to Rebase

• Shared branches (use merge instead: git merge origin/main)
• Critical production code without comprehensive tests
• When multiple people are pushing to the same branch
• If you don't understand the conflicts you're seeing

Default to merge if uncertain. Merge is safer for collaborative work.

Use rebase when: Solo feature branch, clean history matters, no shared dependencies.

Summary: The Rebase Philosophy

Rebasing is a tool for creating clean, linear commit history. Used well, it makes debugging and code review easier. Used poorly, it loses work.

The key principle: Understand every conflict before resolving it. Don't automate away the thinking.

With this Skill, you can rebase with confidence, understanding each decision and protecting your code throughout the process.

Advanced: Automated Conflict Resolution

When You KNOW the Resolution Strategy Upfront

For CI/CD pipelines or automated rebases:

# Accept ALL incoming changes (risky - verify first!)
git rebase -X theirs origin/main

# Accept ALL your changes (also risky!)
git rebase -X ours origin/main

# Three-way recursive merge (safest auto-strategy)
git rebase -Xrecursive origin/main

⚠️ WARNING: Only use automated strategies when:

1. You understand the consequences 2. You have comprehensive tests 3. Changes are non-critical 4. You've verified the strategy is correct for this scenario

For production code: Use manual resolution from the core workflow in SKILL.md.

Resolution Patterns & Heuristics

Pattern 1: Main Added New Validation/Security

Indicator: Main's version has if checks or validations you don't have

Action: Keep main's validation, integrate with your feature

// WRONG: Removing main's validation
function authenticate(token) {
  validateToken(token); // Lost: if (!token) check
  return true;
}

// RIGHT: Keeping all validations
function authenticate(token) {
  if (!token) throw new Error("No token"); // main's addition
  validateToken(token); // your code
  return true;
}

Pattern 2: Your Feature Added Critical Functionality

Indicator: Main's version doesn't have your key feature additions

Action: Ensure your additions are preserved

// Before conflict
export class AuthService {
  validate() {}
  // Your addition
  setUserContext(user) {}
}

// After resolving (keep your addition)
export class AuthService {
  validate() {} // main's version
  setUserContext(user) {} // your addition (don't lose this!)
}

Pattern 3: Both Changed Same Line (Logic Conflict)

Indicator: Same line different in both versions

Action: Understand why, choose based on correctness

// YOU: Changed return value
return new User(profile);

// MAIN: Changed return statement entirely
return User.fromProfile(profile);

// DECISION: What's the actual implementation?
// Check User class for which method exists
// Pick the one that matches current API

Pattern 4: Main Deleted Code You Still Need

Indicator: Code block exists in your branch, missing in main

Action: Keep your code - main might have deleted prematurely

// Main deleted some logging
// You kept it in your feature
// DECISION: If logging is useful, keep it
// If it was debug code, you can delete it too

// Usually: Keep your feature code + main's latest

Scripts & Tools Reference

bash: Analyze Current Conflicts

# See all conflicts at a glance
git diff --name-only --diff-filter=U

# Count conflicts
git diff --name-only --diff-filter=U | wc -l

# Show conflicts with context
git status | grep 'both modified'

bash: Verify No Conflict Markers Remain

# Check for leftover conflict markers
git grep -l '<<<<<<'

# If any files show up, you missed editing them
git add <missing-file>
git rebase --continue

bash: Compare Your vs Incoming Changes

# See only YOUR changes in this conflict
git show :1:<filename>  # Base version
git show :2:<filename>  # Your version
git show :3:<filename>  # Their version

# Compare two versions:
git show :2:<filename> > yours.txt
git show :3:<filename> > theirs.txt
diff yours.txt theirs.txt

Using Bundled Scripts

This skill includes helper scripts in scripts/:

• `pre-rebase-backup.sh`: Creates a safety backup before rebasing
• `analyze-conflicts.sh`: Analyzes current conflicts and provides detailed information
• `validate-merge.sh`: Validates that merge/rebase is clean and ready for testing

See SKILL.md for usage instructions.

Conflict Resolution Strategies Reference

Strategy Decision Matrix

Choose your strategy based on your situation:

---

Deep Dive: Each Strategy

1. Squash First (Recommended)

How it works:

# Squash all commits into one
git rebase -i origin/main  # Keeps your branch's history intact
# Mark commits as 's' (squash) to combine them
# Then rebase once against main

When to use:

• 3+ commits to rebase
• Multiple files changed
• Conflicts expected
• Want clean commit history on main

Advantages:

• ✅ Resolve conflicts ONCE (not per-commit)
• ✅ Final code is one clean commit
• ✅ Faster for many commits
• ✅ Easy to understand final state

Disadvantages:

• ❌ Lose intermediate commit history
• ❌ Can't debug individual commits later
• ❌ Harder to bisect if bug is introduced

Example:

$ git rebase -i $(git merge-base HEAD origin/main)

# Editor shows:
pick a1b2c3d feat: add authentication
pick d4e5f6g fix: handle edge case
pick h7i8j9k chore: update dependencies

# Change to:
pick a1b2c3d feat: add authentication
s d4e5f6g fix: handle edge case
s h7i8j9k chore: update dependencies

# Save - commits squash into one
# Write new commit message describing entire feature

$ git rebase origin/main
# Resolve conflicts once
$ git rebase --continue
$ git push origin feature-branch --force-with-lease

---

2. Interactive Rebase (Full Control)

How it works:

git rebase -i origin/main
# Reorder, edit, squash individual commits before rebasing

When to use:

• Want to keep some commits, squash others
• Need to reorder commits strategically
• Want to reword commit messages
• History preservation is important

Advantages:

• ✅ Full control over commit order
• ✅ Can keep important intermediate commits
• ✅ Can edit commit messages
• ✅ Excellent for code review

Disadvantages:

• ❌ More conflict resolution iterations
• ❌ Takes more time
• ❌ More error-prone

Interactive rebase commands:

pick    = use commit
reword  = use commit, but edit message
squash  = use commit but combine with previous
fixup   = like squash, but discard log message
drop    = remove commit
exec    = run command between commits

Example:

$ git rebase -i origin/main

# Before:
pick commit1 - feat: part A
pick commit2 - feat: part B
pick commit3 - test: add tests
pick commit4 - chore: lint

# Edit to:
pick commit1 - feat: part A
squash commit2 - feat: part B      # Combine with part A
squash commit3 - test: add tests   # Include tests
drop commit4 - chore: lint         # Remove lint-only commit

# Save and edit final message to describe everything

---

3. Simple Linear Rebase (Fastest)

How it works:

git rebase origin/main
# Git replays all your commits directly, no intermediate edits

When to use:

• 1-2 commits only
• Simple changes, minimal conflicts
• Don't care about reordering
• Want fastest possible rebase

Advantages:

• ✅ Fastest to execute
• ✅ Simplest conceptually
• ✅ Preserves commit history as-is

Disadvantages:

• ❌ Conflict per commit (can be slow)
• ❌ Can't reorder or edit commits
• ❌ Loses opportunity to clean up history

---

4. Git Rerere (Smart Replay)

How it works:

git config --global rerere.enabled true
# Git records your conflict resolutions
# Automatically replays them when same conflict appears

When to use:

• Rebasing many commits against target with repeated conflicts
• Same file changed in multiple of your commits
• Want to avoid re-resolving the same conflicts

Advantages:

• ✅ Automatic conflict replay
• ✅ Huge time savings for complex rebases
• ✅ Consistent resolutions

Disadvantages:

• ❌ Can hide mistakes if recorded wrong
• ❌ Requires careful first resolution
• ❌ Only works for identical conflict patterns

How to use:

# Enable (one-time)
git config --global rerere.enabled true

# Now when you rebase:
git rebase origin/main

# First conflict: You resolve it
# [Edit file, git add, git rebase --continue]

# Second identical conflict: Git automatically applies same resolution
# Just keep going: git rebase --continue

# Git has learned your conflict pattern and replays it

Track rerere database:

# See all recorded resolutions
ls -la .git/rr-cache/

# Review a specific resolution
cat .git/rr-cache/<conflict-hash>/preimage
cat .git/rr-cache/<conflict-hash>/postimage

---

5. Merge Instead (Safest Alternative)

How it works:

git merge origin/main
# Combines two branches, creates merge commit

When to use:

• Shared branches (never rebase shared branches!)
• Too complex to rebase
• Team collaboration on same branch
• Want to preserve branch history

Advantages:

• ✅ Preserves both histories
• ✅ Can't lose commits
• ✅ Safe for shared branches
• ✅ Clearer integration point

Disadvantages:

• ❌ Less clean history
• ❌ Creates merge commit
• ❌ Harder to bisect
• ❌ More verbose history

---

Automation Strategies (Pipeline Use)

Risky: Auto-Accept With -X

# Accept all INCOMING changes (main's version)
git rebase -X theirs origin/main

# Accept all YOUR changes (your version)
git rebase -X ours origin/main

# Three-way recursive merge (safest auto-strategy)
git rebase -X recursive origin/main

ONLY use when:

1. You have comprehensive tests covering all changes 2. You understand the implications 3. You've verified the strategy on a test branch first 4. Changes are non-critical (not user-facing)

Recommendation: Avoid auto-resolution in production pipelines.

---

Conflict Complexity Indicators

Low Complexity (Safe to Auto-Resolve)

• ✅ Changes in different files
• ✅ Same file, different functions/methods
• ✅ Whitespace/formatting conflicts
• ✅ Import reordering

Medium Complexity (Manual Review Needed)

• ⚠️ Changes in same function but different branches
• ⚠️ Logic changes (if statements, loops)
• ⚠️ Return values or flow changes
• ⚠️ API changes

High Complexity (Very Careful)

• ❌ Same line changed differently
• ❌ Critical business logic
• ❌ Security/authentication code
• ❌ Database migrations

---

Decision Tree: Which Strategy?

START: Do I need to rebase?
  |
  +-> Is this a shared branch?
      |-> YES: Use MERGE instead, don't rebase
      |-> NO: Continue
  |
  +-> How many commits to rebase?
      |-> 1-2 commits:
      |   +-> Use SIMPLE LINEAR REBASE
      |   +-> Quick, straightforward
      |
      |-> 3-10 commits:
      |   +-> Are conflicts expected?
      |   +-> YES: Use SQUASH FIRST
      |   +-> NO: Use INTERACTIVE REBASE
      |
      |-> 10+ commits:
          +-> Almost always: Use SQUASH FIRST
          +-> Too many conflict iterations otherwise
  |
  +-> Any other concerns?
      |-> I've rebased this file before: Enable RERERE
      |-> Feeling uncertain: Use MERGE instead
      |-> Need clean history: Use INTERACTIVE
      |-> Just want it done: Use SQUASH FIRST

END: Choose strategy and proceed

---

Post-Resolution Validation

After resolving conflicts, always validate:

# 1. Check syntax (prevents runtime errors)
npm run lint
npm run type-check  # If TypeScript

# 2. Check logic (review changes)
git diff HEAD origin/main -- <conflicted-file>

# 3. Run tests (catches integration issues)
npm test

# 4. Manual smoke test (try key features)
npm start
# Test the feature manually

# 5. Only then force push
git push origin branch --force-with-lease

Rule: Never push code you haven't tested.

Troubleshooting Common Rebase Issues

Problem: "CONFLICT (content): Merge conflict in X"

What it means: File X has conflicting changes from both branches

Solution:

1. git status to see all conflicts 2. Edit each conflicted file (look for <<<<<<< markers) 3. git add <file> 4. git rebase --continue

Problem: "fatal: cannot lock ref 'refs/heads/...'"

What it means: Git can't write to branch (another command is running or permission issue)

Solution:

# Check if another git process is running
ps aux | grep git

# Kill it if safe: kill <PID>

# Or retry after a moment
# If persistent: check file permissions in .git/

Problem: Rebase seems stuck (no prompt)

What it means: Your editor didn't open, or it's waiting for input

Solution:

# Check if you have an editor set
git config --global core.editor

# Set one if not configured
git config --global core.editor "nano"  # or "vim", "code", etc.

# Resume rebase
git rebase --continue

Problem: "Your branch has diverged"

What it means: After rebase, local and remote have different history

Solution:

# This is EXPECTED after rebase
# Force push safely to update remote
git push origin $(git rev-parse --abbrev-ref HEAD) --force-with-lease

Problem: Lost Commits After Force Push

Recovery:

# Your backup branch saves you
git reset --hard backup-rebase-<timestamp>

# Or use reflog to find the SHA
git reflog
git reset --hard <SHA>