Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Sep 24, 2025, 20:23 UTC
Message-ID: <CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com>
In-Reply-To: <ffbb9d7c6aff77f9a1caed86a20bcc6b9afe66e7.1758656702.git.gitgitgadget@gmail.com>

On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 43 quoted lines

>
> From: Julia Evans <julia@jvns.ca>
>
> 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>
> ---
>  Documentation/git-pull.adoc | 25 ++++++++++++++-----------
>  1 file changed, 14 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
> index 50af7fde81..61d18fef36 100644
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -15,17 +15,20 @@ 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`).
> -
> -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.
> +Integrate changes from a remote repository into the current branch.
> +
> +First, `git pull` runs `git fetch` with the same arguments to fetch

Hm. Is it worth saying "similar" rather than "same" since we don't pass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in this context?

> +remote branch(es). Then it integrates the remote branch into the current
> +branch.

Plural-singular here leaves me wondering how Git decides which of multiple fetched branches to integrate. A quick test of the form

    git pull origin refs/heads/\*:refs/remotes/origin/\*

just gives an error in every mode I tried, so I'm now confused about this use :)

I _do_ like that when I "git pull", Git will fetch all branches if I have fetch.all set. That seems related but different. Welp, more corners to explore!

Show 10 quoted lines

> There are 4 main options for integrating the remote branch:
> +
> +1. `git pull --ff-only` will only do "fast-forward" updates: it
> +   fails if the remote branch has diverged. 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.

Lovely.

-- 
D. Ben Knoble