Rebase Branch
Goal
Rebase the current branch onto a target branch, guide through any conflicts that arise, and optionally force-push the rebased branch. This command helps keep feature branches up-to-date with the main branch while maintaining a clean commit history.
Note: Interactive rebase (git rebase -i) is not supported as it requires terminal interaction. This command performs a standard rebase.
Input
$ARGUMENTS (optional): Target branch name to rebase onto (defaults to auto-detected main branch: main, master, or develop)
Process
- Pre-flight Checks: Verify working directory is clean and identify branches
- Detect Target Branch: Auto-detect main branch if not specified
- Fetch Latest: Fetch latest changes from remote
- Execute Rebase: Run git rebase onto target branch
- Handle Conflicts: Guide user through resolution if conflicts occur
- Force Push: Offer to push rebased branch with safety checks
Pre-flight Checks
Before starting the rebase:
-
Check for uncommitted changes:
- Run
git status --porcelain
- If output is non-empty, abort and ask user to commit or stash changes first
-
Identify current branch:
- Run
git branch --show-current
- Store for later use in push step
-
Verify not on target branch:
- If current branch equals target branch, abort with helpful message
-
Check for rebase already in progress:
- Check if
.git/rebase-merge or .git/rebase-apply directories exist
- If found, use AskUserQuestion: "A rebase is already in progress. What would you like to do?"
- Options: "Continue the rebase", "Abort and start fresh", "Skip this commit"
Target Branch Detection
If no target branch is specified in $ARGUMENTS:
-
Check for common main branch names (local OR remote):
git show-ref --verify --quiet refs/heads/main || git show-ref --verify --quiet refs/remotes/origin/main → use main
git show-ref --verify --quiet refs/heads/master || git show-ref --verify --quiet refs/remotes/origin/master → use master
git show-ref --verify --quiet refs/heads/develop || git show-ref --verify --quiet refs/remotes/origin/develop → use develop
-
If none found, ask user to specify target branch
Fetch and Rebase
-
Fetch latest changes:
git fetch origin
-
Execute rebase:
git rebase origin/<target-branch>
-
Check exit code to determine if conflicts occurred
Conflict Resolution
When conflicts occur, guide the user through resolution:
1. Identify Conflicted Files
git diff --name-only --diff-filter=U
2. For Each Conflicted File:
- Display the file path
- Read and show the conflict markers using the Read tool
- Explain what the conflict is with CORRECT terminology:
- IMPORTANT: During rebase, git terminology is REVERSED from merge!
- The "HEAD" / "Current Change" section shows the TARGET branch (e.g., main) - this is counterintuitive!
- The "Incoming Change" section shows YOUR branch's changes
- Explain this clearly: "The top section (HEAD) is from main, the bottom section is your changes"
3. Wait for User to Resolve:
- Use AskUserQuestion to wait for explicit confirmation
- Prompt: "Please resolve the conflicts in your editor, save the files, then confirm here."
- Options: "I've resolved the conflicts", "I need help understanding the conflict", "Abort the rebase"
4. After User Confirms Resolution:
- Verify the file no longer has conflict markers
- Stage the resolved file:
git add <file>
- Ask if there are more conflicts to resolve
5. Continue Rebase:
git rebase --continue
6. Repeat if More Conflicts:
- If rebase stops again with conflicts, repeat the resolution process
- Keep track of progress and inform user
7. Abort Option:
- At any point, offer the user the option to abort:
git rebase --abort
- This returns the branch to its pre-rebase state
Force Push with Safety Checks
After successful rebase, offer to push:
0. Check for Protected Branches:
Before offering force push, verify current branch is not a protected branch:
# If current branch is main, master, or develop - DO NOT offer force push
- If on protected branch, display: "Force push skipped - you're on a protected branch (main/master/develop). Rebase complete but not pushed."
- Skip the entire force push flow and end the command
1. Check if Branch Exists on Remote:
git ls-remote --heads origin <current-branch>
2. Warn About Shared Branches:
- If other commits exist on remote that aren't in local, warn user
- Check with:
git log origin/<branch>..<branch> --oneline and vice versa
3. Confirm with User:
Use AskUserQuestion to confirm:
- "Rebase complete. Push changes to origin/<branch>?"
- Options: "Yes, force push", "No, I'll push manually"
4. Execute Force Push:
Use --force-with-lease for safety (prevents overwriting others' work):
git push --force-with-lease origin <current-branch>
Error Handling
- Dirty working directory: Ask user to commit or stash changes first
- Target branch doesn't exist: List available branches and ask user to specify
- Rebase already in progress: Offer to continue, abort, or skip
- Push rejected: Explain why and suggest solutions
- No upstream set: Offer to set upstream with push
Command Execution Steps
- Run
git status --porcelain to check for uncommitted changes
- Run
git branch --show-current to get current branch name
- Detect or validate target branch
- Run
git fetch origin to get latest
- Run
git rebase origin/<target> and check result
- If conflicts:
- List conflicted files
- Read each file to show conflicts
- Guide resolution
- Stage resolved files
- Continue rebase
- Repeat until complete
- Ask user about force push
- If confirmed, run
git push --force-with-lease origin <branch>
Success Output
✅ Rebase Complete
📍 Branch: feature/my-feature
🎯 Rebased onto: origin/main
📊 Commits replayed: 5
🚀 Pushed to origin/feature/my-feature (force-with-lease)
Example Usage
/rebase # Rebase onto auto-detected main branch
/rebase main # Explicitly rebase onto main
/rebase develop # Rebase onto develop branch
Final Instructions
- Always check for clean working directory before starting
- Never force push to main/master/develop branches
- Use
--force-with-lease instead of --force for safety
- Guide users clearly through conflict resolution
- Keep users informed of progress throughout the process
- Offer abort option at any point during conflict resolution