From: "Julia Evans" <julia@jvns•ca>
To: "D. Ben Knoble" <ben.knoble@gmail•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch
Date: Wed, 24 Sep 2025 16:54:40 -0400 [thread overview]
Message-ID: <f6dea581-04c5-4b05-ab81-1fb06de1cf41@app.fastmail.com> (raw)
In-Reply-To: <CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com>
>> -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?
That's a good point, I'll try to think of a better way to phrase it.
I guess the truth is that `git pull` has three categories of options,
those it passes verbatim to `git fetch`, those it passes verbatim to `git merge`,
and the others (-q, -v, and --recurse-submodules).
That's a bit of a mouthful but maybe there's a way to say that explicitly
that isn't too awkward, it does seem helpful to know when reading the
OPTIONS section.
>> +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 find it confusing too. My current strategy for handling this here is to
somewhat awkwardly say "it's explained in the DEFAULT BEHAVIOUR section"
a bit further down.
It's a tricky situation because I find the DEFAULT BEHAVIOUR section very
confusing. It seems like there's a fair amount of duplication with other
sections that could be cleaned up to make it easier. But removing the
duplication and making it easier to understand feels like too many changes
for this series, especially because really doing it well probably involves the
sub-project of "clean up the <refspec> section of the `git fetch` man page".
In any case, I'll see if I can find a way to make it a little less awkward.
next prev parent reply other threads:[~2025-09-24 20:55 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 [this message]
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
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=f6dea581-04c5-4b05-ab81-1fb06de1cf41@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(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