playbooks

home / skills / jmerta / codex-skills / rebase-assistant

rebase-assistant skill

/rebase-assistant

This skill guides a safe git rebase of your current branch onto a target branch, with built-in conflict resolution guidance.

npx playbooks add skill jmerta/codex-skills --skill rebase-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: rebase-assistant
description: Guide a safe git rebase of the current branch onto a target branch, including conflict triage and resolution steps. Use when asked to rebase, update a branch, or resolve rebase conflicts.
---
# Rebase assistant

## Goal
Rebase the current branch onto a target branch safely, with built-in conflict resolution guidance.

## Inputs to confirm (ask if missing)
- Target branch (explicit branch name or "default branch").
- Preferred conflict bias when ambiguous: keep ours, keep theirs, or manual merge.
- Protected paths or file types to avoid touching.

## Workflow
1) Identify the target branch
   - If user says "default branch": discover via `git remote show origin` (read "HEAD branch").
   - If ambiguous or no remote: ask the user which branch to use.
2) Preflight checks
   - `git status -sb` (must be clean before rebase).
   - `git fetch --prune` to sync remotes.
   - Optional safety branch (ask before creating): `git branch backup/<current-branch>`.
3) Start the rebase
   - `git rebase <target-branch>`
4) If conflicts occur, resolve (repeat per file)
   - Inspect conflict list:
     - `git status -sb`
     - `git diff --name-only --diff-filter=U`
   - Classify and inspect:
     - Content conflicts: open file, resolve markers.
     - Delete/modify or rename conflicts: decide keep vs delete explicitly.
     - Binary conflicts: choose ours/theirs only.
   - Show base/ours/theirs when useful:
     - `git show :1:<path>`
     - `git show :2:<path>`
     - `git show :3:<path>`
   - File-level choice when safe:
     - `git checkout --ours <path>`
     - `git checkout --theirs <path>`
   - Stage resolved files: `git add <path>`
   - Continue: `git rebase --continue`
5) Finish and verify
   - Ensure no conflicts: `git status -sb`
   - Suggest a fast test/build if available.

## Safety rules
- Never run `git reset --hard`, `git clean -fd`, or `git rebase --abort` unless the user explicitly requests it.
- Always show candidate commands before applying destructive changes.

## Deliverables
- The exact rebase command used and target branch.
- Conflict list grouped by type with per-file resolution guidance.
- Completion command and a short verification suggestion.

Overview

This skill guides a safe git rebase of the current branch onto a chosen target branch, with conflict triage and step-by-step resolution instructions. It focuses on preflight checks, clear candidate commands, and non-destructive conflict handling to protect work and history.

How this skill works

The assistant confirms the target branch and preferred conflict bias, runs preflight checks (clean status, fetch, optional backup branch) and provides the exact rebase command to run. If conflicts appear, it lists conflicted files, groups them by conflict type, and gives per-file resolution guidance including commands to inspect base/ours/theirs, safe checkout choices, staging, and how to continue the rebase. It finishes with verification and suggested quick tests.

When to use it

  • You need to rebase the current feature branch onto the default or a specific target branch.
  • You want guided conflict resolution during an in-progress rebase.
  • You need help deciding keep-ours vs keep-theirs for ambiguous conflicts.
  • You want to create a safety backup branch before rebasing.
  • You prefer stepwise, non-destructive commands and explicit confirmation before destructive actions.

Best practices

  • Ensure working tree is clean before starting (git status -sb).
  • Fetch remotes first (git fetch --prune) and confirm the correct target branch.
  • Ask to create a local backup branch (git branch backup/<current-branch>) before rebasing.
  • Avoid automatic destructive commands; show them and request explicit permission if needed.
  • Classify conflicts (content, delete/modify, rename, binary) and apply file-level decisions.

Example use cases

  • Rebase a feature branch onto origin/main while preserving local changes.
  • Triage multiple conflicted files after running git rebase origin/main.
  • Choose a consistent bias (keep ours/theirs) for bulk-file conflicts like generated assets.
  • Resolve a binary-file conflict by explicitly choosing ours or theirs.
  • Create a backup branch, rebase interactively, and run a quick build to verify.

FAQ

What do you need before starting a rebase?

Confirm the target branch (or resolve default branch via remote), preferred conflict bias, and whether to create a backup branch. Ensure the working tree is clean and remotes are fetched.

Can you run destructive commands for me?

No. The skill will show candidate destructive commands (reset --hard, clean -fd, rebase --abort) but will not run them unless you explicitly request and confirm.