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
- 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
- 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).
- 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.
- 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).
- 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}
- Conflict handling loop
When conflicts happen:
-
Collect context:
-
git status
-
Identify conflicted files (from status output).
-
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?"
-
Apply the resolution, then stage only resolved files:
-
git add <file...>
-
Continue:
-
git rebase --continue
-
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)
- 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.
- 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.