Table of Contents
Do you get the error message, "Pulling is not possible because you have unmerged files," when you try to git pull changes? Worry no more.
This tutorial explains the origin of the error message and how to solve it.
Let's do this!
Understand the basics
Git pull
Let's start by understanding what git pull entails.
Think of the code tracking environment as a two-part architecture: local and remote environment. In a local environment, we create the project files in a working directory. Next, we stage the changes. We can fall back to untracked files or safely store the files in a repository.
In simple terms, a repository is the version control system's database. Here, Git refers to the new changes as commits and assigns them unique numbers called commit hashes.
Although the changes are safely stored and can be retrieved, they are local. That means a loss of the computer results in a loss of our files. So, we send the changes to a remote repository through git push.
We can then collaborate with more remote developers, working on the same or separate git branches. A developer does their part and pushes the changes to the specified branch. To get the other developer's changes, you do the opposite of git push: git pull.
git pull is the process of updating a local repository with its updated remote version.
Some articles related to this topic:
git pull force Explained
git pull command examples
git pull vs git pull --rebase explained with examples
Git merge
A typical repository has multiple branches: the main branch and its subbranches.
After creating commits in the subbranch, we unite them with the main branch. This process is called git merge. Git merge enables collaboration in a project. Git is intelligent enough to notice the merge timestamps per branch.
Some articles related to this topic:
git merge explained
Git merge vs rebase and the problems they solve
However, here is a catch.
Merge Conflicts
Sometimes Git gets confused when it cannot determine the logical hierarchy of code portions resulting from commits of separate branches. Such a scenario is called a merge conflict.
A merge conflict needs to be resolved. Otherwise, your subsequent pull requests will fail. You can correct the pull error by resolving the merge conflict through a hard reset or manually accepting the new commit's changes in the script file.
Now that you know the origin and the solution to the typical error, "Pulling is not possible because you have unmerged files," let's set up a lab environment and do it practically.
Lab environment setup
Log into your GitHub account and create a new repo with a README.md
file. I am creating one called lab
.
Copy the repo URL.
Return to your local machine's terminal, clone the repo, and cd
into it.
Now let's generate the error: Pulling is not possible because you have unmerged files.
Generate the error: Pulling is not possible because you have unmerged files
Make a commit in the main branch
Let's create index.html
with a title and a description paragraph.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Pulling is not possible because you have unmerged files</title>
</head>
<body>
<h2>Let's create the error</h2>
<p>You are about encounter the error: pulling is not possible because you have unmerged files</p>
</body>
</html>
Stage and commit the changes.
git add index.html git commit -m "Add index.html"
Now we have two commits in the main branch.
git log --oneline
Make a commit in the feature branch
Create a feature branch.
git switch -c feature_branch
And modify the index.html file by adding a paragraph: First, create the feature branch. We use Visual Studio Code to ease the development and manual error correction. Stage the changes and make a commit
.
Now the feature branch is ahead of the main branch with a commit.
Switch to the main branch, and modify the index.html
with a paragraph: Generating the error.
Next, stage the changes and create a commit
.
What happens when we attempt to merge the feature branch?
Let's find out.
Create a merge conflict
Now let's attempt merging the feature branch's changes.
Input
git merge feature_branch
Output
user@hostname:~/lab$ git merge feature_branch
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.
Git tells us it found a conflict in the index.html
file and recommends that we correct the error before proceeding.
Okay, let's inspect the file.
Input
cat index.html
Output
user@hostname:~/lab$ cat index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Pulling is not possible because you have unmerged files</title>
</head>
<body>
<h2>Let's create the error</h2>
<p>You are about encounter the error: pulling is not possible because you have unmerged files</p>
<<<<<<< HEAD
<p>Generating the error</p>
=======
<p>First, create the feature branch</p>
>>>>>>> feature_branch
</body>
Git is stranded on whether the paragraph from the latest commit (HEAD) from the main branch should come first or the feature branch's paragraph.
<<<<<<< HEAD
<p>Generating the error</p>
=======
<p>First, create the feature branch</p>
>>>>>>> feature_branch
We could edit the file to capture our intention before merging the feature branch. However, let's ignore the call to resolve the conflict. Nor merge the feature branch.
Instead, let's return to the GitHub repository and update the README.md
file
Getting error
Now attempt to pull the remote changes.
Input
git pull
Output
user@hostname:~/lab$ git pull
error: Pulling is not possible because you have unmerged files.
hint: Fix them up in the work tree, and then use 'git add/rm <file>'
hint: as appropriate to mark resolution and make a commit.
fatal: Exiting because of an unresolved conflict.
Git says we have an error: Pulling is not possible because you have unmerged files.
Resolving the error: Pulling is not possible because you have unmerged files
Although we could reset one of the commits, we will retain the changes by accepting both paragraphs in the index.html.
from
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Pulling is not possible because you have unmerged files</title>
</head>
<body>
<h2>Let's create the error</h2>
<p>You are about encounter the error: pulling is not possible because you have unmerged files</p>
<<<<<<< HEAD
<p>Generating the error</p>
=======
<p>First, create the feature branch</p>
>>>>>>> feature_branch
</body>
</html>
to
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Pulling is not possible because you have unmerged files</title>
</head>
<body>
<h2>Let's create the error</h2>
<p>You are about encounter the error: pulling is not possible because you have unmerged files</p>
<p>Generating the error</p>
<p>First, create the feature branch</p>
</body>
</html>
Then, stage and commit the changes.
Input
git add . git commit -m "Accept both paragraphs"
Output
user@hostname:~/lab$ git add .
user@hostname:~/lab$ git commit -m "Accept both paragraphs"
[main 308f222] Accept both paragraphs
Now git pulling does not produce the primary error.
Input
git pull
Output
user@hostname:~/lab$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 779 bytes | 194.00 KiB/s, done.
From github.com:Stevealila/lab
634d087..4685287 main -> origin/main
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint: git config pull.rebase false # merge
hint: git config pull.rebase true # rebase
hint: git config pull.ff only # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.
Although the pull process goes through, we get some warnings. The relieving part is that Git gives us some hints on how to get rid of the warnings.
Summary
The error, "Pulling is not possible because you have unmerged files," often results from attempting to git pull changes without resolving local merge conflicts. As shown in this tutorial, you can correct the conflicts before proceeding with git pull.