nsheaps/rebase

Rebase Branch

Rebase a feature branch onto its base branch to produce a clean, linear commit history.

Pre-fetched Context

Current branch: !git branch --show-current 2>/dev/null || echo "(not in a git repo)"

Working tree status: !git status --porcelain 2>/dev/null | head -5; COUNT=$(git status --porcelain 2>/dev/null | wc -l); [ "$COUNT" -gt 5 ] && echo "... and $((COUNT - 5)) more" || true

PR info for current branch: !gh pr view --json baseRefName,headRefName,number,title,state 2>/dev/null || echo "(no PR found or gh not authenticated)"

Overview

This skill rebases a feature branch on top of its base branch instead of merging. Use rebase when:

• The project or user prefers linear history (no merge commits)
• A PR review requested rebasing before merge
• Cleaning up history before final merge

Key difference from update-branch: The update-branch skill uses git merge (preserves history, no force push needed). This skill uses git rebase (rewrites history, requires force push).

Input Resolution

Default behavior (no arguments): Use the current directory, get the current branch via git branch --show-current, find the associated PR via gh pr list --head <branch>, and rebase onto the PR's base branch.

Determine the target branch from the provided input. Accept any of:

| Input Type | Example | Resolution | | ----------- | -------------------------------------- | ------------------------------------------------------- | | No input | (empty) | Current directory → current branch → find PR → rebase | | PR number | 123, #123 | gh pr view 123 --json headRefName,baseRefName | | PR URL | https://github.com/org/repo/pull/123 | Parse number, use gh pr view | | Branch name | feature/my-branch | Use directly, find PR with gh pr list --head <branch> | | Directory | /path/to/repo | cd there, get current branch, find PR |

Critical: Always query the PR to determine the base branch. Never assume main or master.

# Get branch info from PR
gh pr view <number> --json headRefName,baseRefName,number,url

# Find PR for a branch
gh pr list --head <branch-name> --json number,baseRefName --limit 1

Rebase Workflow

Execute these steps in order:

Step 1: Pre-flight Checks

Ensure the working tree is clean before rebasing:

git status --porcelain

If there are uncommitted changes, stop and ask the user whether to stash, commit, or abort. A rebase with a dirty working tree will fail.

Step 2: Fetch Latest

git fetch --all --prune

Step 3: Get Base Branch from PR

BASE_BRANCH=$(gh pr view <number> --json baseRefName --jq '.baseRefName')

If no PR exists for the branch, ask the user what the base branch should be.

Step 4: Ensure on Correct Branch

git checkout <feature-branch>

Step 5: Pull Remote Feature Branch Changes

Before rebasing, incorporate any remote changes to the feature branch:

git pull origin <feature-branch> --rebase

Step 6: Rebase onto Base Branch

git rebase origin/$BASE_BRANCH

If conflicts occur, see Conflict Resolution.

Step 7: Force Push with Lease

Since rebase rewrites history, a force push is required. Always use --force-with-lease to prevent overwriting others' work:

git push --force-with-lease origin <feature-branch>

NEVER use --force — --force-with-lease will fail safely if the remote has commits you haven't seen.

Step 8: Verify

Confirm the remote branch is updated:

gh pr view <number> --json commits,mergeable,mergeStateStatus

Conflict Resolution

Rebase applies commits one at a time, so conflicts must be resolved per-commit.

During Rebase Conflicts

When a conflict occurs mid-rebase:

# See which files conflict
git diff --name-only --diff-filter=U

# After resolving conflicts in a file
git add <file>

# Continue the rebase
git rebase --continue

To abort and return to the pre-rebase state:

git rebase --abort

Obvious Conflicts

Resolve directly when the conflict is clearly one of:

• Formatting differences (whitespace, line endings)
• Simple additions that don't overlap semantically
• Deleted code that was also modified (keep modification or deletion based on intent)
• Import statement ordering

Non-Obvious Conflicts

For conflicts requiring analysis, delegate to specialized agents:

1. Use Explore agent with haiku model to understand:

   • What each side of the conflict is trying to accomplish
   • The history of the conflicting changes
   • Related code that might inform the resolution

2. Use Plan agent to determine:

   • The correct resolution strategy
   • Whether both changes can coexist
   • If architectural decisions are needed

3. Execute the resolution — the executing agent owns the final resolution.

4. Stage and continue:

   git add <resolved-files>
   git rebase --continue
   

5. Verify the resolution — run tests or builds after the full rebase completes.

For detailed conflict patterns, see the update-branch skill's references/conflict-resolution.md.

Safety Rules

Only modify the requested branch:

• ONLY rebase the specific PR/branch that was requested
• Do NOT recursively rebase parent PRs
• If the base branch is itself a feature branch, rebase onto it as-is

Force push safely:

• ALWAYS use --force-with-lease (never bare --force)
• --force-with-lease fails if the remote has unexpected commits, preventing data loss
• If --force-with-lease fails, fetch and inspect before retrying

Confirm before force pushing shared branches:

• If the feature branch has multiple contributors (check with git log --format='%an' origin/<branch> | sort -u), warn the user that rebase will rewrite their collaborators' history
• Collaborators will need to git pull --rebase or reset their local branch after the force push

Preserve all commits:

• After rebase, verify the same number of feature-branch commits exist (unless squashing was requested)
• Compare git log --oneline origin/$BASE_BRANCH..<feature-branch> before and after

When NOT to rebase:

• The branch is shared with other active contributors (prefer merge)
• The branch has already been merged elsewhere
• The user explicitly asked for merge (use update-branch skill instead)

Completion Messaging

When reporting completion, be explicit about what happened:

Do say: "Rebased feature branch onto main — force pushed with lease to update remote"

Don't say: "Branch updated" (ambiguous — could be merge or rebase)

Error Handling

| Error | Resolution | | ----------------------------- | ---------------------------------------------------------- | | No PR found for branch | Ask user for base branch, or create PR first | | Dirty working tree | Ask user to stash or commit first | | Rebase conflicts | Resolve per-commit, then git rebase --continue | | --force-with-lease rejected | Fetch, inspect new remote commits, ask user how to proceed | | Rebase produces empty commits | Use git rebase --skip for truly empty commits | | Authentication failure | Ensure gh and git are authenticated |

CI/Remote Environment Usage

This skill works identically in CI and local environments:

• Use git directly for all operations
• Git identity configuration is outside this skill's scope
• The CI environment should configure user.name and user.email appropriately