averello/git-mirror
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2025-12-12 20:36:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: git-pull: clarify options for integrating remote branch

Browse Source 
From user feedback:

- One user is confused about the current default ("I was convinced that
  the git default was still to merge on pull")
- One user is confused about why "git fetch" isn't mentioned earlier
- One user says they always forget what the arguments to `git pull` are
  and that it's not immediately obvious that `--no-rebase` means "merge"
- One user wants `--ff-only` to be mentioned

Resolve this by listing the options for integrating the the remote
branch. This should help users figure out at a glance which one they
want to do, and make it clearer that --ff-only is the default.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Julia Evans
2025-10-15 13:13:29 +00:00
committed by Junio C Hamano
parent 85abbfc59b
commit 59b28f928b
1 changed files with 19 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
Documentation/git-pull.adoc
View File

@@ -15,17 +15,26 @@ SYNOPSIS
DESCRIPTION
-----------
Incorporates changes from a remote repository into the current branch.
If the current branch is behind the remote, then by default it will
fast-forward the current branch to match the remote. If the current
branch and the remote have diverged, the user needs to specify how to
reconcile the divergent branches with `--rebase` or `--no-rebase` (or
the corresponding configuration option in `pull.rebase`).
Integrate changes from a remote repository into the current branch.
More precisely, `git pull` runs `git fetch` with the given parameters
and then depending on configuration options or command line flags,
will call either `git rebase` or `git merge` to reconcile diverging
branches.
First, `git pull` runs `git fetch` with the same arguments
(excluding merge options) to fetch remote branch(es).
Then it decides which remote branch to integrate: if you run `git pull`
with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
for the current branch.
Then it integrates that branch into the current branch.
There are 4 main options for integrating the remote branch:
1. `git pull --ff-only` will only do "fast-forward" updates: it
fails if your local branch has diverged from the remote branch.
This is the default.
2. `git pull --rebase` runs `git rebase`
3. `git pull --no-rebase` runs `git merge`.
4. `git pull --squash` runs `git merge --squash`
You can also set the configuration options `pull.rebase`, `pull.squash`,
or `pull.ff` with your preferred behaviour.
Assume the following history exists and the current branch is
"`master`":