DEV Community

Cristian Sifuentes
Cristian Sifuentes

Posted on

When Git Pushes Back: Handling Unmerged Files Like a Pro

#git #github #programming #backend

When Git Pushes Back: Handling Unmerged Files Like a Pro

When Git Pushes Back: Handling Unmerged Files Like a Pro

In professional Git workflows, nothing feels more disruptive than this message:

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.
Enter fullscreen mode Exit fullscreen mode

This isn’t just an error. It’s Git telling you, "We have unfinished business." In this article, we’ll explore how to deal with unmerged files like a seasoned engineer, walking through real use cases, advanced resolution strategies, and pro-level habits.

What Triggers Unmerged Files?

Unmerged files happen when you:

  • Run git pull and Git can’t automatically reconcile the changes between local and remote.
  • Have outstanding merge conflicts from a previous operation.

They leave Git in a mid-merge state, pausing all operations until you fix or abort the process.

The Scenario: Refactoring Reports Module in Spark

Let’s say you’re collaborating on a refactor of the reports module using a feature branch:

git pull origin users/ismaelg/spark-clean-architecture/reports-refactoring
Enter fullscreen mode Exit fullscreen mode

You get:

fatal: Exiting because of an unresolved conflict.
Enter fullscreen mode Exit fullscreen mode

You check git status and see files marked as both modified. These are conflict markers.

Resolving Conflicts Like a Pro

Step 1: View the Conflicts 

git status
Enter fullscreen mode Exit fullscreen mode

Look for sections like:

both modified:   reports/reportService.ts
Enter fullscreen mode Exit fullscreen mode

Open the file and locate the conflict markers:

<<<<<<< HEAD
const reportLimit = 100;
=======
const reportLimit = 50;
>>>>>>> origin/users/ismaelg/spark-clean-architecture/reports-refactoring
Enter fullscreen mode Exit fullscreen mode

Step 2: Resolve Intelligently

Choose or merge the correct content. For example:

const reportLimit = 75; // compromise for scalability vs latency
Enter fullscreen mode Exit fullscreen mode

Then remove the markers.

Step 3: Mark as Resolved 

git add reports/reportService.ts
Enter fullscreen mode Exit fullscreen mode

Step 4: Commit the Merge 

git commit -m "Resolve merge conflicts in reportService.ts"
Enter fullscreen mode Exit fullscreen mode

Step 5: Continue Your Workflow

Now your git pull completed successfully. You're back to a clean state.

Advanced Techniques

1. Visual Merge Tools

Use tools like:

  • code --wait . (VSCode)
  • git mergetool
  • Meld, Beyond Compare, or KDiff3 
git mergetool
Enter fullscreen mode Exit fullscreen mode

2. Abort a Faulty Merge

If you realize things went wrong:

git merge --abort
Enter fullscreen mode Exit fullscreen mode

Or if you’re mid-rebase:

git rebase --abort
Enter fullscreen mode Exit fullscreen mode

3. Stash Before Pulling 

git stash
# then pull
# resolve
# finally apply back
git stash pop
Enter fullscreen mode Exit fullscreen mode

Bonus: Preventive Habits

Habit Why It Helps
git pull --rebase Keeps history linear and clean
Commit early and often Smaller diffs, easier conflict resolution
Use feature flags Avoid blocking production deployments
Always check git status Catch conflicts before they snowball

TL;DR Key Takeaways

  • Git won't let you move forward with unmerged files.
  • Conflicts are natural in collaboration; resolution is part of your job.
  • Learn to resolve with tools or manually.
  • Master conflict resolution commands: git status, git mergetool, git add, git commit.
  • Don't panic — just follow the breadcrumbs.

Conclusion

Git isn't just a tool, it's your partner in code collaboration. Unmerged files aren't mistakes — they're checkpoints. Learning to handle them confidently elevates you from a developer to a Git power user.

The next time Git pushes back, you'll be ready.

✍️ Written by: Cristian Sifuentes – Full-stack dev crafting scalable apps with [NET - Azure], [Angular - React], Git, SQL & extensions. Clean code, dark themes, atomic commits

#git #devops #conflicts #gitproblems #versioncontrol #cleanarchitecture #spark #refactor

Top comments (0)