---
# System prepended metadata

title: 'Fix: Git Divergent Branches Error'
tags: [git]

---

# Fix: Git Divergent Branches Error

> **Error:** `fatal: Need to specify how to reconcile divergent branches.`

- - - 

## What Does This Error Mean?

This error happens when you run `git pull` and Git finds that:

-  Your **local branch** has commits that the remote doesn't have.
-  The **remote branch** also has commits that your local branch doesn't have.

This means the two branches have "diverged" - they each went in a different direction from a common ancestor. Git doesn't know **which strategy** you want to use to bring them back together, so it stops and asks you.

```
Remote:  A - - -  B - - -  C          (origin/develop)
                \
Local:    A - - -  B - - -  D - - -  E   (your local develop)
```

In this example, commits `C` are on remote and `D`, `E` are only local - they diverged from `B`.

- - - 

## The 3 Strategies to Fix It

### Strategy 1: Merge (Recommended for teams)

```bash
git pull - - no- rebase
```

Or set it as the default permanently:

```bash
git config pull.rebase false
git pull
```

**What it does:**
Creates a new **merge commit** that combines both branches.

```
Remote:  A - - -  B - - -  C
                      \
Local:    A - - -  B - - -  D - - -  E - - -  M (merge commit)
```

**Pros:**
-  Preserves full history exactly as it happened.
-  Safe and non- destructive - never rewrites commits.
-  Best for shared/team branches.

**Cons:**
-  Creates an extra merge commit that can clutter history.

- - - 

### Strategy 2: Rebase (Cleaner linear history)

```bash
git pull - - rebase
```

Or set it as the default permanently:

```bash
git config pull.rebase true
git pull
```

**What it does:**
Moves your local commits **on top of** the remote commits, replaying them one by one.

```
Remote:  A - - -  B - - -  C
Local:    A - - -  B - - -  C - - -  D' - - -  E'  (D and E replayed on top of C)
```

**Pros:**
-  Creates a clean, linear history (no merge commits).
-  Easier to read with `git log`.

**Cons:**
-  Rewrites commit hashes (D becomes D', E becomes E').
-  Can cause conflicts that you resolve one- by- one.
-  **Avoid on shared/public branches** that others are using.

- - - 

### Strategy 3: Fast- Forward Only (Safest, most restrictive)

```bash
git pull - - ff- only
```

Or set it as the default permanently:

```bash
git config pull.ff only
git pull
```

**What it does:**
Only pulls if your local branch has **no new commits** (i.e., it can simply move the pointer forward). If branches have diverged, it **refuses to pull** and exits with an error.

**Pros:**
-  Prevents accidental merges or rebases.
-  Forces you to explicitly decide how to handle divergence.

**Cons:**
-  Will fail whenever branches diverge - you then have to manually rebase or merge.

- - - 

## Quick Decision Guide

| Situation | Use |
|- - - |- - - |
| Team/shared branch (like `develop`, `main`) | `- - no- rebase` (merge) |
| Personal feature branch, clean history desired | `- - rebase` |
| You want Git to fail if branches diverge | `- - ff- only` |
| You don't want to think about it ever again | Set a global default (see below) |

- - - 

## Set a Global Default (Do It Once, Never See This Error Again)

Run one of these once to configure Git globally across all your repositories:

```bash
# Option A: Always merge on pull (most common for teams)
git config - - global pull.rebase false

# Option B: Always rebase on pull (clean history preference)
git config - - global pull.rebase true

# Option C: Only fast- forward, fail if diverged
git config - - global pull.ff only
```

- - - 

## Step- by- Step: Fix Your Current Situation RIGHT NOW

If you just want to fix this immediately on your `develop` branch:

### Option A - Merge approach (safe for team branches)

```bash
git pull - - no- rebase origin develop
# Resolve any merge conflicts if prompted
git push origin develop
```

### Option B - Rebase approach (clean history)

```bash
git pull - - rebase origin develop
# Resolve any rebase conflicts if prompted (git add + git rebase - - continue)
git push origin develop
```

- - - 

## Resolving Conflicts (If They Appear)

After pulling, you may see conflict markers in files:

```
<<<<<<< HEAD
Your local change
=======
Remote change
>>>>>>> origin/develop
```

**Steps to resolve:**

1. Open the conflicted file(s) and edit them to keep the correct code.
2. Remove the `<<<<<<<`, `=======`, and `>>>>>>>` markers.
3. Stage the resolved files:
   ```bash
   git add <file>
   ```
4. Complete the process:
   -  If you used `- - no- rebase`: `git commit`
   -  If you used `- - rebase`: `git rebase - - continue`

- - - 

## Summary

```bash
# QUICKEST FIX (merge, safe for teams):
git pull - - no- rebase

# SET GLOBAL DEFAULT SO THIS NEVER HAPPENS AGAIN:
git config - - global pull.rebase false
```

- - -