Rebase On Main

Non-Negotiables

• Prefer safety over completion. If resolving a conflict could overwrite work, remove functionality, or requires product/code intent you cannot infer, stop and ask the user a specific question.
• Always create a backup before rewriting history.
• Always use --force-with-lease, never --force.
• Do not rebase shared branches, protected branches, or branches with unknown ownership unless the user explicitly approves.
• Preserve functionality from both sides when possible. Never silently drop behavior from either mainline or the feature branch.
• Before a normal rebase or git rebase --continue, set GIT_EDITOR=true. Keep it set through the rebase so Git accepts the existing commit message instead of opening vim, nano, or another interactive editor.
• Report what changed at the end: target branch, commits rebased, conflicts resolved, validation run, and push result.

Locate Bundled Helpers

The scripts below belong to this skill, not to the repository being rebased. Before changing into the target repository, take the absolute path of this loaded SKILL.md from the harness's skill context and derive SKILL_DIR from it. Never run bash scripts/... from the target repository or hard-code a machine-specific skills directory.

# Substitute the absolute SKILL.md path reported by the current harness.
SKILL_FILE="<path reported for this loaded SKILL.md>"
SKILL_DIR="$(CDPATH= cd -- "$(dirname -- "$SKILL_FILE")" && pwd -P)"

Confirm the helpers exist before invoking them. If the harness does not expose a skill path or a helper is unavailable, use the inline fallback in the relevant workflow step; do not stop solely to find the scripts.

Quick Start

export GIT_EDITOR=true
bash "$SKILL_DIR/scripts/pre-rebase-backup.sh"
git fetch origin
git rebase origin/main
bash "$SKILL_DIR/scripts/analyze-conflicts.sh"
# Resolve conflicts intelligently, then:
git add <resolved-files>
git rebase --continue
bash "$SKILL_DIR/scripts/validate-merge.sh"
git push origin "$(git rev-parse --abbrev-ref HEAD)" --force-with-lease

Use origin/master instead of origin/main only when master is the repository mainline.

Workflow

1. Establish context:
   • Run git status --short --branch.
   • Save the current branch with git rev-parse --abbrev-ref HEAD.
   • Refuse to proceed from detached HEAD.
   • Identify mainline from origin/HEAD, then fall back to origin/main, origin/master, main, or master.
2. Check safety:

   • Run bash "$SKILL_DIR/scripts/pre-rebase-backup.sh" when available. Otherwise create the backup inline:

     branch="$(git rev-parse --abbrev-ref HEAD)"
     timestamp="$(date +%Y%m%d_%H%M%S)"
     safe_branch="$(printf '%s' "$branch" | tr '/[:space:]' '--')"
     backup="backup/rebase-${safe_branch}-${timestamp}"
     git branch "$backup"

   • If the working tree has unrelated uncommitted changes, stop and ask before stashing or modifying them.
   • Fetch latest with git fetch origin.
   • Inspect divergence with git log --oneline <target>..HEAD and git log --oneline HEAD..<target>.
3. Choose strategy:
   • Use simple rebase for 1-2 straightforward commits.
   • Use squash-first for 3+ commits or repeated conflicts if the user is willing to trade per-commit history for one conflict-resolution pass.
   • Use interactive rebase when commit order, duplicate commits, or focused cleanup matters.
   • See references/strategies.md.

Squash First

Use this only when the user explicitly asks to squash, or has accepted squashing. After fetching and selecting <target>, squash all feature commits since the merge base into one local commit, then rebase that commit onto the updated target:

base="$(git merge-base HEAD <target>)"
git log --oneline "$base"..HEAD
git reset --soft "$base"
git commit -m "<concise summary of the squashed feature>"
git rebase <target>

Run the backup helper before git reset --soft. Do not use this path if the displayed range contains commits the user intends to retain separately. If the final message cannot be inferred from the commits, ask the user for it.

4. Rebase:
   • Prefer git rebase <target> where target is usually origin/main.
   • If conflicts occur, run bash "$SKILL_DIR/scripts/analyze-conflicts.sh" when available; otherwise run git diff --name-only --diff-filter=U and git status --short --branch.
   • Read every conflicted file before editing. Understand ours and theirs in rebase context before choosing.
   • Resolve by combining intent where possible; do not blindly choose either side.
   • If the correct result is ambiguous, stop and ask the user rather than guessing.
   • Stage resolved files and continue with git rebase --continue.
   • Repeat until the rebase completes.
5. Validate:
   • Run bash "$SKILL_DIR/scripts/validate-merge.sh" when available. Otherwise run git diff --check, ensure git diff --name-only --diff-filter=U is empty, and inspect changed files for conflict markers.
   • Run project-specific checks discovered from the repo, such as tests, lint, typecheck, or targeted tests for changed areas.
   • If validation fails, fix the merged code before continuing or pushing.
6. Push:
   • Push only after validation: git push origin "$(git rev-parse --abbrev-ref HEAD)" --force-with-lease.
   • If --force-with-lease fails, stop. Someone else may have pushed to the branch.

Conflict Resolution Rules

• Keep mainline fixes such as security, migrations, API changes, dependency updates, and bug fixes unless there is a clear reason not to.
• Keep feature-branch behavior that implements the user's work unless it is made obsolete by mainline.
• Remove duplicate code created by combining both sides.
• Add short comments only when the merged logic would otherwise be unclear.
• Do not continue a rebase with unresolved conflict markers, failing syntax checks, or unexplained test failures.

Recovery

• Abort an unsafe rebase with git rebase --abort.
• Recover from the backup branch created by the helper or inline backup command.
• See references/troubleshooting.md for repeated conflicts, bad resolutions, and force-with-lease failures.