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.

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
# 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 trueThe 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.
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 refKey Comparison Table
| Command | Updates local branch | Touches working tree | Creates commits | Safe with uncommitted changes |
|---|---|---|---|---|
git fetch | No | No | No | Yes |
git pull --ff-only | Fast-forward only | Yes, checkout | No | Yes if no overlap |
git pull (merge) | Yes | Yes | Merge commit if divergent | Only if files do not overlap |
git pull --rebase | Yes, rewritten | Yes | No, rewrites yours | No, unless --autostash |
git remote prune origin | No, only refs/remotes | No | No | Yes |
git fetch --prune-tags | No | No | No | Yes, deletes tags locally |
| Situation | Recommended setting | Reason |
|---|---|---|
Shared main, CI on top of it | pull.ff = only | Linear history, failure is explicit |
| Feature branch, frequent upstream moves | pull.rebase = true | Keeps topic commits on top, no merge noise |
| Branch with signed merge commits | pull.rebase = merges | Rebases without flattening local merges |
| Many remotes, fork workflow | fetch.prune = true + remote.pushDefault | No ghost branches, correct default push target |
| Slow CI checkout | fetch --depth / partial clone | Less 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:
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
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 vanishedPruning never deletes a local branch, even one whose upstream disappeared. The : gone marker is the signal to clean up yourself:
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:
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 commitsThe 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
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 repoA 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
git config --global rebase.autoStash true
git pull --rebaseWith 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:
git status # rebase in progress, plus stash@{0} from autostash
git rebase --abort
git stash list # your autostash survives the abort
git stash popAlso 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:
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.0Remote 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
| Symptom | Cause | Fix |
|---|---|---|
fatal: Need to specify how to reconcile divergent branches | No pull.rebase / pull.ff configured | Set pull.ff=only or pass --rebase explicitly |
git pull creates merge commits on a rebase-only team | pull.rebase unset or false | git config --local pull.rebase true |
origin/branch: gone but local branch remains | Prune removed the tracking ref only | git branch -d <branch> after verifying it is merged |
git fetch --prune did not remove upstream/* | Pruned one remote only | git fetch --all --prune |
fatal: refusing to merge unrelated histories | Two roots, e.g. an imported repository | git pull --allow-unrelated-histories, then review the merge |
Shallow clone breaks bisect or merge-base | Grafted history | git fetch --unshallow, or clone with --filter=blob:none instead |
error: Your local changes would be overwritten by merge | Divergent pull with overlapping edits | Commit or stash first, then pull --rebase |
| Rebase pull rewrote commits others have | Rebase rewrites hashes | Re-push with --force-with-lease, or use --no-rebase on shared branches |
fetch stops at rejected non-fast-forward | Upstream rewrote history | git fetch --force origin main |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.