Introduction

git pull is sugar for git fetch followed by integration of the upstream branch into the current branch. The integration step is either a merge (default) or a rebase.

The two steps

1. git fetch <remote> <refspec>: download and update tracking refs.
2. If pull.rebase is false: git merge FETCH_HEAD.
3. If pull.rebase is true: git rebase FETCH_HEAD.

Equivalent manual sequence:

git fetch origin main
git merge origin/main             # or git rebase origin/main

Configuration

git config --global pull.rebase false   # merge (default classic)
git config --global pull.rebase true    # rebase
git config --global pull.ff only        # fast-forward only, otherwise abort

Since Git 2.27, plain git pull with no configuration prints a warning. Pick a strategy explicitly.

Fast-forward only

--ff-only is the safest pull: it succeeds only if your branch is strictly behind. No merge commit, no rebase, no surprises.

git pull --ff-only

Combine with autostash to avoid working-tree blockers:

git pull --ff-only --autostash

Pull with rebase

git pull --rebase
git pull --rebase=merges          # preserve merge structure

--rebase=merges is useful for branches that contain merge commits you want to keep.

Pull with autostash

git config --global rebase.autoStash true
git config --global merge.autoStash true

With these on, dirty trees are stashed before the integration and reapplied after, transparently.

Multi-branch pull

git pull origin main feature        # fetches both, merges octopus into HEAD

This is rarely what you want; prefer separate operations.

Pull vs explicit fetch + integrate

Many experienced users prefer to never use git pull. They run git fetch first, inspect git log HEAD..@{u}, and then choose merge or rebase deliberately. This is especially valuable when integrating long-lived divergent branches.

Pull policies for teams

Healthy teams pick a single pull policy and configure it organization-wide. Two common choices:

# Linear-history team: rebase on pull, merge via PR only
git config --global pull.rebase true
git config --global rebase.autoStash true

# Merge-friendly team: never rebase, always fast-forward main
git config --global pull.rebase false
git config --global pull.ff only

The worst configuration is the absent one: each developer's git pull behaves differently, producing inconsistent histories. Document the policy in your repo's CONTRIBUTING.md and provide a one-line config snippet new contributors can copy.

Common mistakes

Running git pull with uncommitted changes and getting an unexpected merge commit on top of dirty work. Either stash, commit, or set autoStash. Pulling with rebase on a branch others have based work on; you rewrite their base. Rebase only on private branches. Configuring pull.rebase globally without realizing it also affects main; many teams set pull.ff only globally and override per-branch. Finally, using git pull in CI; CI rarely needs integration, only the latest commit. Use git fetch and an explicit checkout of origin/main to keep CI deterministic.