smart-rebase

Files (2)

• SKILL.md
• smart-rebase-analyze.sh · scripts/

SKILL.md (first lines)

# 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); a `<quoted branch>` after
it stays a short name on purpose. **Which spelling matters, and where, is measured — not a blanket
rule.** Measured on git 2.55.0 in this repository:

| Command | `--` | `--end-of-options` | Consequence |
|---------|------|--------------------|-------------|
| `git push`, `git fetch`, `git merge-base` | accepted | accepted | **Interchangeable.** Picking one is a convention, not a correctness requirement |
| `git log … --not <name>` | forces `<name>` to a **pathspec** — a name that is neither ref nor file yields nothing at exit 0 | keeps rev/path disambiguation — the same name exits **128** with `ambiguous argument` | **Not interchangeable.** `--end-of-options` fails closed; `--` fails silently. Step 6 uses `--end-of-options` for this reason |
| `git rev-parse` | — | **echoes the separator literally**, then resolves | Neither separator helps. Use `git rev-parse --verify --quiet refs/heads/<name>` |
| `git check-ref-format --branch` | rejected (exit 129) | rejected (exit 129) | Honours neither, so the script validates a source by its full `refs/heads/…` form instead |

The separator terminates **option** parsing, never **refspec** parsing: `git push origin -- '+main'`
still reads the leading `+` as the force modifier, and `git check-ref-format --branch '+main'` exits
0, so a lexical protected-branch check passes a branch literally named `+main`. Emit fully-qualified
refspecs (`'refs/heads/<n>:refs/heads/<n>'`) rather than short names wherever a `+` could appear.
This is the same fact § Step 5 states about the analysis script: the resolved operand is what git
acts on, never the spelling that was typed.

The slot also **brings its own quotes** —
never wrap one in a further fixed pair. `'--base=<quoted branch-or-commit>'` reads as safe and is
not: substituting `feat/x;printf${IFS}PWN` yields `'--base='feat/x;printf${IFS}PWN''`, which the
shell splits into an analysis call and a second command (measured), and a name containing `'` turns
it into a syntax error. Write the fixed prefix unquoted, adjacent to the slot:
`--base=<quoted branch-or-commit>`. Where the analysis script has already
produced the string — its `rebase_command` field, and the `git fetch …` line in its failure
message — copy that string rather than rebuilding it; `sh_quote` in the script is the same rule,
already applied. Reasons in full: `docs/features/ref-name-hardening/4-implementation.md` § 1.

## 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: Output → print the rebase command for the developer to run

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness