Git Your local changes to the following files would be overwritten by merge Solution

You cannot pull code from a remote repository if there are any conflicts between uncommitted changes you have made on your local machine and the contents of the remote repository. This protects you from overwriting code you want to keep.

In this guide, we discuss the “Your local changes to the following files would be overwritten by merge” error and why the error is raised. We’ll also walk through an example so you can learn how to solve this error.

Your local changes to the following files would be overwritten by merge

Your local version of a repository will often be different than that of a remote repository. This is a core feature of Git: you can make changes locally without pushing them to the remote repository until you are ready.

When you pull code from a remote repository, Git will retrieve the contents of that repository and save them to your local machine. This can only happen if you have committed all of the changes to files that you want to save.

If you try to pull code without first committing changes, you may see the “Your local changes to the following files would be overwritten by merge” error. This will only happen if you have modified a file that has also been changed in the remote version of the repository.

An Example Scenario

Let’s make a revision to a Git repository called ck-git. First, let’s clone a copy of this repository:

git clone https://github.com/career-karma-tutorials/ck-git

We now have a copy of the repository on our local machine. This repository contains one file: README.md. Its contents are:

# ck-git

We are going to go to GitHub and modify this file on the server. Our file now contains the contents:

# Career Karma Git

Our local version of the repository is now different from the origin master branch on the remote version of the repository.

Our version contains the code that was in the remote repository when we pulled the code. The remote repository contains the change that we have made to README.md.

Now, let’s say that we change README.md on our local machine:

# CK Git

We have changed our file. Now, let’s try to pull the changes we made to our remote repository so that we can save them to our local machine:

git pull

This command returns an error:

...
Updating a30b784..ec281fc
error: Your local changes to the following files would be overwritten by merge:
    README.md
Please commit your changes or stash them before you merge.
Aborting

We have shortened the response of this command for brevity. The message we should focus on is “Your local changes to the following files would be overwritten by merge”.

The Solutions

There are now two copies of our file: the one on our local machine and the one in our remote repository. When we pull our code from our remote repository, Git is unsure what version of the file should remain.

To solve this error, we can either stash our code or commit our code.

To commit our code, we can add our README.md file to a commit and create a commit containing that file:

git add README.md
git commit -m "docs: Update README.md"

This will add the changes we made to README.md on our local machine to the commit history of our project. Git will now know that we want to keep these changes.

The second solution is to stash our changes. This lets us save our changes for later viewing. We can stash our code using the git stash command:

git stash

This command saves our change into a stash (our code is “stashed away” for later). Now that we’ve stashed our code, we can safely pull the code from our remote repository:

git stash pop

The code in a Git stash can be viewed by running the git stash pop command. This will let us see the changes we’ve made to our file that we did not commit to our repository. This means that if we decide we want to commit the changes to the file later, we can do so.

Conclusion

The “Your local changes to the following files would be overwritten by merge” error occurs when you try to pull a remote repository to your local machine whose contents conflict with the contents of your local version of the repository.

To fix this error, either stash your changes away for later or commit your changes. Now you have the knowledge you need to fix this error like an expert!