You cannot modify a file on two branches and switch between those branches without committing or stashing the file. This is because Git is unsure what changes should be saved and what changes should be overwritten.
This guide discusses the “Your local changes to the following files would be overwritten by checkout” error and what it means. We’ll walk through an example so you can figure out how to fix this error.
Your local changes to the following files would be overwritten by checkout
When you navigate to a branch, you can view the repository at a particular time in its history and make the changes you need. You should commit the changes made when you are ready so Git keeps track of the evolution of your project.
You cannot switch between two branches if both branches contain an uncommitted file change. Git needs to know whether a file should be saved or part of a commit. This protects you from accidentally overwriting code you may want to refer back to later.
An Example Scenario
We’re going to clone a repository that contains one file called README.md:
git clone https://github.com/career-karma-tutorials/ck-git
The contents of the README.md file are as follows:
Our repository has two branches: development and master. In our local working directory, we are going to change the README.md file on the origin master branch:
# Career Karma Git
Our master branch is now different from our remote repository. We’re going to switch to our development branch and change the contents of its README to say:
# Career Karma [Development]
We can change this file on the development branch by executing these commands:
git checkout development nano README.md
Next, switch back to the master branch, commit the changes made to the branch, and push them to our remote repository:
git checkout master git add README.md git commit -m "docs: Update README" git push
The git checkout command lets us switch to the master branch. In review, our remote repository now contains:
- A modified README.md on the development branch
- A master branch that is ahead one commit
Now, let’s modify our README.md again on the master branch:
This means both branches contain differences between the remote master branch. Let’s try to switch over to our development branch with these changes in place:
git checkout development
This command returns an error message:
error: Your local changes to the following files would be overwritten by checkout: README.md Please commit your changes or stash them before you switch branches. Aborting
Because our development and master branches contain uncommitted changes, Git cannot proceed with the checkout. If Git proceeded, the uncommitted changes we have made to our README.md on the master branch would not be saved.
We can fix this error in two ways. First, we can commit our changes on the master branch:
git add README.md git commit -m "docs: Add tutorials message to README.md file" git push
In these commands, we add the README.md file to the staging area, add all files from the staging area into a commit, and we push our change to the remote repository.
Git now has a record of how our README.md file appears with the changes that we made.
Alternatively, we could stash our changes for later. This is a good solution if you want to make your changes accessible later on when you are not yet ready to add the changes to a commit. To stash your changes, you can run the git stash command:
git stash save README.md
This will save our README.md file in a stash. Whenever we are ready to revisit this file, we can access the stash using the stash pop command:
git stash pop
This command will restore the README.md file in our repository. “Stashing” is another way of saying “saving for later.” Stashes do not create commits of your changes.
After we run one of the above solutions, we can navigate to the development branch successfully:
git checkout development
This command switches our branch to “development” and informs us of this change in our terminal:
Switched to branch 'development'
We have solved the issue.
The Git “Your local changes to the following files would be overwritten by checkout” error occurs when you make changes on two branches without committing or stashing those changes and try to navigate between the branches.
You can fix this issue by either stashing your changes for later or adding them to a commit.
Now you have the knowledge you need to fix this error like a pro!