How to Fix "fatal: not possible to fast-forward, aborting" in Git

You tried to pull the latest changes from a remote repository, but instead of a clean update, you were hit with this error message:

$ git pull origin main
From https://github.com/user/repo
 * branch            main     -> FETCH_HEAD
fatal: not possible to fast-forward, aborting.

Don't panic! This is a very common Git error. It simply means that your local branch and the remote branch have diverged. In other words, there are commits on the remote branch that you don't have locally, AND you have made commits locally that are not on the remote branch.

Why Does This Happen?

This typically happens when you are collaborating with others. Imagine this:

1. You clone a repository and start working on a new feature on the main branch.
2. While you were working, your colleague also made some changes and pushed them to the main branch on the remote.
3. Now, your local main branch is out of sync with the remote main branch. When you try to git pull, Git sees that it can't just fast-forward your local branch to the latest remote version because you have your own new commits.

Git is being cautious here. It's telling you, "Hey, I can't just add the new remote changes on top of your local changes because that would create a messy history. You need to decide how to integrate these two different lines of work."

The Git Cheat Sheet

No need to remember all Git commands and parameters: get our popular "Git Cheat Sheet" - for free!

Download Now for Free

How to Fix It

You have two main options to resolve this: Merging or Rebasing.

Option 1: Merge the Remote Changes

This is the most straightforward approach. You can explicitly fetch the remote changes and then merge them into your local branch. This will create a "merge commit" that ties the two histories together.

git pull --no-ff

Or explicitly:

# First, fetch the latest changes from the remote
$ git fetch origin

# Now, merge the remote main branch into your local main branch
$ git merge origin/main

After running these commands, Git will likely open a text editor for you to provide a message for the merge commit. You can usually accept the default message and save the file.

Your commit history will now show how the two divergent branches were merged back together.

Option 2: Rebase Your Local Changes

Rebasing is another way to integrate changes. It essentially replays your local commits on top of the latest remote changes. This results in a cleaner, linear history, which is preferred by some people.

git pull --rebase

Or step by step:

# Fetch the latest changes from the remote
$ git fetch origin

# Rebase your local commits on top of the remote branch
$ git rebase origin/main

This will take your local commits, temporarily set them aside, update your branch to the latest version from the remote, and then re-apply your commits one by one.

A word of caution: Rebasing rewrites commit history. If you have already pushed your local commits to a shared remote, it's generally better to use the merge strategy to avoid confusion for your collaborators.

Using git pull with Rebase

You can also configure git pull to use rebase instead of merge by default:

# Tell Git to use rebase when you pull
$ git pull --rebase

This is a popular workflow for teams that prefer a clean, linear project history.

A Quick Diagnostic Command

Want to see exactly what's happening? Use this command to visualize your branch status:

git log --graph --oneline --all -10

This shows you the last 10 commits across all branches in a nice graph format, helping you understand the divergence.

Final Thoughts

With practice, handling diverged branches becomes second nature. Seeing this error is a normal part of working with Git, especially in a team. It's Git's way of preventing you from losing work and forcing you to be explicit about how you want to combine different histories.

The important thing is that Git gives you the tools to handle these situations safely and according to your project's needs — whether you choose to merge or rebase, you are in full control. You cannot break anything!