rebasing-branch
所有变基操作('rebase branch', 'rebase on main', 'rebase onto')的标准工作流:用Git安全协议替换基于bash的git变基工作流—首先同步基础分支,防止主线变基错误,保持工作状态,提供冲突解决指导。git-workflows的规范变基实现。
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_branchfield - Extract
is_mainlineflag (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:
- Execute:
git rebase <rebase-base>(from Phase 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:
- Find fork point:
git merge-base --fork-point <rebase-base>(from Phase 2) - Reset dates:
git rebase <fork-point> --reset-author-date - 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:
Verify current branch:
git branch --show-currentCompare to saved_branch from Phase 1
Check status:
git status --porcelainVerify clean (empty output)
Get recent commits:
git log --oneline -5Report 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.