| name | troubleshoot-rebase |
| description | Diagnose and recover from git rebase failures |
Git Rebase Troubleshoot
Diagnose and recover from rebase failures. Invoke when standard rebase error handling cannot resolve the issue.
Quick Diagnosis
Check: pwd, git status, git branch --show-current, git worktree list, gh pr view.
Resolve the repo's default branch before any rebase — it is the correct rebase
target, not necessarily main:
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
main on a git-flow repo (default branch develop, see /gh-cli-patterns
Canonical Default-Branch Detection in github-workflows) is never a rebase
target — it takes merge commits only. Feature branches there rebase onto
develop, and only a hotfix/* branch legitimately rebases onto main.
Error: Push Rejected (Non-Fast-Forward)
Branches have diverged. First, confirm your current branch: git branch --show-current.
-
If this is a feature branch (for example feature/foo) and the push was rejected:
- Rebase onto the latest default branch:
git fetch origin --force && git rebase origin/<DEFAULT_BRANCH>
- Then push your feature branch:
git push --force-with-lease origin HEAD
-
If you are on <DEFAULT_BRANCH> and are behind origin/<DEFAULT_BRANCH>, do
not rebase it:
- Update it:
git fetch origin --force && git reset --hard origin/<DEFAULT_BRANCH>
- Then retry your original operation (for example, rebase your feature branch onto
<DEFAULT_BRANCH> and push the feature branch).
If the rebase fails because origin/<DEFAULT_BRANCH> moved again, repeat: fetch, rebase your feature branch, then push with --force-with-lease.
Error: Repository Rule Violations
GH013 error about PR/status checks. This is NOT a block if commits are from approved PR.
Causes: CI not passing, reviews not approved, merge conflict.
Fix order: Rebase feature -> push (triggers CI) -> wait for checks -> merge to <DEFAULT_BRANCH> -> push.
Check: gh pr view <branch> --json checks,reviews,statusCheckRollup
Error: Embedded Git Repository
Nested .git directory found. Fix: git rm --cached <folder-name> or add to .gitignore.
Rebase Conflict
Identify: git status, git diff --name-only --diff-filter=U
Resolve: edit files, git add <file>, then git rebase --continue (or --abort).
Error: Fast-Forward Merge Failed
The default branch was updated between rebase and merge. Run
git fetch origin --force && git reset --hard origin/<DEFAULT_BRANCH>, then retry.
Error: Feature Branch Push Failed
Fix: git push --force-with-lease origin <branch>
Recovery: Aborting In-Progress Rebase
git rebase --abort && git status
Verification
Before retrying:
- Default branch synced:
git diff origin/<DEFAULT_BRANCH> --stat (should be empty)
- Branch clean:
git status
- No rebase in progress: check
.git/rebase-{merge,apply} doesn't exist
- PR state:
gh pr view <branch> --json state
Escalation
If unresolved: check git reflog, review git log -10 --oneline, ask user.
DO NOT: Use --force (use --force-with-lease), use gh pr merge, run git rebase -i.
Related Skills
- rebase-pr (github-workflows) — Standard rebase-merge PR workflow this skill troubleshoots
- troubleshoot-precommit (git-workflows) — Troubleshoot pre-commit hook failures during rebase
- troubleshoot-worktree (git-workflows) — Troubleshoot git worktree, branch, and refname issues