git pull vs git fetch

What is git fetch?

git fetch contacts the remote (typically origin) and downloads any commits, branches, or tags that your local repository does not yet have. Crucially, it only updates your remote-tracking branches — local references like origin/main that mirror the remote's state. Your actual local branch (main) and your working directory are completely untouched.

This makes git fetch a read-only, risk-free operation. You can run it at any time, even with uncommitted changes, without any risk of conflicts or overwritten work. After fetching you can inspect what is new before deciding how to integrate it:

# Download all remote changes safely
git fetch origin

# See commits on origin/main that you don't have locally
git log HEAD..origin/main --oneline

# Compare your current branch with the remote
git diff HEAD origin/main

# Check whether your history has diverged
git status
# → "Your branch is behind 'origin/main' by 3 commits"
# → "Your branch and 'origin/main' have diverged"

What is git pull?

git pull is a convenience command that combines two steps: git fetch followed by git merge. It downloads the remote changes and immediately integrates them into your current branch. This is efficient when you know you want the latest changes and are confident the integration will be clean — for instance, on a private feature branch with no local commits yet.

The default merge behaviour can produce a merge commit whenever your local and remote histories have diverged. Many teams consider this noise in the history. The --rebase flag solves this by replaying your local commits on top of the fetched commits instead of merging them:

# Simple pull (fetch + merge — may create a merge commit)
git pull

# Pull with rebase (fetch + rebase — linear history, no merge commit)
git pull --rebase

# Set rebase as the global default
git config --global pull.rebase true

# Pull a specific remote branch into your current branch
git pull origin feature/payments

FETCH_HEAD

After every fetch, Git writes a file called FETCH_HEAD recording the tip of the branch just fetched. You can reference it directly: git diff FETCH_HEAD shows what changed, and git merge FETCH_HEAD integrates those changes. Most developers prefer named refs like origin/main because they are more explicit, but FETCH_HEAD is useful in scripts and CI pipelines.

Fast-forward vs diverged history

When you pull or merge, Git decides between two outcomes based on the state of your histories:

Fast-forward: If your local branch has no commits that the remote does not have — i.e. your branch is simply behind — Git can move the branch pointer forward without creating a merge commit. This is the cleanest outcome.

Diverged history: If both your local branch and the remote have commits the other side lacks, the histories have diverged. A plain git merge will create a merge commit with two parents. Running git pull --rebase instead replays your local commits on top of the remote commits to restore a linear history.

# Fast-forward scenario (local is only behind)
#   origin/main: A → B → C
#   local main:  A → B
#   After: git pull → fast-forwards to C (no merge commit)

# Diverged scenario (both sides have new commits)
#   origin/main: A → B → C
#   local main:  A → B → D (your commit)
#   git pull           → creates merge commit M(C, D)
#   git pull --rebase  → replays D on top of C → linear A→B→C→D'

The safer workflow: fetch → inspect → integrate

On shared branches such as main or develop, the fetch-inspect-merge pattern gives you full visibility before altering your branch. This is the workflow recommended in most professional Git guidelines:

# Step 1: fetch safely — working directory unchanged
git fetch origin

# Step 2: inspect what is incoming
git log HEAD..origin/main --oneline --graph

# Step 3: see the actual diff
git diff HEAD origin/main

# Step 4: integrate consciously — merge or rebase
git merge origin/main
# — or for a linear history —
git rebase origin/main

Compare this with the git merge vs rebase guide to decide which integration strategy suits your team's branching model.

How engineers talk about git pull and git fetch

When to use git fetch

• Before a code review or deployment. Fetch to see whether the remote has diverged; inspect the incoming changes; then integrate deliberately.
• On shared branches (main, develop). Fetching gives you a window to review before your local branch is affected.
• When you have uncommitted work in progress. A fetch is always safe; a pull might conflict with your unstaged changes.
• Refreshing your view of all remotes. Run git fetch --all --prune to update every remote-tracking branch and remove stale references for deleted branches.

When to use git pull

• Your own private feature branch. If you are the only developer on the branch and you want the latest remote commits, git pull is the quickest path.
• Clean working directory with no divergence. When you have no local commits beyond the remote, the pull will fast-forward cleanly — no merge commit, no surprises.
• Automated scripts and CI pipelines. CI typically runs a pull or shallow checkout; the merge behaviour is expected and controlled within the pipeline.
• Team has configured pull.rebase true. When your organisation has standardised on rebase pulls, git pull is safe and keeps history linear.

Quick decision guide

• Want to see what changed on the remote without touching your branch → git fetch
• Private branch, clean working directory, no local commits → git pull is fine
• Want a linear history with no merge commits → git pull --rebase
• On a shared branch (main, develop) → git fetch, then review, then merge or rebase
• Have uncommitted work in progress → git fetch (stash first if you need to pull)
• Need to update all remote-tracking refs at once → git fetch --all --prune
• Unsure whether your history has diverged → git fetch then git status

Key vocabulary

• Remote-tracking branch — a local read-only reference that mirrors the state of a branch on the remote (e.g. origin/main). Updated by fetch.
• Fast-forward merge — a merge that simply moves the branch pointer forward because there is no divergence; no merge commit is created.
• Diverged history — two branches that have each moved forward independently from a common ancestor, each having commits the other lacks.
• Merge commit — a commit with two parents, created when two diverged branches are merged. Visible as a "diamond" in the history graph.
• FETCH_HEAD — a file Git writes after every fetch, pointing at the tip of the branch just fetched; usable as a ref in subsequent commands.
• Rebase — replaying commits from one branch on top of another to produce a linear history without merge commits.
• Prune — removing stale remote-tracking references for branches that have been deleted on the remote (git fetch --prune).
• Stash — temporarily shelving uncommitted changes so you can fetch or pull without conflicts (git stash / git stash pop).