What does "would be overwritten by merge" mean?

Question

When pulling from a team based Git remote repository, I get this message:

"C:\Program Files (x86)\Git\bin\git.exe" pull --progress "origin" +refs/heads/master:refs/remotes/origin/master
Updating 71089d7..4c66e71
error: Your local changes to the following files would be overwritten by merge:
    Source/Reporting/Common/Common.Dal.csproj
Please, commit your changes or stash them before you can merge.
Aborting
Done

What rule (or feature) in Git makes sure that the file I modified in my working directory does NOT get overwritten by the pull?

In other words, in what circumstances it will be overwritten by a pull? or... what do I need to do to force a pull to overwrite the file I just modified?

Answer 1

What rule would produce a "would be overwritten" warning?

If you've modified a file that also have modifications in the remote repository but have not committed it.

What rule would avoid a "would be overwritten" warning?

If there are no uncommitted files that also have modifications in the remote repo.

What do I need to do...

It depends on what you actually want:

1. You want to force a pull to overwrite the file

   Obviously, if you really want this, you don't care about the changes you've just made and don't mind deleting them. If so you simply do:

   git reset --hard
   git pull
   

2. You want both your changes and the changes from the pull

   The easiest way to handle this in my opinion is to commit your changes then do a pull. Then if there is a merge conflict use the usual mechanisms to resolve the merge (hint: configure your difftool and mergetool so you can easily resolve conflicts using a GUI tool like meld or diffmerge etc.). Just do:

   git add $the_affected_file
   git commit
   git pull
   

3. You want both changes but you're not ready to commit

   Personally I don't think you should ever be not ready to commit. But it happens from time to time that you have partly broken code that you're debugging and you really don't want to commit. In this case you can stash you changes temporarily then unstash it after pulling:

   git stash
   git pull
   git stash pop
   

   If there are conflicts after popping the stash resolve them in the usual way. Note: you may want to do a git stash apply instead of pop if you're not ready to lose the stashed code due to conflicts.

Answer 2

The message means that you have local modifications to your file which are not committed. When running pull, the files in your worktree are updated from remote repository. If git finds that the file is modified by both you and committed and in remote repository, it will simply try merging the changes and update both index and work tree. But for only locally modified files and not yet committed, it will stop.

So you have to either commit the changes first or stash them as suggested in the message. There is no way how to avoid it as it would lead into inconsistent index and work tree.

Typical scenario to keep the local changes is (as given in git help stash):

           git pull # first attempt of pull
            ...
           # Here you see the complains about locally modified files
           git stash # will save your changes into stash
           git pull  # pull now succeeds as there are no locally modified files
           git stash pop # pop the stash and apply the changes