If you use Git regularly, you’ve probably seen the message:
“Please commit your changes or stash them before you merge.”
At first, it might sound confusing or even frustrating — especially when you’re in the middle of switching branches or pulling updates. But this is one of those Git messages that makes perfect sense once you understand what’s happening under the hood.
In this post, we’ll break down what this message means, why it appears, and how to fix it safely without losing your work.
What the Message Actually Means
When you see “Please commit your changes or stash them before you merge”, Git is telling you that you currently have uncommitted changes in your working directory, and you’re trying to perform an action that could overwrite or conflict with those changes.
The two most common scenarios are:
- You’re trying to merge another branch into your current one.
- You’re trying to switch branches (checkout) while having uncommitted work.
Git is designed to protect your work. So, before it performs a merge or checkout, it checks if you have any local changes that aren’t saved in a commit. If you do, Git stops and throws this warning.
Why Git Prevents the Merge
Imagine you’re working on a feature and have edited several files. Meanwhile, another developer has updated those same files on a different branch.
If Git allowed you to merge without committing, it could easily mix up these two sets of changes — creating conflicts and potentially overwriting your work.
So, Git requires that your current work is either:
- Committed (saved in your branch’s history), or
- Stashed (temporarily put aside in a safe place).
This ensures that no progress is lost and the repository remains in a clean, consistent state.
How to Check What’s Causing the Error
Before you do anything, it’s smart to see what changes are currently uncommitted.
Run:
git status
This command shows:
- Which files you’ve modified
- Which files are staged (ready to be committed)
- Which files are not tracked
You’ll likely see something like:
On branch feature/login
Changes not staged for commit:
modified: app.js
modified: styles.css
This output confirms you have uncommitted changes.
Option 1: Commit Your Changes
If your work is complete or at a point where you want to save it, the simplest solution is to commit your changes.
Steps:
Stage all changes:
git add .
Commit them:
git commit -m “Your commit message here”
Proceed with your merge or checkout:
git merge branch-name
or
git checkout branch-name
By committing, you’re saving your work permanently in your branch’s history.
Option 2: Stash Your Changes
If you’re not ready to commit yet — maybe you’re experimenting or want to test something on another branch — you can stash your changes.
Stashing means Git saves your uncommitted work temporarily and restores your workspace to a clean state.
To stash your changes:
git stash
Now, your working directory is clean, and you can safely merge or switch branches.
When you’re ready to bring back your changes, simply run:
git stash pop
That command reapplies the stashed changes on top of your current branch.
If you want to see all your stashes, you can use:
git stash list
And if you want to keep a stash for later without applying it immediately:
git stash apply stash@{0}
Option 3: Discard Changes (Use with Caution)
If the changes in your working directory are not important and you simply want to discard them, you can reset your workspace.
To discard all uncommitted changes:
git restore .
or (for older versions of Git):
git checkout — .
Be careful — this deletes your local modifications permanently.
If you’ve added files to the staging area (with git add), you’ll also need to unstage them first:
git reset
Example Scenario
Let’s go through a real-world example.
You’re working on a feature branch feature/dashboard and you’ve modified two files:
- dashboard.html
- main.js
Then you try to run:
git merge main
Git responds with:
error: Your local changes to the following files would be overwritten by merge:
Please commit your changes or stash them before you merge.
In this case, you can either:
Commit your changes:
git add .
git commit -m “Work in progress on dashboard”
git merge main
Or stash your changes:
git stash
git merge main
git stash pop
Both will solve the issue cleanly without losing your work
Best Practices to Avoid This Error
- Commit Frequently
Make small, meaningful commits often. This keeps your working directory clean and your history easy to understand. - Use Feature Branches
Keep your work isolated from the main branch by creating new branches for each feature or fix. - Pull and Merge Regularly
Sync your branch with the main branch often. This prevents large, complicated merges later. - Use Git Status Before Switching Branches
Always run git status before changing branches to ensure you’re not leaving uncommitted changes behind. - Name Your Stashes Clearly
You can name your stashes for better tracking:
git stash push -m “Work on dashboard layout”
Common Mistakes to Avoid
- Committing Unfinished Work:
Don’t commit just to “get rid” of the warning. It’s better to stash if your work is incomplete. - Forgetting to Pop Your Stash:
If you stash your work, remember to reapply it later. Otherwise, you might lose track of it. - Mixing Commit and Stash:
Don’t commit some files and stash others unless you’re confident in what you’re doing. It can cause confusion later.
Final Thoughts
The “Please commit your changes or stash them before you merge” message is not an error — it’s a safeguard. Git is protecting your progress from being lost or overwritten.
Once you understand the reason behind it, handling it becomes second nature. Whether you choose to commit, stash, or discard, the key is knowing when and why to use each method.
Following clean Git practices — committing regularly, stashing wisely, and checking your status before major operations — will save you time, prevent errors, and make your workflow smoother.
In the end, this small Git message is a helpful reminder to keep your work organized and your repository clean.