git-rebase-sync

Use this skill when you need to sync a feature branch onto the latest

origin/{base_branch}

via git rebase, including conflict resolution with explicit clarification questions when intent is ambiguous.

Goals

• Rebase the current branch onto a specified base branch (often the repo default branch like

  dev

  or

  main

  ).
• Resolve conflicts deliberately, without guesswork.
• Keep safety rails: backup ref, confirmations before history-rewriting commands, and safe pushing.

Hard Rules

• Do not create or switch to a different feature branch. Operate on the current branch name unless I explicitly ask otherwise.
• Before any history-rewriting command (

  git rebase ...

  ,

  git push --force*

  ), print the exact command(s) you will run and wait for my confirmation.
• Create a local backup ref (prefer an annotated tag) before starting the rebase. Do not push backup refs unless I explicitly ask.
• Prefer

  git push --force-with-lease

  , never plain

  --force

  .
• If the correct conflict resolution is unclear, stop and ask a targeted question. Do not invent product behavior.

Workflow

1) Identify base + branch

• Determine the current branch:

  • git branch --show-current

• Determine the base branch you will rebase onto:
  • If not provided, use GitHub default branch:

    • gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

• Fetch latest:

  • git fetch origin

2) Preflight safety checks

• Ensure the working tree is clean and there is no operation in progress:

  • git status

• If

  git status

  indicates an in-progress merge/rebase/cherry-pick, stop and ask what to do (abort vs continue).

3) Create a local backup ref (do not push)

• Create an annotated tag at current

  HEAD

  :

  • git tag -a {branch_name}-rebase-backup-$(date +%Y%m%d-%H%M%S) -m "pre-rebase backup" HEAD

• Record the tag name as

  {backup_ref}

  for recovery.

4) Choose rebase mode (normal vs preserve merges)

• Check whether the branch contains merge commits:

  • git rev-list --count --merges origin/{base_branch}..HEAD

• If merge commits exist, ask whether to preserve them (

  --rebase-merges

  ) or flatten them (plain rebase).

5) Run the rebase (requires confirmation)

• Print the exact command you intend to run, then wait for confirmation:
  • Typical:

    • git rebase origin/{base_branch}

  • With merge preservation:

    • git rebase --rebase-merges origin/{base_branch}

6) Conflict handling loop

When conflicts happen:

1. Collect context:

   • git status

   • Identify conflicted files (from status output).
2. For each conflicted file:
   • Open the file and understand the surrounding code and intent.
   • Prefer minimal, mechanical conflict resolutions:
     • Keep upstream changes unless the feature branch deliberately supersedes them.
     • Re-run generators (lockfiles, codegen) instead of hand-editing when appropriate.
   • If intent is ambiguous, ask a single targeted question, for example:
     • "Should we keep the new upstream behavior X, or keep the feature behavior Y?"
     • "Is this file generated and safe to regenerate, or do you want manual resolution?"
3. Apply the resolution, then stage only resolved files:

   • git add <file...>

4. Continue:

   • git rebase --continue

5. If you reach a point where resolution is too risky/unclear:
   • Stop and ask; optionally propose aborting the rebase.

Helpful commands during conflicts:

• Inspect current conflict hunks:

  git diff

• See the commit being replayed:

  git show

• If you need to back out:

  git rebase --abort

  (this is safe and should be preferred over destructive resets)

7) Post-rebase verification

• Show the new commit range:

  • git log --oneline --decorate origin/{base_branch}..HEAD

• Run appropriate repo checks (tests, typecheck, lint) if available.

8) Push updated branch (requires confirmation)

• If the branch already exists on origin, rebasing rewrites history, so pushing requires force-with-lease.
• Print the exact command and wait for confirmation:

  • git push --force-with-lease origin HEAD:{branch_name}

Recovery

• If something goes wrong, use

  {backup_ref}

  to restore the pre-rebase state.
• Do not run destructive commands (e.g.,

  git reset --hard

  ) unless I explicitly confirm after you show the exact command.