[Git] Error: cannot rebase — You have unstaged changes — How to Fix It

Summary

The error error: cannot rebase: You have unstaged changes — clean your working directory before rebasing appears when Git detects modified files that have not been staged or committed. To avoid overwriting or losing these edits, Git blocks the rebase until the working directory is clean. The correct solution is to either commit, stash, or discard all local modifications before resuming the operation.

Context

Rebasing in Git replays commits from one branch onto another, creating a linear history. Because this process rewrites commit ancestry, Git must operate from a pristine working directory to ensure that diffs apply correctly. If local modifications are present, conflicts could occur or untracked work could be lost. This safeguard applies to all major environments — Windows, macOS, Linux, Git Bash, and IDEs such as VS Code — and prevents users from corrupting repository history when history rewriting is involved.

Probable Cause

  • Unstaged local file edits blocking the start of a rebase operation.
  • Residual changes from a previous incomplete merge or cherry-pick.
  • Automated formatters or linters altering files between commits.
  • Temporary debugging or test edits not committed before rebasing.

Quick Fix

Resolve the issue by cleaning your working directory. Use one of the following approaches depending on whether you want to keep, save, or discard your edits:

  1. Check which files are blocking the rebase:
git status
  1. If you want to keep the changes permanently, commit them:
git add .
git commit -m "Save changes before rebase"
  1. If you want to save them temporarily, stash instead:
git stash push -m "temp changes before rebase"
  1. Retry the rebase command:
git rebase origin/main
  1. After completion, restore your stashed work if needed:
git stash pop
  1. If the edits are irrelevant, discard them safely:
git restore .        # for Git ≥ 2.23
# or
git checkout -- .    # for older versions

Full Example

A developer modifies main.py and README.md but forgets to commit them. When running: 

git rebase origin/main

Git halts with: 

error: cannot rebase: You have unstaged changes.
error: Please commit or stash them.

The developer inspects the repository, stashes the edits, performs the rebase, and restores them: 

git status
git stash push -m "temp changes before rebase"
git rebase origin/main
git stash pop

The rebase completes successfully, and the developer’s edits are reapplied on top of the updated branch without loss or conflict.

Pitfalls & Debug

  • Symptom: Rebase aborts repeatedly → Fix: Ensure no untracked files remain (git clean -fd).
  • Symptom: Stash not restored → Fix: Reapply manually with git stash list and git stash apply.
  • Symptom: IDE auto-saves reintroduce changes → Fix: Temporarily disable auto-format or watcher extensions.
  • Symptom: “Cannot apply stash” → Fix: Resolve conflicts, commit manually, and drop the stash.
  • Symptom: Detached HEAD after rebase → Fix: Use git switch <branch> to return to the target branch.

Validation & Next Steps

Verify that your repository is clean before rebasing: 

git status

It should display “working tree clean”. After finishing, confirm linear commit structure: 

git log --graph --oneline

Adopt a workflow that always commits or stashes edits before starting history-altering operations like rebase, merge, or cherry-pick.

Sources

Git official documentation — git-rebase
Pro Git Book — Rebasing section
Stack Overflow — discussions on unstaged changes blocking rebase
Atlassian Tutorials — Stashing and cleaning workflow

Labels: Tool/Git, OS/Windows-macOS-Linux, Topic/Rebase