Rebase Skill (Fusion Framework)

This skill helps you rebase feature branches onto the latest main branch, handling common conflicts in a pnpm monorepo.

Overview

When rebasing a feature branch, you'll often encounter conflicts in pnpm-lock.yaml due to parallel dependency changes. The correct approach is to regenerate the lockfile rather than manually resolving conflicts.

Standard Rebase Workflow

1. Prepare for rebase

# Navigate to your worktree or branch
cd /path/to/worktree

# Ensure you're on the correct branch
git branch

# Fetch latest changes from origin (including main)
git fetch origin
git fetch origin main:refs/remotes/origin/main

2. Start the rebase

# Rebase your branch onto the latest main
git rebase origin/main

3. Handle pnpm-lock.yaml conflicts

CRITICAL: When pnpm-lock.yaml has conflicts during rebase:

# Regenerate it from package.json files
pnpm install

# Stage the regenerated lockfile
git add pnpm-lock.yaml

# Continue the rebase
git rebase --continue

4. Handle "Version Packages" commit conflicts

When you encounter a "Version Packages (next)" commit with conflicts:

This happens when your feature branch has pre-release versions (e.g., 2.0.0-next.0) but main has been updated with newer regular versions.

Resolution strategy:

package.json: Use --ours (HEAD version from main)
CHANGELOG.md: Use --ours (HEAD changelog from main)

# For all package.json conflicts, keep HEAD version
git checkout --ours "packages/*/package.json"
git add "packages/*/package.json"

# For all CHANGELOG.md conflicts, keep HEAD changelog  
git checkout --ours "packages/*/CHANGELOG.md"
git add "packages/*/CHANGELOG.md"

# Also check other affected files
git checkout --ours "vue-press/package.json" 2>/dev/null || true
git add "vue-press/package.json" 2>/dev/null || true

# Continue the rebase
git rebase --continue

Why? The main branch has the authoritative versions and changelogs. Your feature branch's pre-release versions will be regenerated when you create a new changeset after rebasing.

5. Handle other conflicts

For conflicts in source files (.ts, .tsx, etc.):

# Manually resolve conflicts in the files
# Then stage the resolved files
git add path/to/resolved-file.ts

# Continue the rebase
git rebase --continue

6. Complete the rebase

After all commits are rebased successfully:

# Verify the branch is clean
git status

# Force push to update the remote branch
git push --force-with-lease origin YOUR_BRANCH_NAME

7. Align pre.json initial versions (if in pre mode)

If .changeset/pre.json exists (pre-release mode), align initialVersions to current package versions for packages changed by the rebase:

# From repo root
node .github/skills/rebase/scripts/align-pre-initial-versions.cjs

What it does:

Reads .changeset/pre.json to get the tag (e.g., next)
Updates initialVersions when the current package version does NOT end with -TAG.NUMBER (e.g., 2.0.0 or 2.1.0)
Skips entries where the current version ends with -TAG.NUMBER (e.g., 2.0.0-next.0), preserving ongoing pre state

8. Sanity check vs remote

Before pushing, verify local rebase result against the remote branch.

# Ensure you have latest remote
git fetch origin

# Set a helper var for current branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Quick overview of what will change on the remote
git diff --stat origin/$BRANCH...HEAD

# See the file list (useful to spot unintended changes)
git diff --name-only origin/$BRANCH...HEAD | sort

# Review commit differences (left/right) without merges
git log --oneline --left-right --cherry --no-merges origin/$BRANCH...HEAD

# Optional: preview the push without sending any data
git push --force-with-lease --dry-run origin $BRANCH

Proceed to push only if the changes match expectations.

9. Generate raw data report

Run the data extraction script:

# From repo root
node .github/skills/rebase/scripts/generate-rebase-report.cjs --no-fetch

This generates .tmp/skills/rebase/<timestamp>-rebase-report.md with raw data:

Ahead/behind counts and diff summary
Highlights & Anomalies: largest diffs, config changes, dependency summary
Full commit list (all 57+ commits with hashes and messages)
Changed packages and top-level folders
pre.json initialVersions changes (version baseline updates)
pnpm-lock.yaml churn
Detailed Dependency Changes - Complete breakdown per package:
- ⚠️ Major version bumps (e.g., zod: ^3.23.8 → ^4.3.5)
- ➕ Added dependencies (e.g., @azure/search-documents: ^12.2.0)
- ➖ Removed dependencies
- Minor/patch version changes
- Organized by section: dependencies, devDependencies, peerDependencies

10. Generate human-readable summary (automatic)

After the raw report is generated, the AI agent will automatically:

Read the latest report from .tmp/skills/rebase/<timestamp>-rebase-report.md
Analyze the "Detailed Dependency Changes" section
Create a human-readable summary with:
- Breaking dependency changes - Each major bump explained (what package, what changed, why it matters, what to test)
- New dependencies added - What was added and its purpose
- Version baselines updated - Which packages bumped and what that means
- Risk assessment - Overall risk level (🟢 LOW, 🟡 MEDIUM, 🔴 HIGH) with reasoning
- Pre-push checklist - Specific tests to run based on detected changes

The summary will be displayed in the chat for review before you push.

Next steps: sanity checks and push confirmation

Open the SUMMARY.md file in your editor to review before pushing.

Common Scenarios

Reset local branch to match remote

If your local branch has diverged incorrectly:

# Fetch latest
git fetch origin

# Hard reset to remote branch
git reset --hard origin/YOUR_BRANCH_NAME

Abort a rebase in progress

If you need to start over:

git rebase --abort

Continue after fixing conflicts

# After resolving conflicts and staging changes
git rebase --continue

Skip a commit during rebase

Only if the commit is no longer needed:

git rebase --skip

Rebase Checklist

Why Regenerate pnpm-lock.yaml?

The lockfile contains exact dependency resolutions for the entire monorepo. During a rebase:

Base branch (main) has new/updated dependencies
Your branch has different/updated dependencies
Git cannot merge these semantically - it only sees text conflicts

By regenerating with pnpm install:

pnpm reads all current package.json files (including your changes)
Resolves dependencies against the latest registry state
Creates a consistent lockfile that works with both sets of changes
Respects workspace protocols and catalog references

Troubleshooting

"diverged and have X and Y different commits"

Your local branch has commits that aren't on remote. Common causes:

Previous force push to a different commit
Local branch accidentally pointing to wrong commit

Fix: Reset to remote and rebase:

git fetch origin
git fetch origin main:refs/remotes/origin/main
git reset --hard origin/YOUR_BRANCH_NAME
git rebase origin/main

Rebase conflicts on every commit

You may be rebasing in the wrong direction. Ensure:

You're ON your feature branch
You're rebasing ONTO main: git rebase origin/main

pnpm install fails during rebase

Check:

All package.json changes are staged/committed
No syntax errors in modified package.json files
You're running from the repository root

Example: Complete rebase flow

# 1. Navigate and prepare
cd /Users/odin.rochmann/dev/GitHub/fusion-framework.worktree/react-19
git fetch origin
git fetch origin main:refs/remotes/origin/main

# 2. Ensure clean state
git status  # Should show "nothing to commit, working tree clean"

# 3. Start rebase
git rebase origin/main

# 4. If pnpm-lock.yaml conflict appears:
git rm pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml
git rebase --continue

# 5. Repeat step 4 for each commit with lockfile conflicts

# 6. When rebase completes:
git push --force-with-lease origin react-19

Related Skills

pnpm-dependency-analysis - Analyze dependencies before/after rebase
dependabot-pr-handler - Handle automated dependency updates that may conflict during rebase