Git Pull Options

If you use Git for version control, you might have recently seen a warning message after running git pull. It probably looked something like this:

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.

And it suggests using --rebase or --ff-only. What does this mean, and what should you do about it? Let’s break it down!

Git wants you to be explicit about how you handle changes when your local branch and the remote branch have both moved forward (i.e., they have diverged). By default, git pull fetches the latest changes from the remote and then merges them into your local branch. But merging isn’t always what you want, and it can clutter your history with unnecessary merge commits.

Git now encourages you to choose a strategy for combining changes, so your workflow is more predictable and your commit history stays clean.

What Are Divergent Branches?

Divergent branches happen when a remote branch has commits added after you originally pulled it. In the illustration below, the user pulled the main branch at commit B and added two more commits (D & E) to it.
In the mean time, another user pushed commit C to the remote. Since the local branch doesn’t have commit C, the two branches have now diverged.

Before:
A---B---C   (origin/main)
     \
      D---E   (main)

What Are My Options?

When you see this warning, Git is asking you to pick one of these strategies:

1. Merge (Default Behavior)

• What it does: Combines changes from both branches, possibly creating a merge commit (F in the illustration).
• When to use: If you want to preserve the full history of how branches diverged and merged.
• How to set the default: git config –global pull.rebase false
• How to set dynamically: git pull –merge

Before:
A---B---C   (origin/main)
     \
      D---E   (main)

After `git pull` (merge):
A---B---C---------F   (main, origin/main)
     \           /
      D---E-----

2. Rebase (--rebase)

• What it does: Re-applies your local commits on top of the remote branch, making your history linear (D’ and E’ in the illustration).
• When to use: If you prefer a tidy, linear history without extra merge commits.
• How to set the default: git config –global pull.rebase true
• How to set dynamically: git pull –rebase

Before:
A---B---C   (origin/main)
     \
      D---E   (main)

After `git pull --rebase`:
A---B---C---D'---E'   (main)
                ^
           (origin/main)

3. Fast-Forward Only (--ff-only)

• What it does: Only updates your branch if it can be done without a merge commit. If not, it aborts.
• When to use: If you want to avoid merges and rebases entirely, and only accept fast-forward updates.
• How to set the default: git config –global pull.ff only
• How to set dynamically: git pull –ff-only

Before:
A---B---C---D   (origin/main)
         \
          E     (main)

After `git pull --ff-only` (if possible):
A---B---C---D   (main, origin/main)

Summary

Strategy	History Shape	Merge Commits?	Linear?	When to Use
Merge	Branching	Yes	No	Preserve full branch history
Rebase	Linear	No	Yes	Keep history tidy
Fast-forward	Linear (if possible)	No	Yes	No local commits to combine

Which Option Should You Pick?

• Rebase is great for keeping your history clean and linear, especially in solo or small-team projects.
• Merge preserves the true branching structure, which can be helpful for complex team workflows.
• Fast-forward only is safest if you want to avoid accidental merges or rebases.

Have questions or tips about Git workflows? Drop them in the comments below!