branch-rebase

Safely rebase the current branch onto its upstream target, auto-resolving trivial conflicts and prompting for complex ones. Use when the user says "rebase", "rebase onto main", "update my branch", "sy

SKILL.md

GitHub

Branch Rebase

Rebase the current feature branch onto its upstream target with automatic resolution of trivial conflicts.

Invocation

/rebase-branch [target]
  • target — branch to rebase onto. Defaults to the first of baseline, main, master that exists.

Workflow

Follow every step in order. Do not skip steps. Do not push at the end.

1. Validate environment

git rev-parse --is-inside-work-tree

If not a git repo, stop and tell the user.

2. Detect branches

CURRENT=$(git branch --show-current)

If CURRENT is empty (detached HEAD), stop: "You are in detached HEAD state. Check out a branch first."

If a target argument was provided, use it. Otherwise detect the target:

for candidate in baseline main master; do
  if git show-ref --verify --quiet "refs/heads/$candidate" || \
     git show-ref --verify --quiet "refs/remotes/origin/$candidate"; then
    TARGET=$candidate
    break
  fi
done

If no target found, stop: "Could not find baseline, main, or master. Specify a target branch."

If CURRENT equals TARGET, stop: "You are already on the target branch."

3. Check for uncommitted changes

git status --porcelain

If output is non-empty, stop immediately and tell the user:

You have uncommitted changes. Please commit or stash them before rebasing.

List the dirty files so they can decide. Do not proceed.

4. Update the target branch

git checkout $TARGET
git pull --ff-only

If the pull fails (e.g. diverged local target), warn the user and ask whether to continue or abort.

5. Return to feature branch and rebase

git checkout $CURRENT
git rebase $TARGET

If the rebase completes cleanly, skip to step 7.

6. Resolve conflicts

If the rebase stops with conflicts, read CONFLICTS.md: version-only and different-version changelog conflicts auto-resolve; everything else goes to /branch-resolve-conflicts (or git rebase --abort if the user prefers). Repeat for each conflicting commit.

7. Post-rebase version bump and changelog

If the repo has a version manifest (build.gradle(.kts), pom.xml, package.json, *.csproj) or a changelog, read VERSIONING.md. The branch must end with a version distinct from the target's and its own changelog section; any fixup is a separate chore: commit at the tip. Otherwise skip to step 8.

8. Report success

Tell the user:

Rebase complete. {CURRENT} is now based on {TARGET}.

If a version bump or changelog update was made, list exactly what changed:

  • Version bumped: {OLD} → {NEW} in build.gradle
  • New changelog section added for {NEW}

Then:

Your branch has not been pushed. When you're ready:

git push --force-with-lease

List any files that were auto-resolved during conflict resolution so the user can verify.

Important rules

  • Never push. The user decides when and how to push.
  • Never use --force. Only suggest --force-with-lease in the final message.
  • Never amend or squash commits during this workflow.
  • If anything unexpected happens (network errors, lock files, hook failures), stop and report rather than retrying destructively.
  • Prefer git rebase --abort over leaving the repo in a broken state.

Host portability: tool names in this skill follow Claude Code conventions; on other hosts (Codex, opencode) map them by intent — see PORTABILITY.md.

<!-- self-evolve:start -->

Self-Evolve Loop

Journal ~/.ink-and-agency/learnings/branch-rebase.md (or workspace-local .ink-and-agency/ where the sandbox confines writes). Read it first; append what the run taught — SELF-EVOLVE.md.

<!-- self-evolve:end -->