smart-rebase

Smart Rebase — Partial Rebase for Squash-Merge Repos

Analyze branch history → identify squash-merged commits → generate precise git rebase --onto command.

When NOT to Use

• Simple git rebase without squash-merge complexity (use git directly)
• Merge conflict resolution (use /merge-prep)
• Branch management or switching (use git commands)
• Cherry-picking specific commits (use git cherry-pick)

Core Problem

In squash-merge repositories, when a feature branch is based on another branch that was already squash-merged:

main:    A ─── S (squash merge of B1+B2+B3) ─── ...
              ↑
feature: A ─ B1 ─ B2 ─ B3 ─ F1 ─ F2 ─ F3
              ↑ drop (in S)   ↑ keep (unique)

Need: git rebase --onto main B3 feature to keep only F1-F3.

Permissions

Claude must not execute git rebase unless user explicitly authorizes. Default: output commands for manual execution.

Note on allowed-tools: Bash(bash:*) is required to run the analysis script. Cannot narrow to specific script paths until #9354 is resolved.

Prerequisites

Before starting, validate:

| Check | Command | Fail action | |-------|---------|-------------| | Not on shared branch | git branch --show-current must not be main or develop | Abort with warning | | Clean working tree | git status --porcelain must be empty | Abort: "stash or commit changes first" | | Not detached HEAD | git symbolic-ref HEAD succeeds | Abort: "checkout a branch first" |

Workflow

Step 1: Analyze → run script to detect commits
Step 2: Identify → determine keep/drop boundary (cut point)
Step 3: Display → output rebase plan
Step 4: Confirm → user reviews
Step 5: Execute → output or execute rebase command
Step 6: Verify → confirm history is correct

Step 1: Analyze

bash skills/smart-rebase/scripts/smart-rebase-analyze.sh [--target origin/main]

Auto-detect mode uses git cherry to find commits already cherry-picked to target. Squash merges cannot be detected by git cherry — proceed to Step 2.

Step 2: Identify Cut Point

Case A — User provides base branch or commit

# Resolve the common ancestor as cut candidate
git merge-base <base-branch> HEAD
# Or specify the cut point commit directly
bash skills/smart-rebase/scripts/smart-rebase-analyze.sh --base <branch-or-commit>

Case B — Inference needed

1. Check target_new squash merge commit messages
2. Compare with commits messages in current branch
3. Identify which commits are covered by the squash merge
4. Confirm cut point and re-run with --base

Case C — git cherry detected all

When cherry_dropped > 0, detected commits can be dropped. Verify cut point is contiguous (all drops must precede all keeps).

Step 3: Display Plan

## Rebase Plan

| Item           | Value                                   |
| -------------- | --------------------------------------- |
| Current branch | feat/my-feature                         |
| Target         | origin/main (dd21265c)                  |
| Cut point      | 06a7fae6                                |
| Keep           | 3 commits                               |
| Drop           | 15 commits (already in main via squash) |

### Commits to Keep

1. `57d7898a` feat: Add error classification framework
2. `05c11119` docs: Document classification rules
3. `da987681` fix: Correct classification accuracy

### Commits to Drop (already in main)

1. `f76209f4` docs: Add RPC optimization design
   ...

Step 4: User Confirmation

Display plan and wait for user confirmation before proceeding.

Step 5: Execute

# Fetch only if target is a remote-tracking ref
git fetch origin <target-branch>   # skip if target is local
git rebase --onto <target> <cut-point> <branch>

• Default: output commands for manual execution
• User-authorized: execute directly

Step 6: Verify

# Confirm history is correct
git log --oneline -10

# Confirm commit count
git log --oneline HEAD --not <target> | wc -l

On success, suggest force push:

git push --force-with-lease origin <branch>

Conflict Handling

| Scenario | Action | | ----------------------- | --------------------------------------------- | | Already squash-merged | git rebase --skip (dropped commit) | | Real content conflict | Manual resolve → git rebase --continue | | Cannot resolve | git rebase --abort to restore original state |

Prohibited

• No rebase on shared branches (main/develop)
• No force push to main/develop
• No rebase without user confirmation
• Always use --force-with-lease (prevent overwriting others' pushes)

Output

Rebase plan table with keep/drop commits:

• With --base: includes git rebase --onto command ready to copy-paste
• Auto-detect: analysis report with cherry status per commit; may require --base follow-up

Verification

• [ ] Prerequisites validated (not shared branch, clean tree, not detached)
• [ ] Script output parsed and displayed as plan table
• [ ] User confirmed before any rebase execution
• [ ] Post-rebase commit count matches expected keep count
• [ ] --force-with-lease used (never --force)

Examples

# Auto-detect (cherry-pick scenarios)
/smart-rebase

# Specify base branch (squash-merge scenarios)
/smart-rebase --base fix/feature-xyz

# Specify non-main target
/smart-rebase --target origin/develop --base fix/hotfix-123

References

| File | Purpose | When to Read | |------|---------|-------------| | [smart-rebase-analyze.sh](scripts/smart-rebase-analyze.sh) | Analysis script | Step 1 |