/smart-rebase

name: smart-rebase
description: "Smart partial rebase for squash-merge repositories. Auto-detect which commits to keep/drop when base branch was squash-merged into target. Use when: user says 'rebase', 'partial rebase', 'base already merged', 'smart rebase', or /smart-rebase. Not for: simple git rebase (the developer runs it — no skill executes rebase for them), merge conflict resolution (use /merge-prep), branch switching (the developer runs git checkout). Output: rebase plan table + a shell-quoted git rebase --onto command for the developer to run after the ambiguity check in Step 5."
allowed-tools: Bash(git:*), Bash(bash:*), Read, Grep, Glob

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 — **the developer runs it**; no skill runs

`rebase` for them, this one included, and the one credential that reaches it is the user's own message naming that execution (§ Permissions). "Use git directly" is an instruction to the human, and this list is read by the dispatcher before § Permissions loads, so it says so here

• Merge conflict resolution (use `/merge-prep`)
• Branch management or switching — the developer runs the git command
• 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` — **no workflow authorization lifts this**, this skill's included. The one credential that does reach it is Register #4's `user-authorized execution`: the user's own message naming that execution, which this skill can neither grant, request nor infer. `rebase` is a destructive operation under Anchor Register #4 (`@rules/discretion.md`), whose enumerated approval workflows are a closed set: `/push-ci` (push), `/smart-commit --execute` (add + commit), `/epic-merge` (rebase --onto, force-with-lease, squash-merge) and `/gh-stack` (`gh stack link` / `push` / `submit --auto`). This skill is not on that list, so user approval here cannot create the exception — adding a workflow to the list is itself an Anchor-level change. This skill **outputs** the rebase command; the developer runs it.

> **Note on `allowed-tools`**: `Bash(git:*)` is granted because Steps 1–3 read history (`git log`, > `git rev-parse`, `git branch --show-current`), and `Bash(bash:*)` to run the analysis script — > the latter cannot be narrowed to specific script paths until > [#9354](https://github.com/anthropics/claude-code/issues/9354) is resolved. **A tool grant is not > an authorization**: what may be executed is decided by the rule above, not by what the permission > string happens to permit.

Prerequisites

Before starting, validate:

| Check | Command | Fail action | |-------|---------|-------------| | Not on a protected branch | `git branch --show-current` must not match the **complete** protected set defined in `@rules/git-workflow.md` § Prohibited (which lists the complete protected set): `main`, `master`, `develop`, `release/*`. Do not re-spell a shorter list here — a partial copy is how `master` and `release/*` reached the force-push suggestion below | 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" |

Names in commands

Every command this skill outputs carries ref names, and **a ref name is not display text**: `git check-ref-format` accepts `;`, backticks, `$( )` and `'` inside one — all measured. A name substituted into a command as a bare word runs whatever it contains, and a fixed pair of single quotes is broken by a name containing `'`.

So every `<…>` slot in a command block below is written `<quoted …>`: substitute a **shell-quoted** value, single-quoted with each `'` rendered as `'\''`.

**Shell-quoting is only half of it, and the other half is git's own option parser.** Quotes are consumed by the shell; git never sees them, so a branch named `--all` is still an option when it arrives. Measured: `git check-ref-format refs/heads/--all` exits 0, and `git push --force-with-lease origin '--all'` pushed **every** branch in the repository, not the one named. The mechanism the templates below rely on is the **`--` / `--end-of-options` separator**, placed before the ref operand — not fully-qualifying it. That distinction is load-bearing for one operand in particular: a `git rebase` **branch** operand written `refs/heads/<branch>` is measured to land on a **detached HEAD** and never move the branch, which is the whole point of the command, whereas the same short name after `--` stops the option parser and — **when the short name resolves unambiguously** — updates the ref. That qualification is not hypothetical and the separator does not supply it: with a branch `refs/heads/tags/v0.0.1` and a tag `v0.0.1` both present, `git rebase --onto main main -- 'tags/v0.0.1'` **exits 0 and leaves the branch unmoved** (measured — `docs/features/ref-name-hardening/requests/2026-08-20-ref-name-hardening-r1.md` finding 1). Until the ambiguity probe that closes this lands (that ticket's AC 1), **the emitted `rebase_command` is not safe to run verbatim on a repository where the current branch name could also name a tag** — check `git rev-parse --verify` for an `is ambiguous` warning on the operand before running it. So the separator, carried in the template, is the rule — `--` for `git push` and `git rebase`, `--end-of-options` for `git merge-base` and for `git log --not` (Step 6);