Skip to main content

Fix git pull - not possible to fast-forward

· 5 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

How to Solve "Not Possible to Fast-Forward" with git pull​

The git pull "Not possible to fast-forward" error happens when your local branch and the remote branch have diverged. This means there are new commits on the remote branch that you don't have, and you also have local commits that are not on the remote branch. Git cannot simply move your branch pointer forward (fast-forward) because doing so would lose your local changes.

To fix this, you must explicitly tell Git how to merge the divergent histories. There are two primary solutions: using git pull with rebase or performing a standard git pull followed by a manual merge.

Solution 1: Use git pull --rebase (Recommended for a Clean History)​

This method re-applies your local commits on top of the fetched remote changes, creating a clean, linear history.

  1. Check Your Status: First, ensure your working directory is clean.

    git status

  2. Use git pull --rebase: Run git pull with the --rebase flag.

    git pull --rebase origin main

    Git will perform the following steps:

    • Fetch: It will fetch the latest commits from the remote branch (origin/main).
    • Stash: It will temporarily save your local commits.
    • Replay: It will "replay" your local commits one by one on top of the new remote commits.

  3. Resolve Conflicts (if any): If there are conflicts, Git will pause the rebase.

    • Resolve the conflicts in the affected files.
    • Stage the resolved files with git add ..
    • Continue the rebase with git rebase --continue.
    • Repeat this process for any additional conflicts.

  4. Push Your Changes: Once the rebase is complete, your local branch history is linear and includes the latest remote commits. You can now push your changes.

    git push origin main

Solution 2: Use a Standard git pull Followed by a Merge​

This is the default behavior of git pull without any flags. It will create a "merge commit" to join the divergent histories. This is safer for shared branches because it doesn't rewrite history (3).

  1. Fetch the Remote Changes:

    git fetch origin

  2. Merge the Divergent Branches:

    git merge origin/main

  3. Resolve Conflicts (if any): If there are conflicts, Git will stop.

    • Resolve the conflicts in the files.
    • Stage the resolved files with git add ..
    • Complete the merge with git commit.

  4. Push Your Changes: You can now push your changes, including the new merge commit.

    git push origin main

Why Does This Error Occur?​

The "fast-forward" error is a safeguard (1). It happens when you have a local branch that is not a direct descendant of the remote branch's head commit. Git wants to prevent you from losing your local commits, which would happen if it simply moved the branch pointer forward without merging or rebasing.

By default, git pull is a shortcut for git fetch followed by git merge (2). The error message essentially tells you that a simple merge is not possible because of the divergent histories, and you need to choose an explicit strategy (rebase or merge) to resolve the divergence.

Sources​

  1. Git Reference: git-pull
  2. Atlassian Git Tutorials: Git pull
  3. The Golden Rule of Rebasing