SuperAPI AI Directory

smart-rebase

Coding & development

View repository

Updated 10-16 09:44

About this skill

smart-rebase — rebase onto the base branch and force-push

The whole workflow is in scripts/rebase-sync.sh, split into subcommands so a conflict can stop the run, get fixed, and resume. Drive the script — don't hand-roll git fetch/rebase/push calls, because the script also carries the safety checks (refuse on the base branch, lease-protected push, autostash).

$SKILL_DIR below is this skill's directory.

Two paths: stacked PRs vs. a plain branch

preflight reports a STACK: line, and it decides everything that follows:

  • STACK: stack — the branch belongs to a GitHub stacked PR chain and gh-stack is installed. Take the stack path (stack-sync).
  • STACK: no-stack or no-extension — take the plain path (rebase → push).

The stack path isn't merely a shortcut. A stack is a chain where each branch's parent is the branch below it, so rebasing one layer with plain git leaves the layers above pointing at the old parent — their PR diffs then show the lower layer's commits as if they were new work, and reviewers see noise that isn't theirs. gh stack sync cascade-rebases every layer onto its updated parent and pushes them atomically, which is why it wins whenever it applies.

Stack path

  1. Confirm with the user first. gh stack sync fetches, rebases and pushes in one indivisible step, so there is no post-rebase/pre-push checkpoint to stop at the way the plain path has. Tell them it will force-push (with lease) every branch in the stack, and show the stack from preflight's output.

  2. bash "$SKILL_DIR/scripts/rebase-sync.sh" stack-sync
    

    STATUS: synced and you're done — report which layers moved.

  3. Exit 10 means conflicts. sync is conservative here: it rolls every branch back to its original state and pushes nothing, so the stack is untouched. Replay it with pauses instead:

    bash "$SKILL_DIR/scripts/rebase-sync.sh" stack-rebase
    

    Resolve conflicts exactly as in the plain path below (same inverted ours/theirs caveat), git add each file, then stack-continue — repeating while it keeps exiting 10, since each layer is replayed in turn. stack-abort restores every branch. Once it reports STATUS: rebased, run stack-sync again to push.

  4. STATUS: sync-failed usually means the local and remote stacks diverged. sync needs an interactive terminal to ask which side wins, and it aborts rather than guess — so nothing was changed. Don't try to force it: report the message and ask the user to run gh stack sync in their own terminal.

Everything below is the plain path, used when STACK: is not stack.

Why it's split into subcommands

git rebase stores its paused state in .git/rebase-merge/, which outlives the process. So stopping at a conflict and resuming from a later shell invocation is safe — that's what makes rebase → (fix) → continue → push work.

Steps

  1. Preflight — always first, it tells you the branch, the resolved base, and whether the tree is dirty:

    bash "$SKILL_DIR/scripts/rebase-sync.sh" preflight
    

    The base branch is auto-detected from origin/HEAD, falling back to main/master/develop. If the user names a different base, pass it as an argument to preflight and rebase (e.g. ... rebase develop).

    If it exits non-zero because the current branch is the base branch, stop and tell the user — rebasing and force-pushing main itself would rewrite shared history. Ask which feature branch they meant.

    If it reports STATUS: ready-stacked, switch to the stack path above and ignore the remaining steps here.

  2. Rebase:

    bash "$SKILL_DIR/scripts/rebase-sync.sh" rebase
    

    Uncommitted work is stashed automatically (--autostash) and restored by git as soon as the rebase finishes, so you don't need to manage the stash.

  3. If exit code is 10, there are conflicts. The script prints the conflicted files and leaves the rebase in progress. Resolve them yourself:

    • Read each conflicted file and understand both sides. The user's own commits are being replayed on top of the base, so "ours" is the base branch's version and "theirs" is the commit being replayed — this is inverted compared to a merge, and getting it backwards silently drops their work.

    • Keep both intents where they're compatible rather than picking a side wholesale. If two people edited neighbouring lines, the answer is usually both edits, not one.

    • git add each file, then:

      bash "$SKILL_DIR/scripts/rebase-sync.sh" continue
      

    A rebase replays commits one at a time, so continue may hit conflicts again and exit 10 again. Loop until it reports STATUS: rebased.

    If a conflict is genuinely ambiguous — you can't tell which behaviour the user wants — don't guess. Explain the choice and ask. rebase-sync.sh abort restores the pre-rebase state cleanly if they'd rather handle it themselves.

  4. Confirm before pushing. Force-pushing rewrites the remote branch, so show the user what happened and get an explicit go-ahead first:

    • which commits are now on top of the base (the script prints them)
    • which conflicts you resolved, and how you resolved each one — this is the part they most need to sanity-check, since a wrong resolution looks like a clean rebase
    • that the next step force-pushes origin/<branch>

    Skip this confirmation only if the user already said to push without asking (e.g. "rebase and force push it").

  5. Push:

    bash "$SKILL_DIR/scripts/rebase-sync.sh" push
    

    This uses --force-with-lease (plus --force-if-includes when git supports it) — never a bare --force.

    If it reports push-rejected, someone else pushed to this branch and the script lists the commits that a force-push would destroy. Stop there. Do not escalate to --force, and note that re-running step 2 does not help — rebase only fetches the base branch, so it won't pick up commits made on the feature branch itself. Show the user the listed commits and let them decide (typically: coordinate with whoever pushed, or git rebase origin/<branch> to put their own work on top of it).

Reporting back

Keep the summary short and factual: base branch and its new tip, how many commits were replayed, conflicts resolved (file + one line on the resolution), and the push result. If anything was left undone — aborted rebase, rejected push — say so plainly rather than implying success.