If you have made changes to the same file in both your local copy of a Git repository and a remote repository, you’ll encounter the “commit your changes or stash them before you can merge” Git error.
In this guide, we discuss what this error means and why it may be raised. We discuss the three ways in which you can solve this error.
commit your changes or stash them before you can merge
Because Git is distributed, you can maintain multiple copies of a repository. This means you can have one version of a repository on one computer, another version on another computer, and one central version to which every copy refers.
It is possible for the remote (central) version of a repository to change before you push a change to a repository. If someone changes the central version of a repository, you need to pull a local copy so you can work with the most up-to-date version of the codebase.
If the updated version of the repository contains a change to a file that conflicts with a change you have made on your local machine, you’ll see an error. This is because Git is unsure whether the remote version or the local version of the change should be kept.
This error is designed as a safeguard. Before you can push your code, Git forces you to think about which version of a file you want to keep: the local one, or the one in the remote version of the repository.
There are three ways you can solve this error:
- Commit a changed file
- Discard your changes
- Stash your changes
Solution #1: Commit a Changed File
You want to commit the changed file if your local copy of the file is the one you want to keep in the repository. This will add your file to the Git commit record and make it part of the history of the project.
git add filename.md git commit -m "feat: A change has been made"
When you push your commit to the remote version of the repository, your change will be reflected in the codebase.
Solution #2: Discard Your Changes
Often, the changes made to a remote repository remain in place. If you want to discard your changes, you can either checkout the remote version of a file, or reset your repository to the last commit so you can accept the changes that have been made.
To discard an individual file, use the git checkout command:
git checkout filename.md
git reset --hard
The –hard flag tells your computer you want to make a change to the HEAD, index, and working directory. This means the files on your local machine will be changed to reflect the current state of the remote repository.
Solution #3: Stash Your Changes
Stashing lets you keep track of the changes you have made to which you can refer in the future. It is helpful if you want to retrieve a remote copy of a repository but where you also want to save a record of your changes.
The changes you stash are not uploaded to the remote repository. You need to create a separate commit to add them to the repository.
To stash your changes, use the git stash command:
Now that you have a saved version of your changes, you can merge your code into the main version of your repository, or discard your changes. Once you have done either of these tasks, you can retrieve the code from your stash using the pop keyword:
git stash pop
You may run into the same error again if the remote version of a repository changes again. This is more of a temporary solution until you decide whether to commit a file to the main line of development or discard it.
The “commit your changes or stash them before you can merge” error is raised when you try to pull code from a remote repository that conflicts with a local change you have made to a repository.
To solve this error, either commit your change to the repository, discard your change, or stash your change for later. Now you have the knowledge you need to fix this error like a professional developer!