Synopsis
git pull [--rebase] [--ff-only] [<remote> [<branch>]]Description
The git pull command is shorthand for git fetch followed by an integration step (merge by default, rebase optionally). It updates your current branch to incorporate upstream changes. Many teams prefer to configure pull.rebase = true or use git pull --rebase to keep history linear.
If your branch and the upstream have diverged, git pull may produce a merge commit. With --ff-only, the pull will fail rather than create a merge — useful when you want to be sure your local branch is just behind, not divergent.
In day-to-day use, git pull integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git pull --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git pull interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git pull's side effects helps avoid all three.
Common Options
| Option | Description |
|---|---|
--rebase | Rebase local commits on top of fetched changes. |
--ff-only | Only fast-forward; abort if a merge would be needed. |
--no-ff | Always create a merge commit. |
--all | Fetch from all remotes before integrating. |
--autostash | Stash local changes before pulling and pop after. |
--prune | Prune stale remote-tracking branches as part of the fetch. |
Examples
git pull
# Default: fetch and merge from configured upstream
git pull --rebase origin main
# Rebase local commits onto the latest origin/main
git pull --ff-only
# Refuse to create a merge commit
git config --global pull.rebase true
# Make rebase the default for every pullCommon Mistakes
Pulling with uncommitted changes can cause Git to refuse to merge. Either commit, stash, or use --autostash. Pulling onto a branch that has diverged often produces unexpected merge commits. Use --ff-only as a safety net or rebase explicitly.
Related Commands
git fetch, git merge, git rebase, git push