git-rebase-sync（git 变基同步）

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).

1. 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?"

1. Apply the resolution, then stage only resolved files:

- git add <file...>

1. Continue:

- git rebase --continue

1. 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.