rebasing-branch

cblecker 的头像作者 cblecker

所有变基操作('rebase branch', 'rebase on main', 'rebase onto')的标准工作流:用Git安全协议替换基于bash的git变基工作流—首先同步基础分支,防止主线变基错误,保持工作状态,提供冲突解决指导。git-workflows的规范变基实现。

📖 中文导读:所有变基操作('rebase branch', 'rebase on main', 'rebase onto')的标准工作流:用Git安全协议替换基于bash的git变基工作流—首先同步基础分支,防止主线变基错误,保持工作状态,提供冲突解决指导。git-workflows的规范变基实现。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Rebase a git branch description: Provides comprehensive rebase workflow with automatic base branch sync, author date management, and conflict resolution guidance. Syncs base branch before rebasing, prevents mainline rebase errors, resets author dates on request. Integrates with Git Safety Protocol for force push warnings. Use for 'rebase', 'rebase on main', 'rebase onto', 'update branch with main'.

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 ", "rebase on ", "rebase against "
  • 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.