Introduction

If you have ever run git pull and been greeted with the error "Entry 'foo' not uptodate. Cannot merge.", you know how frustrating it can be when Git refuses to cooperate. This error occurs because Git is protecting you from losing uncommitted local changes that overlap with incoming changes from the remote. Understanding why Git raises this guard and how to resolve it will save you time and prevent accidental data loss.

Why This Error Happens

To understand the root cause, you need to know how Git tracks file states across three layers. The working tree is your actual files on disk. The index (also called the staging area) holds the snapshot you are preparing for the next commit. HEAD points to the last commit on your current branch. When you run git pull, Git performs a fetch followed by a merge. The merge step needs to combine the remote changes with your local HEAD, but it also checks whether your working tree and index are clean. If Git detects that a file has been modified locally but not committed, and that same file was changed in the incoming commits, it refuses to merge because it cannot safely combine the two versions without risking data loss.

1Working Tree    Index (Staging)    HEAD (Last Commit)
2   foo*              foo               foo
3   (modified)     (original)        (original)
4
5Remote has a new version of foo → Git cannot merge safely

The asterisk indicates that foo has uncommitted local modifications. Git sees a conflict between your local changes and the incoming version and halts the merge entirely.

Fix 1 — Stash, Pull, Then Pop

The most common fix is to temporarily shelve your local changes using git stash, perform the pull, and then reapply your changes on top.

1# Stash your uncommitted changes
2git stash
3
4# Now pull cleanly
5git pull
6
7# Reapply your stashed changes
8git stash pop

If the reapply step produces conflicts, Git will mark the conflicting sections in the file with standard conflict markers (<<<<<<<, =======, >>>>>>>). Resolve them manually, then stage and commit the result. This approach is ideal when your local changes are work-in-progress that you want to keep.

Fix 2 — Commit Your Changes First

If your local modifications are ready to be saved, simply commit them before pulling. This gives Git two proper commits to merge.

1# Stage and commit your local changes
2git add foo
3git commit -m "Save local changes to foo before pulling"
4
5# Now pull and merge
6git pull

After the pull, Git will attempt a merge between your commit and the remote changes. If both sides modified the same lines, you will get a merge conflict to resolve, but your work is safely recorded in a commit either way.

Fix 3 — Discard Local Changes

If you do not need your local modifications and just want the remote version, you can discard your changes entirely.

1# Discard changes to a specific file
2git checkout -- foo
3
4# Now pull cleanly
5git pull

Be careful with this approach — git checkout -- foo permanently discards your local edits to that file. There is no undo. Only use this when you are certain the local changes are expendable.

Using git pull --rebase

An alternative to the default merge-based pull is git pull --rebase, which replays your local commits on top of the fetched remote commits instead of creating a merge commit. This keeps the history linear and cleaner.

1# Stash first if you have uncommitted changes
2git stash
3
4# Pull with rebase
5git pull --rebase
6
7# Reapply stashed changes
8git stash pop

The rebase approach is especially useful in teams that prefer a linear commit history. However, it still requires a clean working tree, so you must stash or commit local changes before running it.

Understanding the Three-Layer Model

A deeper understanding of the working tree, index, and HEAD helps prevent this error from recurring.

1# See what differs between working tree and index
2git diff
3
4# See what differs between index and HEAD
5git diff --cached
6
7# See the full status across all three layers
8git status

When git status shows modified files under "Changes not staged for commit", those are working tree changes that have not been added to the index. Files under "Changes to be staged for commit" are in the index but not yet committed. Both categories can trigger the "not uptodate" error if the same files are changed remotely.

Common Pitfalls

• Running git checkout -- . to discard all changes wipes every modification in your working tree, not just the conflicting file. Always target specific files.
• Forgetting to pop the stash after pulling leaves your work hidden in the stash stack. Use git stash list to check for forgotten stashes.
• Assuming git pull --rebase avoids all conflicts is incorrect. Rebase replays commits one at a time, and each replay can produce its own conflicts.
• Not checking git status before pulling means you may not realize which files have local modifications, leading to surprise errors.
• Stashing untracked files requires the -u flag (git stash -u). Without it, new files that are not yet tracked by Git will not be stashed and may still block the pull.

Summary

• The "Entry not uptodate. Cannot merge" error means Git found uncommitted local changes that conflict with incoming remote changes.
• Use git stash then git pull then git stash pop to temporarily shelve and reapply your work.
• Commit your local changes before pulling if they are ready to be saved.
• Use git checkout -- <file> to discard local changes you do not need, but be aware this is permanent.
• Use git pull --rebase for a linear history, but always start from a clean working tree.
• Run git status and git diff before pulling to understand exactly what local changes exist.