Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git fetch, pull, rebase, and prune: Syncing Remote Branches

fetch moves tracking refs, pull merges or rebases on top, prune removes branches deleted upstream. Why pull now stops on divergent history, and what --ff-only protects.

~4 min readGit
#Git#Fetch#Pull#Remote
3D illustration of a cloud remote cube sending commit blocks down a pipe to a local repository cube

Quick Summary

git fetch downloads objects and updates remote-tracking refs (refs/remotes/origin/*). It never moves your local branches and never touches the working tree. git pull is git fetch followed by a second command — merge by default, rebase if configured — which is why every confusing "pull" surprise is really a merge or rebase surprise.

Three settings decide what pull does on a divergent history: pull.rebase, pull.ff, and rebase.autoStash. Without any of them, modern Git refuses to guess and prints a hint instead of creating an accidental merge commit. Setting pull.ff = only turns pull into a safe fast-forward-or-fail operation, which is the right default for a branch you share.

--prune is the other half of fetch hygiene. Remote branches deleted on the server stay in your refs/remotes/ forever until something prunes them, so git branch -r slowly fills with ghosts and git branch -vv shows [origin/feature: gone]. fetch.prune = true keeps the remote-tracking namespace honest.

Basic Syntax and Core Signatures

bash
# Fetch only: safe, no working tree change git fetch # default remote, default refspec git fetch origin # one remote git fetch --all # every remote (equivalent to git remote update) git fetch origin main # one branch into FETCH_HEAD + origin/main git fetch --prune # drop remote-tracking refs deleted upstream git fetch --prune --tags # also prune deleted tags git fetch --depth=50 origin main # shallow, then git fetch --deepen=50 # grow the shallow boundary git fetch --unshallow # full history back # RefSpec forms git fetch origin main:refs/remotes/origin/main git fetch origin +refs/heads/*:refs/remotes/origin/* # the default, forced git fetch origin main:feature # update a LOCAL branch (fast-forward only) git fetch origin refs/pull/42/head:pr-42 # GitHub pull request ref # Pull = fetch + integrate git pull # merge (or rebase, per config) git pull --ff-only # refuse if a merge commit would be needed git pull --rebase # replay local commits on top git pull --rebase=merges # rebase, but preserve local merge commits git pull --no-rebase # force a merge this time git pull --autostash # stash dirty tree, integrate, unstash # Persistent configuration git config --global fetch.prune true git config --global fetch.pruneTags false git config --global pull.ff only git config --global pull.rebase true git config --global rebase.autoStash true

The remote-tracking namespace is only a cache of what the server advertised at the last fetch. origin/main is a local ref that Git updates; main is yours.

text
refs/heads/main <- your branch, moves on commit, merge, rebase refs/remotes/origin/main <- last fetched position of the server's main FETCH_HEAD <- what the last fetch wrote, one line per ref

Key Comparison Table

CommandUpdates local branchTouches working treeCreates commitsSafe with uncommitted changes
git fetchNoNoNoYes
git pull --ff-onlyFast-forward onlyYes, checkoutNoYes if no overlap
git pull (merge)YesYesMerge commit if divergentOnly if files do not overlap
git pull --rebaseYes, rewrittenYesNo, rewrites yoursNo, unless --autostash
git remote prune originNo, only refs/remotesNoNoYes
git fetch --prune-tagsNoNoNoYes, deletes tags locally
SituationRecommended settingReason
Shared main, CI on top of itpull.ff = onlyLinear history, failure is explicit
Feature branch, frequent upstream movespull.rebase = trueKeeps topic commits on top, no merge noise
Branch with signed merge commitspull.rebase = mergesRebases without flattening local merges
Many remotes, fork workflowfetch.prune = true + remote.pushDefaultNo ghost branches, correct default push target
Slow CI checkoutfetch --depth / partial cloneLess object transfer, faster than prune tuning

Practical Edge Cases and Deep Dives

1. git pull refuses to run: the divergent-history hint

On a divergent branch with no pull.rebase and no pull.ff set, Git 2.27+ stops:

text
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.

This is a feature, not a regression: the previous default silently produced merge commits on repositories that never wanted them. In scripts, always pass the flag explicitly (git pull --ff-only), because a script cannot answer a hint. For a repository where you never want a merge commit, git config --local pull.ff only makes the failure loud and the fix obvious: fetch, look at the incoming commits, then rebase deliberately.

2. --prune removes tracking refs, not local branches

bash
git fetch --prune # - [deleted] (none) -> origin/feature/login git branch -r # origin/feature/login is gone git branch -vv # local feature/login still says [origin/feature/login: gone] git branch --merged main # a local branch whose upstream vanished

Pruning never deletes a local branch, even one whose upstream disappeared. The : gone marker is the signal to clean up yourself:

bash
git branch -vv | awk '/: gone]/{print $1}' | xargs -r git branch -d

-d (not -D) keeps the safety net: a branch with unmerged commits is refused. Note the ordering trap — git fetch --prune prunes only the remotes fetched, so git fetch --prune origin leaves upstream/* alone; use --all --prune for that.

3. RefSpecs that update a local branch directly

git fetch origin main:main updates your local main without checking it out. Git allows this only when the update is a fast-forward, so it cannot lose work, and it is the standard trick for a deployment clone you never check out:

bash
git fetch origin main:main git log --oneline -3 main # already updated git diff --stat main origin/main # empty git fetch origin main:main # after rewriting history upstream: # ! [rejected] main -> main (non-fast-forward) git fetch origin +main:main # forced, discards local commits

The leading + in a refspec forces the update, which is exactly the --force of fetch. Do not put +refs/heads/*:refs/heads/* in your config; a mirror fetch into local branches will overwrite work with no warning.

4. Shallow clones and what they break

bash
git clone --depth=1 https://example.com/repo.git git rev-parse --is-shallow-repository # true git fetch --deepen=100 # extend: relative to current boundary git fetch --unshallow # whole history, still cheap on a small repo

A shallow clone has a grafted history, so anything that needs real ancestry misbehaves: git merge-base returns nothing, git bisect can only search the shallow span, git log --all --graph shows a wall, and git push from a shallow branch works but git blame on older lines stops at the boundary. Note that --depth applies per remote; git fetch --depth=1 on an already shallow clone re-shallows to that depth, so use --deepen to grow.

5. Rebase pull with local work: autostash and the conflict loop

bash
git config --global rebase.autoStash true git pull --rebase

With a dirty tree, a plain git pull --rebase aborts ("cannot pull with rebase: You have unstaged changes"). Autostash hides the dirt, rebases, and reapplies — but the reapply is a second merge and can conflict on its own, leaving both a rebase stash entry and conflict markers. If that happens:

bash
git status # rebase in progress, plus stash@{0} from autostash git rebase --abort git stash list # your autostash survives the abort git stash pop

Also understand what --rebase does to your commits: it rewrites them, so hashes change and any branch that already contains them will need a force push. That is fine on an unpushed topic branch and unacceptable on a branch someone else is building on.

6. GitHub pull request refs and other non-branch refs

Branches are not the only thing a fetch can retrieve, and fetching is how you inspect a PR without trusting a fork branch:

bash
git fetch origin refs/pull/42/head:pr-42 git switch pr-42 git fetch origin refs/tags/v2.1.0:refs/tags/v2.1.0

Remote configuration also goes stale after a rename or fork move. git remote -v shows the URLs in use, git remote set-url fixes them, and git remote set-head origin -a re-resolves origin/HEAD so git log origin and the git switch heuristic follow the server's real default branch instead of a stale master.

Common Git Operation Mistakes

SymptomCauseFix
fatal: Need to specify how to reconcile divergent branchesNo pull.rebase / pull.ff configuredSet pull.ff=only or pass --rebase explicitly
git pull creates merge commits on a rebase-only teampull.rebase unset or falsegit config --local pull.rebase true
origin/branch: gone but local branch remainsPrune removed the tracking ref onlygit branch -d <branch> after verifying it is merged
git fetch --prune did not remove upstream/*Pruned one remote onlygit fetch --all --prune
fatal: refusing to merge unrelated historiesTwo roots, e.g. an imported repositorygit pull --allow-unrelated-histories, then review the merge
Shallow clone breaks bisect or merge-baseGrafted historygit fetch --unshallow, or clone with --filter=blob:none instead
error: Your local changes would be overwritten by mergeDivergent pull with overlapping editsCommit or stash first, then pull --rebase
Rebase pull rewrote commits others haveRebase rewrites hashesRe-push with --force-with-lease, or use --no-rebase on shared branches
fetch stops at rejected non-fast-forwardUpstream rewrote historygit fetch --force origin main

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.