From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org, "D. Ben Knoble" <ben.knoble@gmail•com>,
"Chris Torek" <chris.torek@gmail•com>
Subject: Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch
Date: Thu, 09 Oct 2025 17:31:30 -0400 [thread overview]
Message-ID: <b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com> (raw)
In-Reply-To: <xmqqqzvddqon.fsf@gitster.g>
On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com> writes:
>
>> +Integrate changes from a remote repository into the current branch.
>> +
>> +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 the remote branch has diverged. This is the default.
>
> Technically, you can pretend to be the king, the center of the
> world, and occasionally publish your very latest to the remote by
> pushing there, and it is technically possible that the remote to
> diverge from you by somehow acquiring its own commits, so the above
> is not wrong per-se, but the way it is phrased is a bit awkward.
>
> The operation fails when _you_ diverged from the remote branch.
Thanks, I meant to fix that earlier. Will fix to say
"if your local branch has diverged from the remote".
>> +2. `git pull --rebase` runs `git rebase`
>
> This technically does not integrate remote branch into our current
> branch. Rather, the commits on our current branch are integrated
> on top of their history. That may be worth noting? I dunno.
At least 2 users who read this also commented that they find the word
"integrate" using, for perhaps a similar reason. Specifically, one comment
was "unclear if 'integrate' is a technical/specific term or just generic".
My assumption was that the word "integrate" was meant to be a generic
way to communicate "combine the changes in the two branches in
some unspecified way", and that's how I was using it. I'm not sure what
you mean when you say "integrate" (is it "merge"?).
I see a few options here:
1. Try to find a different word that communicates "combine the two
branches in a way that you have to specify". I'm not sure how
likely this is to succeed.
2. Instead of using the word "integrate", instead always say something
like "merge or rebase". I tried this but I found it a bit unwieldy, and
I think it might also be confusing for users who aren't familiar with
both merge and rebase, they might worry "do I need to understand
rebase to use `git pull`?", when of course you don't.
3. Keep the word "integrate".
I'm very open to hearing suggestions here, maybe there's another
better way I haven't thought of.
>> +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.
>
> This part has two orthogonal things, each of which has its own
> default, which may be a bit confusing. (1) which branch we get from
> the remote integrates with the current branch. The default is to
> use the upstream of our current branch. (2) how the integration
> between the remote thing and our current branch is done. The
> default is only to accept fast-forward updates.
>
> Perhaps it may help clarify the flow if we said upfront that we
> describe two orthgonal things? E.g.,
>
> First it fetches. Then it decides two things: what to integrage
> with the current branch, and how to do the integration. By
> default, the upstream branch of the current branch is what gets
> integrated, and by default "pull --ff-only" (described below) is
> how the integration is done.
>
> or something? I dunno.
I think I'm happy with how the two different defaults are being
described right now, but I'll run this by some folks and see
what they think.
next prev parent reply other threads:[~2025-10-09 21:35 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-23 19:44 [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-23 19:44 ` [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-09-24 20:17 ` D. Ben Knoble
2025-10-07 21:20 ` Julia Evans
2025-09-23 19:45 ` [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-09-24 20:23 ` D. Ben Knoble
2025-09-24 20:54 ` Julia Evans
2025-09-24 22:38 ` Chris Torek
2025-10-06 21:16 ` Julia Evans
2025-09-23 19:45 ` [PATCH 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-09-23 19:45 ` [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-09-24 17:21 ` Julia Evans
2025-09-24 20:29 ` D. Ben Knoble
2025-10-07 21:01 ` Julia Evans
2025-10-10 0:45 ` Ben Knoble
2025-09-24 19:56 ` [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section D. Ben Knoble
2025-10-08 19:25 ` [PATCH v2 " Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-08 21:33 ` Junio C Hamano
2025-10-09 21:31 ` Julia Evans [this message]
2025-10-09 22:20 ` Kristoffer Haugsbakk
2025-10-09 22:41 ` Junio C Hamano
2025-10-08 19:25 ` [PATCH v2 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 16:56 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Ben Knoble
2025-10-15 20:36 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=chris.torek@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox