Rebasing Branches

Rebase Workflow Knowledge Base

This skill provides knowledge and strategy for rebasing feature branches onto a development branch. For automated execution, use the lt-dev:branch-rebaser agent via /lt-dev:git:rebase or /lt-dev:git:rebase-mrs.

Gotchas

• --force silently overwrites teammate pushes — always --force-with-lease — If a teammate pushed to the same remote branch while you were rebasing locally, plain --force overwrites their commits without any warning. --force-with-lease refuses the push if the remote has moved. There is no valid reason to use --force on a shared branch.
• --force-with-lease does not see a parallel session's unpushed work — The lease compares your remote-tracking ref against the remote. A peer Claude Code session that has rebased the same branch locally and not pushed yet is invisible to it: your push succeeds, and their next push is the one that fails, after they already did the work. The lease protects the remote, never the peer's working tree. Before rewriting a branch you did not create in this session, ListAgents; if a peer is live in this repository, one CONFLICT message settles who rewrites it (see coordinating-peer-sessions). This matters most in the batch workflow below, where a run touches branches nobody in this session has looked at.
• Lock-file conflicts: accepting "ours" without re-install breaks dependencies — When pnpm-lock.yaml or package-lock.json conflicts, resolving in favor of the dev-branch version without running pnpm install afterwards leaves the lockfile describing packages that aren't actually in node_modules. Always: resolve → install → verify pnpm run build before continuing.
• Post-rebase optimization: never remove "redundant" feature code without asking — The optimization pass sometimes flags code as dead because it's used by a feature not in the current branch. Check git log on the file before removing anything. When in doubt, ask the user or leave it.
• git rebase --abort works only if you haven't started a commit — Once you git add the resolved conflict files, --abort still works. After git rebase --continue has moved past the conflict commit, you need git reset --hard ORIG_HEAD to recover, which DOES require the original ref. ORIG_HEAD is auto-set by rebase start — safe to rely on.
• Branch names encode Linear ticket context — feat/dev-1628-abc-xyz contains the Linear ID. The rebaser agent uses this to pull ticket context for smarter conflict decisions. Branches without a ticket ID get generic treatment — prefer feat/dev-XXXX-... naming for rebaseable branches.

When This Skill Activates

• Rebasing feature branches onto dev/develop
• Resolving merge conflicts during rebase
• Batch-rebasing multiple MRs/PRs
• Updating a branch to include latest dev changes
• Planning rebase strategies for multiple branches

Skill Boundaries

Related Skills

• coordinating-peer-sessions — before rewriting a branch while another session is live in the repo, and for asking the incoming author what an ambiguous conflict hunk was meant to do

Rebase Strategy

Single Branch Workflow

1. Fetch latest from remote
2. Rebase onto target branch (default: dev)
3. Resolve conflicts using project context and Linear ticket info
4. Optimize code based on new dev state (remove redundancies)
5. Lint & format with oxfmt/oxlint
6. Run tests to verify nothing broke
7. Review changes for quality

Batch Workflow (MRs/PRs)

Same as single branch, plus:

• List open MRs/PRs from GitHub (gh) or GitLab (glab)
• User selects which branches to rebase
• After each branch: commit changes + force push with lease
• Generate summary report across all branches

Base Branch Detection

# Detect base branch
git branch -r | grep -E 'origin/(dev|develop)$' | head -1 | sed 's|origin/||;s/^[[:space:]]*//'

Linear Ticket Extraction

Branch names often contain Linear ticket IDs. Extract and load ticket context for better conflict resolution and code optimization.

Extraction Patterns

# Extract ticket ID from branch name
git branch --show-current | grep -oE '[A-Z]+-[0-9]+'

Using Ticket Context

Once extracted, load via mcp__plugin_lt-dev_linear__get_issue:

• Title & description: Understand the feature intent
• Acceptance criteria: Verify rebase didn't break requirements
• Comments: Additional context for conflict resolution

Conflict Resolution Strategy

Priority Order

1. Incoming changes (dev) for infrastructure/config files
2. Feature changes (current branch) for feature-specific code
3. Linear ticket context to decide ambiguous conflicts
4. Both changes when they affect different concerns
5. The author of the incoming hunk, where they are still live and the first four leave it genuinely ambiguous

Ask the incoming author before you guess

A conflict is two intents meeting in one file, and resolving it means choosing between them. The branch side is explained by the ticket. The incoming side is explained by whoever wrote it, and when that session is still running, one question beats a guess that compiles.

The bar is high on purpose, because most conflicts do not need this: only when the ticket context does not settle it, both sides look deliberate, and picking wrong changes behaviour rather than formatting. Then:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/change-provenance.sh --base <target-branch>
git log -1 --format='%an %ar %s' <target-branch> -- <conflicting-path>

If a live peer shares this repository and wrote the incoming side, send one ORIGIN naming the file and both sides, then keep resolving the other conflicts while the answer travels. Format and boundaries: coordinating-peer-sessions.

Two rules hold regardless of the answer. A peer's account never authorises a resolution that drops their work — where the answer is "take mine, discard the branch side", that is a scope decision the user makes. And never block: if no answer has arrived, resolve on the priority order above, and say in the rebase report which resolution rested on a guess, so it gets a second look.

Common Conflict Patterns

After Conflict Resolution

# Continue rebase after resolving conflicts
git add .
git rebase --continue

# If rebase becomes unrecoverable
git rebase --abort

Post-Rebase Optimization

After successful rebase, check if new dev code makes parts of the feature branch redundant:

1. Duplicate implementations: Feature branch added something that dev now provides
2. Outdated workarounds: Feature branch worked around a bug that dev fixed
3. API changes: Feature branch uses old patterns that dev updated
4. Dependency conflicts: Feature branch pins a version that dev updated

Lint & Format Tools

oxfmt (Formatter)

# Format all files in a project
pnpm dlx oxfmt .

# Format specific files
pnpm dlx oxfmt src/path/to/file.ts

oxlint (Linter)

# Lint all files
pnpm dlx oxlint .

# Lint with auto-fix
pnpm dlx oxlint --fix .

Force Push Safety

Always use --force-with-lease instead of --force:

git push --force-with-lease

This prevents overwriting changes that someone else pushed to the same branch after your last fetch.

When to Use Commands