Victor's room

Overview & Root Cause Summary: The error error: cannot rebase: You have unstaged changes. error: Please commit or stash them occurs when executing git rebase or git pull --rebase while your local working directory contains modified tracked files that have not been committed. Git halts the operation to prevent replayed commit patches from overwriting or corrupting your uncommitted local work.

Understanding the Root Causes

• Dirty Working Tree: Tracked repository files were modified, edited, or partially staged in your working tree without being recorded in a commit prior to initiating the rebase.
• Disabled Autostash by Default: In standard Git configurations, rebase.autoStash is set to false, requiring developers to manually manage their uncommitted changes before rebasing.
• Untracked File Conflicts: An untracked file in your directory matches the path of a file introduced by one of the incoming rebased commits.
• Automated Tool / Linter File Edits: Background code formatters, build tools, or watch daemons modifying files right before the rebase command was invoked.

Step 1: Quick Fix (Use the –autostash Flag or Manual Stash)

Instruct Git to automatically stash your uncommitted changes into a temporary snapshot before rebasing, and restore them once the rebase completes.

# Option A: Execute rebase with the built-in --autostash flag:
git rebase --autostash <upstream_branch>

# Or during a git pull:
git pull --rebase --autostash

# Option B: Manually stash your changes before rebasing:
git stash push -m "WIP before rebase"
git rebase <upstream_branch>
git stash pop

Step 2: Enable Permanent Global Auto-Stashing

Configure Git to always automatically stash and restore uncommitted changes during any rebase or pull operation across all repositories.

# 1. Enable auto-stashing globally for all git rebase commands:
git config --global rebase.autoStash true

# 2. (Optional) Ensure git pull also uses rebase with auto-stash:
git config --global pull.rebase true

# 3. Verify your global configuration:
git config --global --get rebase.autoStash

Step 3: Committing Work-in-Progress or Discarding Scratch Edits

If you prefer to preserve your changes within commit history or discard unneeded local edits, handle your modifications explicitly.

# Option A: Record changes in a temporary WIP commit before rebasing:
git add .
git commit -m "WIP: temporary save before rebase"
git rebase <upstream_branch>
# (After rebase, soft reset to restore uncommitted state if desired: git reset --soft HEAD~1)

# Option B: Discard unwanted local modifications (permanent):
git restore .
git clean -fd
git rebase <upstream_branch>

Verification & Testing Steps

Confirm that the rebase completed cleanly, working tree status is verified, and linear commit history is established.

# 1. Verify repository working tree status:
git status

# 2. Confirm linear commit history following the rebase:
git log --graph --oneline -n 5

# 3. Ensure no dangling stashes were left behind:
git stash list

Summary Comparison Table

Remediation Approach	Command	Working Tree Impact	Recommended Scenario
--autostash Flag	git rebase --autostash	Auto-stashes & restores edits	One-off rebases with active uncommitted work
Global rebase.autoStash	git config --global rebase.autoStash true	Seamless automated preservation	Permanent setup for modern developer machines
Manual Stash	git stash push && git stash pop	Explicit stash stack entry	When you want full control over stash resolution
Temporary WIP Commit	git commit -am "WIP"	Saved directly into Git history	Complex multi-file refactoring in progress