Skip to content
masterclass Buddy
Start learning

Git · Command

git pull

git pull brings changes from another repository, or from a local branch, into the branch you have checked out. It runs a fetch and then integrates the fetched branch by fast-forwarding, rebasing, merging or squashing.

Last updated

How it works

git pull runs in two stages. First it calls git fetch with the same arguments, leaving out merge-only options, to download objects and update remote-tracking refs. Next it chooses a branch to integrate. Branches named on the command line win; otherwise Git uses the current branch's configured upstream (branch.<name>.remote and branch.<name>.merge). Last, it integrates that branch. By default it only allows a fast-forward. You can choose another method with --rebase, --no-rebase (merge) or --squash, or set it once with pull.rebase, pull.squash or pull.ff.

Syntax

git pull [<options>] [<repository> [<refspec>…]]

Parameters

NameTypeDescription
<repository>URL or remote nameThe repository to pull from. If you leave it out, Git uses the current branch's upstream, or origin.
<refspec>refspec (branch, tag or pattern)The ref or refs to fetch and integrate, such as main in git pull origin main. If you leave it out, Git uses the configured upstream.
--ff-onlyflagUpdate only when the local branch has not diverged from the remote. This is the default when no method is chosen.
--rebase[=(true|merges|false|interactive)]flag with optional valueRebase the current branch onto the upstream after fetching. merges keeps local merge commits, false merges instead, and interactive opens an interactive rebase.
--no-rebaseflagShort form of --rebase=false. The fetched branch is merged.
--squashflagPut the merged result in the working tree and index without committing or recording MERGE_HEAD.
--autostashflagStash local changes before the operation and apply them again when it finishes.
-s <strategy> / -X <option>stringPick the merge strategy, or pass an option to the strategy.

Key points

  • Unless you configure it otherwise, a plain pull only fast-forwards. If your branch and the remote have diverged, it stops and makes no changes. You then choose rebase or merge explicitly.
  • With no repository argument, pull uses the current branch's configured upstream. If there is none, it falls back to origin.
  • Every branch you name on the command line is integrated. Naming two or more remote refs creates an octopus merge.
  • When pull relies only on a configured globbing fetch refspec and no branch.<name>.merge is set, it fetches but integrates nothing.
  • When pull merges a single branch, it uses the ort strategy by default. ort is a 3-way merge that also detects renames.
  • git pull origin next gives the same result as running git fetch origin and then git merge origin/next. The fetched tip is also kept for a while in FETCH_HEAD.
  • With --autostash, pull will run even when you have uncommitted changes. Git stashes them first and applies them again afterwards.

Common mistakes

  • --rebase rewrites your local commits. Do not use it on history that other people already have.
  • --no-commit cannot stop a fast-forward, because a fast-forward makes no merge commit. If the branch must not move, add --no-ff as well.
  • With --autostash, the merge can succeed but applying the stash afterwards can still cause conflicts.
  • If the two histories share no common ancestor, pull refuses to merge them unless you pass --allow-unrelated-histories.

Example: Pull safely, then rebase if the branches have diverged

#!/usr/bin/env bash
set -euo pipefail

# Optional: make rebase the default way to pull in this repo
git config pull.rebase true

# Try a fast-forward first; fall back to a rebase if branches diverged
if ! git pull --ff-only origin main; then
  echo "Branches diverged; rebasing local commits onto origin/main"
  git pull --rebase --autostash origin main
fi

# Same thing in two steps: fetch, then merge
git fetch origin
git merge --ff-only origin/main

git log --oneline -5

The script tries a fast-forward pull first and rebases (stashing any uncommitted work) only when the branches have diverged. It then shows the same update done as a separate fetch and merge.

When to use it

Daily sync with upstream

Before you start work on a tracked feature branch, run a bare git pull so the branch matches its upstream without merge commits.

Linear history before pushing

Your push was rejected because others pushed first. Run git pull --rebase to replay your unpublished commits on top of theirs, then push again.

Merging a contributor's branch

A maintainer runs git pull <URL> <branch> to fetch a contributor's branch and merge it in one step.

Deepening a shallow clone

Run pull with --depth, --deepen or --unshallow to fetch more history into a shallow CI checkout while still updating the branch.

Interview questions

QWhat is the difference between git fetch and git pull?

git fetch only downloads objects and updates remote-tracking refs such as origin/main. Your current branch stays where it is. git pull runs that same fetch and then integrates the chosen remote branch into your current branch. git pull origin next is roughly the same as git fetch origin followed by git merge origin/next.

Follow-up: Which merge options does pull pass to the fetch step? None. Pull hands fetch the same arguments minus the merge-related options, and uses those options only when it integrates.

QWhat happens when you run git pull on a branch that has diverged from its upstream, with no pull settings configured?

Pull's default is fast-forward only, so it fails and leaves your branch as it was. You need to say how to reconcile the branches. Use --rebase to replay your commits on the upstream, --no-rebase to create a merge, or set pull.rebase or pull.ff in your config.

Follow-up: How do you get out of a pull that ended in conflicts you don't want to resolve? Run git merge --abort or git rebase --abort, depending on how pull integrated. After a messy pull you can also go back to an earlier state with git reset.

QWhich branch does a bare git pull integrate?

It uses the current branch's upstream, set by branch.<name>.remote and branch.<name>.merge. Without those it falls back to origin and the configured remote.<origin>.fetch refspecs. If branch.<name>.merge is missing, it integrates the first configured refspec. If that refspec is a glob, nothing is integrated.

Follow-up: Why is listing two branches on the command line different from configuring two fetch refspecs? Branches named on the command line are all merged, which gives an octopus merge. Configured refspecs are all fetched, but only the first is merged.

  • git fetch
  • git merge
  • git rebase
  • git push
  • git remote
  • git config
  • git stash
  • git reset

Source: Git - git-pull Documentation. Checked 2026-11-02.