Skill: Rebasing a Branch

When to Use This Skill

Use this skill for rebase requests: "rebase my branch", "rebase on main", "rebase onto X", "update my branch with main".

Use other skills for: syncing (syncing-branch for fetch+merge), viewing status (git status directly).

Workflow Description

Rebases feature branch onto updated mainline, rewriting commit history. Handles state preservation, conflict resolution, optional author date reset.

Extract from user request: target branch (if specified, else mainline), author date preference ("keep dates"/"preserve dates" → preserve, default reset)

---

Phase 1: Pre-flight Checks

Objective: Verify environment is ready for rebase operation.

Step 1: Get current branch

Get current branch:

git branch --show-current

Capture: current_branch

Step 2: Check if on mainline

Run ${CLAUDE_PLUGIN_ROOT}/scripts/get-mainline-branch.sh with the current branch as parameter

Parse JSON response:

• Extract mainline_branch field
• Extract is_mainline flag (true if current branch matches mainline)
• Store both for later phases

Step 3: Check working tree status

Check status:

git status --porcelain

Capture: working tree clean status (empty = clean)

Validation Gate: Safe to Rebase

IF is_mainline = true: STOP immediately EXPLAIN: "Cannot rebase the mainline branch. Mainline should never be rebased as it's the stable reference point for all feature branches." INFORM: "Rebasing mainline would rewrite its history and break all feature branches based on it." PROPOSE: "Create a feature branch first if you need to test changes" EXIT workflow

IF is_mainline = false AND working tree not clean (status output not empty): INFORM: "Uncommitted changes detected - creating commit first" INVOKE: creating-commit skill WAIT for creating-commit to complete

IF creating-commit succeeded: VERIFY: Working tree is now clean PROCEED to Phase 2

IF creating-commit failed: STOP immediately EXPLAIN: "Cannot rebase without committing changes" EXIT workflow

IF is_mainline = false AND working tree clean: PROCEED to Phase 2

Save State: Store saved_branch = current_branch (preserve through all phases)

Phase 1 complete. Continue to Phase 2.

---

Phase 2: Determine Rebase Base

Objective: Identify which branch to rebase onto.

Step 1: Check user request for rebase target

Analyze user's request for target branch specification:

• Look for phrases like: "rebase onto <branch>", "rebase on <branch>", "rebase against <branch>"
• Common branch names: main, master, develop, staging, release, etc.

IF target branch specified in user request: Use specified branch as rebase base

IF no target branch mentioned: Use mainline_branch from Phase 1 as rebase base

Store rebase_base for later phases.

Phase 2 complete. Continue to Phase 3.

---

Phase 3: Checkout Base Branch

Objective: Switch to base branch for syncing.

Step 1: Checkout base branch

Checkout rebase base:

git checkout <rebase_base from Phase 2>

Error Handling

IF checkout succeeds: PROCEED to Phase 4

IF checkout fails: See reference/error-types.md (Phase 3: Checkout Base Branch Errors) for detailed error handling.

Read reference/error-types.md and match error message to documented scenarios. Follow the prescribed action for the specific error type.

Phase 3 complete. Continue to Phase 4.

---

Phase 4: Sync Base Branch

Objective: Ensure base branch is up-to-date with remote.

Plan Mode Handling

Plan mode is automatically enforced by the system. IF currently in plan mode:

• Sync operation will be read-only
• Skills invoked will operate in read-only mode
• Continue through workflow for demonstration purposes

Step 1: Invoke syncing-branch skill

INVOKE: syncing-branch skill WAIT for skill completion

Validation Gate: Sync Success

IF syncing-branch skill succeeded: INFORM: "Base branch synced successfully with remote" PROCEED to Phase 5

IF syncing-branch skill failed: See reference/error-types.md (Phase 4: Sync Base Branch Errors) for detailed error handling.

Follow the prescribed action for sync failure.

Phase 4 complete. Continue to Phase 5.

---

Phase 5: Return to Feature Branch

Objective: Switch back to feature branch for rebase.

CRITICAL: Use Saved State

Retrieve saved_branch from Phase 1 (NOT current branch - we're on base branch now)

Step 1: Checkout feature branch

Checkout saved branch:

git checkout <saved_branch from Phase 1>

Error Handling

IF checkout succeeds: PROCEED to Phase 6

IF checkout fails: See reference/error-types.md (Phase 5: Return to Feature Branch Errors) for detailed error handling.

This is a CRITICAL FAILURE requiring manual intervention. Follow the prescribed action.

Phase 5 complete. Continue to Phase 6.

---

Phase 6: Rebase Execution

Objective: Perform the actual rebase operation.

Plan Mode: Auto-enforced read-only if active

Steps:

1. Execute: git rebase <rebase-base> (from Phase 2)
2. Check exit code

Validation Gate:

See reference/error-types.md (Phase 6: Rebase Execution Errors) for detailed error handling.

Read reference/error-types.md to understand the different exit scenarios:

• Success: Continue to Phase 7
• Conflicts: PAUSE workflow (normal, not failure)
• Other errors: Follow documented error handling

Note: Conflicts are normal, not failures. Workflow PAUSED ≠ FAILED.

Continue to Phase 7.

---

Phase 7: Reset Author Dates (Conditional)

Objective: Update author dates to current time.

Skip: IF user requested preserving dates

Plan Mode: Auto-enforced read-only if active

Steps:

1. Find fork point: git merge-base --fork-point <rebase-base> (from Phase 2)
2. Reset dates: git rebase <fork-point> --reset-author-date
3. Check exit code

Validation Gate: IF reset fails:

See reference/error-types.md (Phase 7: Author Date Reset Errors) for detailed error handling.

Continue to Phase 8.

---

Phase 8: Verification

Objective: Confirm rebase completed successfully.

Steps:

1. Verify current branch:

   git branch --show-current
   

2. Compare to saved_branch from Phase 1

3. Check status:

   git status --porcelain
   

   Verify clean (empty output)

4. Get recent commits:

   git log --oneline -5
   

5. Report using template:

   ✓ Branch Rebased Successfully
   
   **Branch:** <saved_branch> \
   **Rebased onto:** <rebase_base> \
   **Author dates:** <Reset|Preserved> \
   **Working tree:** <Clean|Dirty>
   
   **⚠ Important:** Force push required to update remote
   
   See `${CLAUDE_PLUGIN_ROOT}/shared/git-safety-protocol.md` for force push guidelines.
   
   Recommended command: `git push --force-with-lease origin <saved_branch>`
   
   **This skill provided:** Automatic base branch sync, author date reset option, conflict resolution guidance
   

Validation Gate: IF current branch ≠ saved_branch:

See reference/error-types.md (Phase 8: Verification Errors) for detailed error handling.

Workflow complete.