Rebase

Rebase the current feature branch onto the target branch with minimal user intervention. Resolve trivial and mechanical conflicts automatically; stop and ask only for overlapping ones with conflicting intent.

Terms

Term	Meaning
`<source>`	Current feature branch being rebased
`<target>`	Branch to rebase onto (default: `master`)
`<split>`	Fork/split point — the last common commit between `<source>` and `<target>`
`<remote>`	Remote name (auto-detected via `git remote`; default: `origin`)
`<backup>`	Safety copy: `<source>-rebase-backup`

When to Use

User asks to rebase, sync, or update a branch against master/main/develop
Branch is behind the base and needs updating before merge

Skip when: user asks for merge (not rebase), or wants interactive rebase (squash/reorder/edit).

Pipeline

Setup → Analyze → Pre-checks → Backup → Rebase → [Conflict loop] → Verify → Report
                                                        ↓ (overlapping)
                                                  Reproduce or ask

At any state the user (or the agent, if stuck) can pick one of:

Try — agent decides the best resolution and applies it
Abort — rollback to the backup branch immediately (see Rollback)

Step 0: Setup

Resolve all parameters before doing anything. Do not proceed until all answers are collected.

Detect <source>: git branch --show-current. Refuse if on master/main.
Detect <remote>: git remote. If multiple remotes, ask user which one. If one, use it.
Resolve <target>. If user provides a simple name without / (e.g., master), ask whether they mean <remote>/master (remote tracking branch) or local master. Recommend remote. Wait for answer.
Announce <backup> name (<source>-rebase-backup) so user can recover manually if the session is lost.
Sync (optional). git fetch <remote> <target> — fetch latest. No local checkout/pull needed, rebase targets <remote>/<target> directly.

Step 1: Branch Analysis

Build a mental model of the branch before touching anything.

Identify <split> — the exact commit where <source> diverged from <target>: git merge-base HEAD <remote>/<target>. Report it to the user (hash + subject line via git log -1 --format="%h %s" <split>).
Read the full commit log from split to HEAD: git log --reverse --format="%h %s" <split>..HEAD.
For each commit, read its diff (git show <hash> --stat + selective git show <hash> -- <file> for non-trivial ones).
Produce a short summary: the branch's goal (what feature/fix it implements), the strategy (how commits build on each other), key files (files most heavily changed), and the split point commit. Present this to the user for confirmation before proceeding.
Squash offer. If more than one commit exists since the split point, recommend squashing — fewer commits means fewer conflict points during rebase (conflicts are resolved per-commit, so N commits can produce N × the same conflict). Ask the user for confirmation. If user agrees:
- Squash all commits into one via git reset --soft <split> && git commit.
- Commit message: concatenate all original messages (deduplicate if identical). Format: first message as subject, remaining as bullet list in body.
- If user declines, proceed with individual commits as-is.

This understanding — especially the split point and per-commit intent — is used in Step 5 to judge whether overlapping changes can be reproduced.

Step 2: Pre-checks

Working directory. Run git status --porcelain. If dirty:
- Unstaged/staged changes → git stash push -m "rebase-skill-auto-stash", note stash was created.
- If stash fails → abort, report why.
Behind check. git rev-list --count HEAD..<remote>/<target>. If 0 → already up to date, skip rebase, report done.

Step 3: Backup

Create a safety copy of the branch before rebase:

git branch <backup>

<backup> is the rollback target. Deleted only after the user confirms the rebase result in Step 7. If anything goes wrong → rollback restores this exact state (see Rollback section).

Step 4: Rebase

Run git rebase <remote>/<target>.

Clean rebase (exit 0): proceed to Step 6 (Verify).

Conflicts (exit non-zero): proceed to Step 5.

Step 5: Conflict Resolution Loop

For each commit that conflicts:

List conflicted files: git diff --name-only --diff-filter=U.
Read each conflicted file. Classify every conflict hunk:

Class	Definition	Action
Trivial	Whitespace-only, import reordering, adjacent non-overlapping lines, auto-generated files (lockfiles, snapshots)	Resolve automatically — accept incoming for generated files, merge both sides for additive changes. `git add <file>`.
Mechanical	Same line changed on both sides but intent is unambiguous (version bump, config value update, renamed identifier used consistently)	Resolve with brief explanation logged to user. `git add <file>`.
Overlapping	Both sides changed the same region with different logic. See Overlapping Resolution below.	Assess reproducibility → auto-resolve or ask.

After all files in the current commit are resolved: git rebase --continue.
Repeat until rebase completes or user requests abort.

Overlapping Resolution

When both sides modified the same code region:

Understand both sides. Using the branch analysis from Step 1, recall why the feature branch made this change. Read the incoming (master) change to understand its intent.
Reproducibility check. Ask: "Can the feature branch's intent be re-applied cleanly on top of master's new version of this code?"
- Yes, reproducible: The feature's change is a local addition/modification whose intent is clear and doesn't conflict with master's new logic. Re-implement the feature's change on top of master's version. Log the before/after and reasoning. git add <file>.
- No, conflicting intent: Master's change and the feature's change pull in different directions (different algorithms, structural rewrites, changed contracts). Stop. Show both versions with context (±5 lines), explain the conflict, and offer the user four options:
  - Keep source — accept <source>'s version
  - Keep target — accept <target>'s version
  - Custom — user provides their own solution (paste or dictate)
  - Abort — rollback the entire rebase
Record every overlapping conflict in the report (file, lines, classification, solution).

Rules:

Never silently discard code. If in doubt, classify as overlapping and assess reproducibility. If still in doubt, ask.
Never auto-resolve test files that assert different values — always ask.
If >5 files conflict in a single commit, summarize the situation before resolving; user may prefer to abort.
If git rebase --continue itself fails, read the error and act accordingly (often a missed file).

Step 6: Verify

git log --oneline -20 — confirm commit history looks correct (feature commits on top of base).
If the project has a quick lint or type-check command visible in package.json scripts or a Makefile, run it. Report pass/fail. Do not block on warnings.
git diff <remote>/<target>..HEAD --stat — show what the branch changes relative to base after rebase.

Step 7: Report

Summary

Commits rebased (count)
Total conflicts (count)
Stash status: restored (git stash pop) or clean
Verification: pass/fail
Backup branch: <backup> (kept until user confirms, then deleted)

Conflict Breakdown

Trivial: N resolved automatically
Mechanical: N resolved automatically

Overlapping Conflicts (detailed)

Each overlapping conflict gets its own entry:

src/checkout.ts L101–130 — Reproduced: re-applied discount logic on top of master's refactored price calc
src/auth.ts L55–72 — Asked user: kept master's session handling, re-added token refresh

Rollback

Available at any point — on user request, abort command, or unrecoverable error:

git rebase --abort (if rebase is in progress)
git checkout <source> and git reset --hard <backup>
If stash was created: git stash pop
Confirm restored state: git log --oneline -5
Delete <backup> only after confirmation: git branch -d <backup>

Behavioral Rules

Understand first. Never start rebase without completing branch analysis. The commit-level understanding drives conflict resolution decisions.
Always recoverable. Backup branch exists before any destructive operation. Rollback is one command away at every step.
Reproduce over patch. For overlapping conflicts, prefer re-implementing the feature's intent on top of master's new code over blindly picking a side. This produces cleaner history.
Ask when intent conflicts. If master's change and the feature's change have incompatible goals, stop and ask. Never silently drop logic from either side.
No side effects. Don't push, don't delete branches (except <backup> after user confirms), don't modify files outside the rebase flow.
Stash hygiene. Always pop or drop the auto-stash when done (success or rollback). Never leave orphan stashes.
Transparency. Log every resolved conflict with classification, file, lines, and reasoning. The final report is the audit trail.
Target override. If user specifies a different <target> (e.g., develop, release/x.y), use it. Default is master.

Refuse

Rebase with --force-push unless user explicitly asks
Interactive rebase (squash, reorder) — out of scope
Rebase of master/main itself
Proceeding after overlapping conflict with conflicting intent without user input
Deleting <backup> before user confirms rebase result

rebase