Run git pull and Git downloads whatever new commits are sitting on the remote, then folds them into the branch you have checked out. The fetch happens first and the integration second.
Most people reach for it to get a teammate’s pushed work into their own branch before they carry on.
Atlassian and freeCodeCamp tutorials describe the second step as a merge, and for a long time that was accurate. The Git 2.56 manual (September 2026) lists fast-forward only as the default method now, so a pull on a diverged branch stops with an error unless you’ve set a rebase or merge preference.
What Does git pull Do?
Two operations run back to back, a fetch and then an integration step.
- Git downloads the new commits, updates the remote-tracking branches, and writes the fetched refs to FETCH\_HEAD.
- Git then picks the remote branch to bring in (the upstream of the current branch when no arguments are given) and applies it to the current branch.
The first step is the same operation git fetch performs on its own, so remote-tracking branches stay current even when the second step fails.
What the second step does depends on your flags and config. It can be a fast-forward, a rebase, or an ordinary git merge of the fetched branch.
The integration default has changed over the years, and older tutorials still describe the old one. Atlassian and freeCodeCamp explain the command as a fetch followed by a merge, while the Git 2.56 manual lists fast-forward only as the default method.
Without a rebase or merge preference, a pull on a diverged branch now stops with an error instead of creating a merge commit. Running git --version shows which release applies (the manual itself asks readers to check).
The manual’s title reads fetch and integrate rather than fetch and merge. That wording was already in the 2.33 manual, a release before the default changed in 2.34.
git pull Syntax and Arguments
The full form is git pull [<options>] [<repository> [<refspec>...]], and every part after the command name is optional.
- A remote name or a URL goes in the repository slot, and it falls back to the branch’s configured upstream remote or origin.
- The refspec is the branch or ref to fetch and integrate, such as main in
git pull origin main. - Options cover the integration method plus anything passed through to fetch, like –rebase and –ff-only, or –all.
The repository argument usually takes the origin remote, the name Git gives the source of a clone.
A URL works too (ssh, git, http or https) when it points at a remote repository. The manual calls ftp and ftps inefficient and deprecated.
A refspec has the shape +src:dst. The optional plus allows a non-fast-forward update of the destination.
In practice you’ll mostly see these forms.
git pulltraditionally meantgit pull origin, but a branch.NAME.remote value overrides origingit pull origin nextfetches next, leaves a copy in FETCH\_HEAD, and updates origin/next
A couple of documented quirks catch people out. Pass more than one refspec on the command line and you get an octopus merge.
With no refspec given, pull fetches every refspec in remote.NAME.fetch but merges only one of them. That is the branch named in branch.NAME.merge when it is set. Otherwise it is the first refspec found, and nothing is merged when that refspec is a glob.
git pull vs git fetch, and When to Fetch First
git fetch downloads new commits and stops at the remote-tracking branches. git pull downloads the same commits and then goes on to change the current branch.
| Aspect | git fetch | git pull |
|---|---|---|
| Updates remote-tracking branches | Yes | Yes |
| Writes FETCH\_HEAD | Yes | Yes (through its fetch step) |
| Changes the current branch | No | Yes, by fast-forward, merge or rebase |
| Can produce a conflict | No | Yes, during merge or rebase |
The manual spells out the equivalence. git pull origin next matches git fetch origin followed by git merge origin/next.
If the working tree is clean and the branch is only behind, just pull. Fetch first when you have local commits or the remote history was rewritten.
Reviewing incoming commits before you integrate
After a fetch, the remote-tracking branch holds exactly what a pull would bring in. Reading the log for that branch lists the new commits one by one.
- Run
git statusto confirm the working tree is clean. - Run
git fetch originto update origin/main. - Run
git log HEAD..origin/mainto list commits you do not have. - Run
git diff HEAD...origin/mainto see what they changed. - Run
git merge origin/mainorgit rebase origin/mainonce the changes look right.
Inspecting the changes with git diff catches a bad commit before it reaches your branch.
The git-fetch manual also shows a peek that needs no configured remote. Fetch a branch straight from a URL, then read it with git log FETCH_HEAD.
The snapshot goes stale, though. If a teammate pushes after your fetch, your review is out of date, and the next pull fetches again anyway.
How to Choose Between Merge, Rebase and Fast-Forward Only
Use fast-forward only if you want pull to refuse everything except a clean update. Rebase suits local commits that should sit on top of the remote history, and merge makes sense when the exact history matters more than keeping it in a straight line.
| Method | Flag | History result | Main cost |
|---|---|---|---|
| Fast-forward only | –ff-only | Linear, no new commits | Refuses diverged branches |
| Rebase | –rebase | Linear, local commits replayed on top | Rewrites local commits |
| Merge | –no-rebase | Merge commit joins both lines | Adds merge commits |
The rebase mode is the same operation as running git rebase by hand, applied right after the fetch.
The git-pull manual labels that mode potentially dangerous because it rewrites history, which causes trouble once the history is published.
Command-line options
--ff-onlyupdates only when no divergent local history exists--rebasetakes true, merges, false or interactive--no-rebaseis shorthand for--rebase=falseand runs git merge--squashrunsgit merge --squash, which stages the combined changes without making a commit or moving HEAD- With
--no-commit, Git stops before the merge commit so you can inspect the result
The merges value keeps local merge commits in the replay. With true, Git consults the remote-tracking branch to avoid rebasing non-local changes when the upstream itself was rebased since the last fetch.
--no-commit has a catch. A fast-forward creates no merge commit, so nothing stops it, and the manual says to pair --no-commit with --no-ff to keep the branch untouched.
Setting a default with git config
The default method lives in pull.rebase, pull.squash and pull.ff. Writing them through git config lands in the repository’s .git/config unless –global points the change at ~/.gitconfig.
git config pull.rebase falsegives you mergegit config pull.rebase truegives you rebase- For fast-forward only, it’s
git config pull.ff only
Per-branch overrides exist as well. The manual points to branch.NAME.rebase and branch.autoSetupRebase for making pull rebase on chosen branches.
Picking a mode by branch state
| Branch state | Pick | Reason |
|---|---|---|
| Behind the remote only | –ff-only | No local commits to reconcile |
| Diverged, local commits unpushed | –rebase | Linear history, nothing shared gets rewritten |
| Diverged, local commits already pushed | –no-rebase | Rebasing would rewrite published history |
Default to fast-forward only, and choose rebase or merge deliberately each time a pull stops.
Why git pull Fails and How to Fix It
A pull fails when uncommitted changes would be overwritten by the incoming update, when a merge or rebase hits conflicts, when the branches have diverged, or when the current branch has no upstream.
Uncommitted local changes
Git refuses the merge step when it would overwrite local changes, and the git-config manual lists a dedicated advice message for exactly that refusal.
- Commit the work, then pull.
- Or stash the changes, pull, and restore them afterward.
- Add
--autostashand Git stashes, pulls and reapplies in one command.
Keeping the work in a stash is the quickest way to clear the tree when the edits are not ready to commit.
The manual adds a caution about autostash. Reapplying the entry after a successful merge can produce non-trivial conflicts of its own. Git records the temporary entry in MERGE\_AUTOSTASH.
Merge conflicts
A conflict stops the pull halfway, and the manual says the operation can be aborted safely.
When the pull was a merge
- Edit the conflicted files, stage them, and commit the result
- Or cancel with
git merge --abort
When the pull was a rebase
- Edit and stage the files, then continue the rebase
- Or cancel with
git rebase --abort
A walkthrough of resolving merge conflicts in Git covers the conflict markers themselves.
The git-reset manual lists another way out. A conflicted pull has made no merge commit yet, so git reset --hard clears the index and working tree.
Divergent branches
Local and remote each received new commits, so a fast-forward is impossible. Git reports it as “Need to specify how to reconcile divergent branches.”
git pull --rebasereplays local commits on top of the remote ones for this pullgit pull --no-rebasecreates a merge commit that joins both historiesgit pull --ff-onlykeeps refusing, which leaves room to fetch and review first
Setting pull.rebase or pull.ff makes the choice permanent. Manual pages from Git 2.34 onward state the requirement outright.
No tracking information
A pull with no arguments needs an upstream, and a branch created locally has none until one is set.
The manual lists the cases where Git sets it automatically: on clone, on the first push when push.autoSetupRemote is enabled, and when checking out a remote-tracking branch. It also notes that upstream branches are sometimes called tracking information, which explains the error wording.
The fix is git push --set-upstream origin BRANCH, which records the remote and merge fields in .git/config. A one-off git pull origin BRANCH skips the upstream entirely.
How to Undo a git pull
Run git reset --hard ORIG_HEAD to undo a pull that already merged, because Git leaves the original tip of the branch in ORIG\_HEAD before a pull or merge.
The fetch half stays. Only the change to the current branch is undone, and the remote-tracking branches keep their new positions.
- Run
git statusand stash or commit uncommitted work, since--hardoverwrites tracked changes and can overwrite untracked files. - Run
git log -1 ORIG_HEADto confirm it points at the pre-pull commit. - Run
git reset --hard ORIG_HEADto restore the branch tip, index and working tree. - Run
git log --oneline -3to confirm the pulled commits are gone from the branch.
The reset manual describes moving the branch head with git reset as a way to undo commit, merge, rebase and pull alike.
If local edits must survive, use git reset --merge ORIG_HEAD. It keeps changes that --hard would discard, but it aborts if a file that differs between the target and the index has unstaged changes.
After a rebase pull, read git reflog for the entry just before the rebase started, then reset to it. The reset manual introduces the HEAD@{1} notation for the previous position of HEAD and points to git-reflog for details.
Reset only while the merge commit is still local. The manual warns against rewriting commits that were already given to someone else.
git pull FAQ
Does git pull change the files in my working directory?
Yes. A fast-forward, merge or rebase updates tracked files to match the new branch tip.
When local edits would be overwritten, Git refuses the integration step instead. The fetch half never touches the working tree.
Can git pull run without an internet connection?
Not against a network remote. The fetch step needs network access, so the whole command fails offline. A remote that points at a local path still works.
Commits fetched earlier still sit in the remote-tracking branch, and git merge origin/main integrates them without any network call.
Is a pull request the same thing as git pull?
No. A pull request is a feature of hosting platforms such as GitHub, GitLab and Bitbucket that asks maintainers to merge a branch.
git pull is a local command that updates your own branch from a remote.
What does the –all option do?
It fetches every configured remote instead of one, skipping remotes that set remote.NAME.skipFetchAll.
The flag overrides the fetch.all setting. --verbose is separate and only passes extra output through to fetch and merge.
Why does Git refuse to merge unrelated histories?
The two branches share no common ancestor, and a merge refuses that case by default as a safety check.
--allow-unrelated-histories overrides it, which fits joining two projects that started independently. The manual says no config variable will ever enable it by default.
How can a local branch be forced to match the remote?
Fetch first, then run git reset --hard origin/main with your own remote and branch names.
This discards local commits and uncommitted changes, so save anything worth keeping on a separate branch beforehand.
How is a fork synced with the original repository?
Add the original repository as a second remote, usually named upstream, then run git pull upstream main.
Push the result to origin afterward so the fork on the hosting platform catches up too.
Choosing a Team-Wide Default for git pull
A team repository works best with git pull pinned to fast-forward only in global or system config. The setting lives per clone, and the built-in default differs between Git releases.
Teammates on different releases can run the same command and get different results, so an explicit pull.ff value removes the variable.
Git does not ship .git/config with commits, so each developer sets the value once with --global, or an administrator writes the system-wide gitconfig on managed machines.
- Pin pull.ff to only on every machine, and fetch and inspect whenever a pull stops
- Rebase only unpushed commits
The cost is that every diverged pull now stops and demands a decision. That advice holds for the Git 2.56 manual as verified on October 1, 2026, and a later change to the default would alter it.
Agreeing on the pull default belongs to a wider Git workflow decision for the team.
- MongoDB Cheat Sheet - October 20, 2026
- Adding AI Video Generation to a Software Product: Architecture, Cost Guardrails and QA - October 20, 2026
- Show Hidden Characters, Spaces, and Line Endings in Notepad++ - October 19, 2026
