Git Fetch vs Pull: Fetch Looks, Pull Looks and Then Changes Your Branch

git fetch downloads new commits and moves your origin/main bookmark, and touches nothing else. git pull runs fetch and then merges or rebases the result into your current branch. The difference only matters when your history and the server's have diverged.

Tech Talk News Editorial7 min read
#git#version control#developer tools#workflow
ShareXLinkedInRedditEmail
Git Fetch vs Pull: Fetch Looks, Pull Looks and Then Changes Your Branch

Key takeaways

  • git fetch downloads new commits from a remote and updates your remote-tracking branches such as origin/main, but it does not modify your working directory or your current branch.
  • git pull first runs git fetch with the same arguments, then integrates the fetched branch into your current branch by merging or rebasing, so it is two operations in one command.
  • When your branch and its upstream have each gained one commit the other lacks, git status reports that they have diverged, and git pull on Git 2.53.0 stops with the error: Need to specify how to reconcile divergent branches.
  • Setting git config pull.ff only makes git pull refuse anything that is not a fast-forward, so it can never create a surprise merge commit or rewrite your commits.
  • The safe habit is git fetch, then git log HEAD..origin/main to read what arrived, then git merge --ff-only origin/main or git rebase origin/main on purpose.

git fetch downloads new commits from the remote and updates your origin/main bookmark, and that's all it does to your repository.[1] git pull runs a fetch first, then merges or rebases the result into the branch you're standing on.[2] So fetch is looking, and pull is looking followed by changing your branch.

Most people learn pull first, use it for years, and never find out it was two commands wearing one name.

Then one Tuesday it prints a wall of hints and refuses to run, and the person who's used it ten thousand times has no mental model to fall back on. This article is that model, with the commit graphs drawn out.

Fetch updates a bookmark, not your work

Start with what the server and your laptop each hold. Your repository keeps a local copy of every commit it has seen, plus remote-tracking branches, which the Pro Git book describes as references to the state of remote branches.

They're local, you can't move them yourself, and Git moves them whenever you talk to the network. Think of them as bookmarks for where the remote's branches were the last time you connected.[1]

git fetch is the command that talks to the network. The official manual says it fetches branches and tags, along with the objects needed to complete their histories, and updates the remote-tracking branches.[3] Pro Git is blunter: fetch “will not modify your working directory at all.”[1]

Before git fetchABCDmainorigin/mainserver onlyAfter git fetchABCDmainorigin/main
Time runs left to right. Dashed means you don't have it yet. Fetch adds D and slides the origin/main bookmark onto it, and your own main and your files stay put.Source: Pro Git, remote-tracking branches

Here's what that looks like in a terminal. I set up a throwaway repository with a second clone pushing commits, then ran this on Git 2.53.0.

TerminalShell
$ git fetch
   c9b1b0a..5fe0e86  main       -> origin/main

$ git status -sb
## main...origin/main [behind 1]

$ git log --oneline HEAD..origin/main
5fe0e86 add i
Fetch reports the bookmark moving from c9b1b0a to 5fe0e86. The branch itself is now one commit behind, and nothing in the working directory changed.

HEAD..origin/main is the useful one. It reads as “commits on the server that I don't have,” so you can look at what a teammate pushed before it touches anything of yours.

“Of the Git commands that download from a remote, fetch is the one that can never touch your files.”

Pull is fetch plus an integration step you didn't pick

The manual spells it out. git pull first runs git fetch with the same arguments, then decides which remote branch to integrate, which by default is the upstream of your current branch, and then integrates it into the current branch.[2] The integrating can be done four ways: fast-forward only, rebase, merge, or squash.[2]

When you're behind and have no commits of your own, as in the terminal output above, there is nothing to decide. Your branch can slide forward onto the new commit, which Git calls a fast-forward, and pull works quietly. I confirmed it: git merge --ff-only origin/main printed Fast-forward and moved main from c9b1b0a to 5fe0e86.

The trouble starts when you have a commit the server lacks and the server has one you lack. Then git status says the two branches have diverged, and a pull has to pick a way to combine them. On my 2.53.0 install it refused to pick for me:

TerminalShell
$ git status
On branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.

$ git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
fatal: Need to specify how to reconcile divergent branches.
Real output, trimmed to the lines that matter. Git stops and asks rather than guess.

That prompt has a history. Git 2.27 began warning whenever pull.rebase was unset and neither --rebase, --no-rebase nor --ff-only was given.[4] The warning exists because the two sane answers produce different histories, and Git decided that choosing silently on your behalf was a bad default.

What the two ways of combining look like

Merge ties both lines together with a new commit that has two parents. Rebase lifts your commit off, moves your branch to the fetched tip, and replays your commit on top, which gives it a new ID.

I covered what that replay means, and when it's dangerous, in Git rebase vs merge. The pictures are the quick version.

After git fetch, histories have divergedABLRmain (your commit L)origin/main (their commit R)git pull --no-rebase: a merge commit M with two parentsABLRMmainorigin/maingit pull --rebase: your commit replayed on top as L2ABRL2mainorigin/main
L and R are the two commits that exist on only one side. Merge keeps both and adds M. Rebase keeps R and re-creates your commit as L2, a copy with a different ID.Source: Git manual, git pull
Questiongit fetchgit pull
Talks to the remoteYesYes, it runs fetch first
Updates origin/mainYesYes
Moves your current branchNoYes, by fast-forward, merge or rebase
Changes your working filesNoYes, when the branch moves
Can hit a merge conflictNoYes
Safe to run any timeYesBest with a clean working tree

Takeaway

Fetch can never create a conflict, because it never combines anything. Every conflict you meet during a pull comes from the second half, the integration, and that's the half you can choose to do on your own terms.

What I'd actually do

I fetch first, always. It costs nothing, and it turns “what did my team push” from a guess into a command I can read. Then I integrate on purpose.

The fetch-first habitShell
git fetch --prune
git log --oneline HEAD..origin/main
git diff --stat HEAD origin/main

# then pick one, deliberately
git merge --ff-only origin/main
git rebase origin/main
The --prune flag removes remote-tracking references for branches that no longer exist on the remote, which keeps the branch list honest.

The second thing is a one-line setting I wish everyone had: git config --global pull.ff only. Pull then fast-forwards or stops.

It can't invent a merge commit in the middle of your feature branch, and it can't quietly rewrite your commits. When it stops, you know you're in the diverged case, and you pick merge or rebase with your eyes open.

Heads up

The git-pull manual currently contradicts itself on defaults. One paragraph says --ff-only is the default when no method is given, and the --rebase section calls true the default.[2] I can't resolve that from the docs. What I can say is what my 2.53.0 install did, which is stop and ask. Set pull.ff or pull.rebase yourself and the question never comes up.

If you pull in a shared team repository, the rule from the rebase article applies unchanged: never rebase commits other people have already based work on. Pull with rebase is rebase. It rewrites your local commits, and that's only fine because they're yours.

Pull isn't a bad command. It's a convenient one that hides a decision, and the decision is the whole job of version control. Fetch first, read what arrived, then choose.

Primary sources

  1. 1.PrimaryPro Git, "Remote Branches". Remote-tracking branches as bookmarks; git fetch does not modify the working directory.
  2. 2.PrimaryGit documentation, "git-pull". Pull runs fetch first, then integrates; the four integration modes; the --rebase and --ff-only text.
  3. 3.PrimaryGit documentation, "git-fetch". What fetch downloads, remote-tracking branch updates, and the --prune option.
  4. 4.PrimaryGit 2.27.0 release notes. git pull began warning when pull.rebase is unset and no --rebase, --no-rebase or --ff-only is given.

Frequently asked questions

What's the difference between git fetch and git pull?
git fetch downloads new commits from the remote and updates remote-tracking branches like origin/main, without changing your current branch or working files. git pull runs git fetch and then integrates the fetched branch into your current branch, by merge or rebase. Fetch is read-only for your work. Pull changes your branch.
Is git fetch safe?
Yes. Git's own book says git fetch will not modify your working directory at all. It brings the data down so you can merge it yourself. The only thing that moves is the remote-tracking branch, such as origin/main, which is a local bookmark of where the server's branch was last time you connected.
Does git pull do a merge or a rebase?
It does whichever you configure, and it can refuse to choose. git pull --no-rebase runs git merge, git pull --rebase runs git rebase, and git pull --ff-only only fast-forwards. When your history has diverged and no preference is set, git pull on Git 2.53.0 stops and asks you to pick one with the error Need to specify how to reconcile divergent branches.
How do I see what changed before I pull?
Run git fetch, then git log --oneline HEAD..origin/main to list the commits you don't have, and git diff --stat HEAD origin/main to see the files they touch. Nothing in your branch has changed at that point. When you're happy, run git merge --ff-only origin/main or git rebase origin/main.
How do I stop git pull from creating merge commits?
Run git config --global pull.ff only. With that set, git pull only fast-forwards and fails when your branch has local commits the remote lacks, instead of creating a merge commit. You then choose to merge or rebase deliberately. git config pull.rebase true is the other option, which replays your commits on top of the fetched ones.

Written by

Tech Talk News Editorial

Computer engineering background. Writes about software, AI, markets, and real estate, and the places where the three meet.

More about the author
ShareXLinkedInRedditEmail