doc: git-pull: clarify DESCRIPTION section #1976
Open
+40
−53
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jvns
force-pushed
the
clarify-pull
branch
2 times, most recently
from
4761d96 to
c7f09c2
Compare
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' | ||
| with uncommitted changes is discouraged: while possible, it leaves you | ||
| in a state that may be hard to back out of in the case of a conflict. | ||
| You can also set the configuration options `pull.rebase`, `pull.squash`, |
There was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
On Tue, Sep 23, 2025, at 3:45 PM, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <[email protected]>
>
> From user feedback:
>
> - One user is confused about why `git reset --merge`
> (why not just `git reset`?). Handle this by mentioning
> `git merge --abort` and `git reset --abort` instead, which have a
> more obvious meaning.
> - 2 users want to know what "In older versions of Git" means exactly
> (in versions older than 1.7.0). Handle this by removing the warning
> since it was added 15 years ago (in 3f8fc184c0e2c)
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-pull.adoc | 12 +++---------
> 1 file changed, 3 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
> index 91903b0a94..eec05ab6c7 100644
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the
> remote branch:
> You can also set the configuration options `pull.rebase`,
> `pull.squash`,
> or `pull.ff` with your preferred behaviour.
>
> -In Git 1.7.0 or later, to cancel a conflicting merge, use
> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'
> -with uncommitted changes is discouraged: while possible, it leaves you
> -in a state that may be hard to back out of in the case of a conflict.
> -
> -If any of the remote changes overlap with local uncommitted changes,
> -the merge will be automatically canceled and the work tree untouched.
> -It is generally best to get any local changes in working order before
> -pulling or stash them away with linkgit:git-stash[1].
After sending this I thought to read the `git merge` man page, which has
this warning:
> WARNING: Running `git merge` with non-trivial uncommitted changes is
discouraged: while possible, it may leave you in a state that is hard to
back out of in the case of a conflict.
I think I was probably too hasty in removing the warning entirely, since I
mainly use `git pull --rebase` and I hadn't fully thought through how
`git merge` has a different approach to uncommitted changes than
`git rebase`.
I think a warning similar to that one would make sense, since any warning
that applies to `git merge` should also apply to `git pull`.
> +If there's a merge conflict during the merge or rebase that you don't
> +want to handle, you can safely abort it with `git merge --abort` or `git
> +--rebase abort`.
Also I noticed a typo in `git --rebase abort` :)
|
On the Git mailing list, "D. Ben Knoble" wrote (reply to this): On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> I got feedback from 15 Git users on the current git pull man page, using
> this tool: https://text-feedback.wizardzines.com/git-pull.
>
> My goals here are to be clear about the relationship between git pull and
> fetch/merge/rebase etc, make sure users know the current default for git
> pull (--ff-only) since some folks still remember the old default, and to
> help users quickly figure out what command they need to run to
> merge/rebase/squash/etc.
Huh! I thought pull would merge divergent histories by default, and
even now it's hard to extract that info from the manual (the first
paragraph actually mentions reconciliation via --rebase/--no-rebase,
but I thought --no-rebase was still the default). TIL, thanks!
> I've taken a pretty aggressive approach because I think it's possible to
> have a pretty short and focused DESCRIPTION section here while keeping the
> most important info. Open to hearing that I've removed too much.
>
> This references the UPSTREAM BRANCHES section from
> https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/
> , so if that isn't merged I'll need to revisit the approach here.
A common way to handle this is to build your topic on top of the topic
you depend on, and then mention that in your cover letter. I'm not
sure how GitGitGadget handles that, though, since with format-patch
you could then specify to send patches only from
<other-topic>..<this-topic>. So I think this is probably ok?
--
D. Ben Knoble |
|
User |
Documentation/git-pull.adoc
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> From user feedback:
>
> - it's confusing that we use both <branch> and <refspec> to refer to the
> second argument
Yep.
> - one user is not clear about what `refs/heads/*:refs/remotes/origin/*`
> is meant to be an example of ("is it like a path?")
Also yep, since the deleted text doesn't contain any pointers to learn
what a refspec is.
> The DESCRIPTION section is also doing a lot right now: it's trying to
> describe both how the <repository> and <refspec> arguments work (which
> is pretty complex, as seen in the DEFAULT BEHAVIOUR section)
> as well as how `git pull` calls `git fetch` and merge/rebase/etc
> depending on the arguments.
>
> Handle this by moving the description of the <repository> and <refspec>
> arguments to the OPTIONS section, so that we can focus on the
> merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks
> to the later sections for details.
I generally like this: it makes things a bit more consistent, even
though "options" isn't quite how I think of these (optional!)
positional parameters. Still, I generally jump down to the <arg>
sections (like in git-push(1)) to learn what I can do with those.
> Use the term "upstream" instead of 'the "remote" and "merge"
> configuration for the current branch' since users are more likely to
> know what an "upstream" is.
With the upstream section, great.
> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
> index 48e924a10a..50af7fde81 100644
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,
> will call either `git rebase` or `git merge` to reconcile diverging
> branches.
>
> -<repository> should be the name of a remote repository as
> -passed to linkgit:git-fetch[1]. <refspec> can name an
> -arbitrary remote ref (for example, the name of a tag) or even
> -a collection of refs with corresponding remote-tracking branches
> -(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
> -but usually it is the name of a branch in the remote repository.
> -
> -Default values for <repository> and <branch> are read from the
> -"remote" and "merge" configuration for the current branch
> -as set by linkgit:git-branch[1] `--track`.
And we don't even mind losing "--track" here because we cover it in
Upstream Branches (e.g.,
https://lore.kernel.org/git/3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com/).
> -
> Assume the following history exists and the current branch is
> "`master`":
>
> @@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].
> OPTIONS
> -------
>
> +<repository>::
> + The "remote" repository to pull from. This can be either
> + a URL (see the section <<URLS,GIT URLS>> below) or the name
> + of a remote (see the section <<REMOTES,REMOTES>> below).
> ++
> +Defaults to the configured upstream for the current branch, or `origin`.
> +See UPSTREAM BRANCHES below for more on how to configure upstreams.
> +
> +<refspec>::
> + Which branch or other reference(s) to fetch and integrate into the
> + current branch, for example `main` in `git pull origin main`.
> + Defaults to the configured upstream for the current branch.
> ++
> +This can be a branch, tag, or other collection of reference(s).
> +See <refspec> below under "Options related to fetching" for the full syntax,
> +and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to
> +determine which remote branch to integrate.
> +
I think these are covered in Documentation/pull-fetch-param.adoc,
which I only found by looking at "git help pull" and searching for the
URLs references, hah.
Anyway, the existing explanations are far too late in the manual (Vim
says ~46%, 960 lines down, when rendered with MANWIDTH=80). Moving
them up is a good idea, but maybe we need to do that in a way that
jives with the later "fetching" section. Hm.
--
D. Ben KnobleThere was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
On Wed, Sep 24, 2025, at 4:17 PM, D. Ben Knoble wrote:
> On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget
> <[email protected]> wrote:
>>
>> From: Julia Evans <[email protected]>
>>
>> From user feedback:
>>
>> - it's confusing that we use both <branch> and <refspec> to refer to the
>> second argument
>
> Yep.
>
>> - one user is not clear about what `refs/heads/*:refs/remotes/origin/*`
>> is meant to be an example of ("is it like a path?")
>
> Also yep, since the deleted text doesn't contain any pointers to learn
> what a refspec is.
>
>> The DESCRIPTION section is also doing a lot right now: it's trying to
>> describe both how the <repository> and <refspec> arguments work (which
>> is pretty complex, as seen in the DEFAULT BEHAVIOUR section)
>> as well as how `git pull` calls `git fetch` and merge/rebase/etc
>> depending on the arguments.
>>
>> Handle this by moving the description of the <repository> and <refspec>
>> arguments to the OPTIONS section, so that we can focus on the
>> merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks
>> to the later sections for details.
>
> I generally like this: it makes things a bit more consistent, even
> though "options" isn't quite how I think of these (optional!)
> positional parameters. Still, I generally jump down to the <arg>
> sections (like in git-push(1)) to learn what I can do with those.
>
>> Use the term "upstream" instead of 'the "remote" and "merge"
>> configuration for the current branch' since users are more likely to
>> know what an "upstream" is.
>
> With the upstream section, great.
>
>> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
>> index 48e924a10a..50af7fde81 100644
>> --- a/Documentation/git-pull.adoc
>> +++ b/Documentation/git-pull.adoc
>> @@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,
>> will call either `git rebase` or `git merge` to reconcile diverging
>> branches.
>>
>> -<repository> should be the name of a remote repository as
>> -passed to linkgit:git-fetch[1]. <refspec> can name an
>> -arbitrary remote ref (for example, the name of a tag) or even
>> -a collection of refs with corresponding remote-tracking branches
>> -(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
>> -but usually it is the name of a branch in the remote repository.
>> -
>> -Default values for <repository> and <branch> are read from the
>> -"remote" and "merge" configuration for the current branch
>> -as set by linkgit:git-branch[1] `--track`.
>
> And we don't even mind losing "--track" here because we cover it in
> Upstream Branches (e.g.,
> https://lore.kernel.org/git/3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com/).
>
>> -
>> Assume the following history exists and the current branch is
>> "`master`":
>>
>> @@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].
>> OPTIONS
>> -------
>>
>> +<repository>::
>> + The "remote" repository to pull from. This can be either
>> + a URL (see the section <<URLS,GIT URLS>> below) or the name
>> + of a remote (see the section <<REMOTES,REMOTES>> below).
>> ++
>> +Defaults to the configured upstream for the current branch, or `origin`.
>> +See UPSTREAM BRANCHES below for more on how to configure upstreams.
>> +
>> +<refspec>::
>> + Which branch or other reference(s) to fetch and integrate into the
>> + current branch, for example `main` in `git pull origin main`.
>> + Defaults to the configured upstream for the current branch.
>> ++
>> +This can be a branch, tag, or other collection of reference(s).
>> +See <refspec> below under "Options related to fetching" for the full syntax,
>> +and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to
>> +determine which remote branch to integrate.
>> +
>
> I think these are covered in Documentation/pull-fetch-param.adoc,
> which I only found by looking at "git help pull" and searching for the
> URLs references, hah.
>
> Anyway, the existing explanations are far too late in the manual (Vim
> says ~46%, 960 lines down, when rendered with MANWIDTH=80). Moving
> them up is a good idea, but maybe we need to do that in a way that
> jives with the later "fetching" section. Hm.
That's a good point. It's a bit weird because (I think) `git pull does use the
<refspec> parameter after passing it to `git fetch` (to decide which
remote branch to merge), so we can't just say "to know what the refspec
parameter does, see "git fetch", and we can't just copy the existing
<refspec> section further up.
Rewriting the <refspec> section of `git fetch` so that it addresses both the
`git pull` and `git fetch` case seems like it would just add more confusion.
Duplicating the content of the <repository> bit and then referencing
the second <refspec> section below is the least bad option I can think of
right now, since most of the time you don't actually need to know how to
write a refspec.
I'll add some internal links in the HTML version to the <refspec>
and DEFAULT BEHAVIOUR sections so that they'll be easier to find in the
HTML version at least.
| 'git pull' [<options>] [<repository> [<refspec>...]] | ||
|
|
||
|
|
||
| DESCRIPTION |
There was a problem hiding this comment.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> 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 <[email protected]>
> ---
> 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!
> 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 KnobleThere was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
>> -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.There was a problem hiding this comment.
On the Git mailing list, Chris Torek wrote (reply to this):
On Wed, Sep 24, 2025 at 1:23 PM D. Ben Knoble <[email protected]> wrote:
> > +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?
I would suggest "equivalent" or (perhaps better) "appropriate".
Perhaps even:
First, `git pull` runs the equivalent of `git fetch` with the
arguments needed to fetch necessary branches from
the remote ...
Definition of these arguments can be deferred (perhaps
even indefinitely); but:
> > +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.
here we'd need something along the lines of:
Then it integrates the appropriate remote branch ...
and here we *do* have to define "appropriate".
(Historically the merge step grabbed stuff from FETCH_HEAD,
excluding all the "not-for-merge" parts, and I have never dug into
what happens now...)
ChrisThere was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
On Wed, Sep 24, 2025, at 6:38 PM, Chris Torek wrote:
> On Wed, Sep 24, 2025 at 1:23 PM D. Ben Knoble <[email protected]> wrote:
>> > +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?
>
> I would suggest "equivalent" or (perhaps better) "appropriate".
> Perhaps even:
>
> First, `git pull` runs the equivalent of `git fetch` with the
> arguments needed to fetch necessary branches from
> the remote ...
>
> Definition of these arguments can be deferred (perhaps
> even indefinitely); but:
>
>> > +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.
>
> here we'd need something along the lines of:
>
> Then it integrates the appropriate remote branch ...
>
> and here we *do* have to define "appropriate".
I like the idea of adding "appropriate" here. The question of how to define
it is a little messy.
We do define "appropriate" below under <refspec>, like this:
> See <refspec> below under "Options related to fetching" for the full syntax,
> and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to
> determine which remote branch to integrate.
Like I mentioned in another reply I think deferring the question of what "the
appropriate branch" is to the DEFAULT BEHAVIOUR section like this does is not
a "good" long-term solution because that section is so confusing, but I think
it's not worse than the current state and I don't want to expand the scope of
this patch series too much.
However! I think there's a question of what behaviour to "encourage".
Over on the `git push` side, we decided to highlight using
`git push origin main` to push, because the behaviour of `git push origin main`
is simple to explain ("it pushes the local main branch to the main on the `origin`
remote").
So a natural next question is: should we equivalently highlight
"git pull origin main", to mirror the `git push` man page?
Then it would be easy to say what "the appropriate branch" is, because in that
case the branch is "whatever branch you specified"
My initial instinct is "no": `git push origin main` also feels sort of "foolproof" to me,
in the sense that if you accidentally run it while on the wrong branch, nothing
really bad will happen, since it doesn't matter what your current branch is.
But `git pull` is not the same, since running `git pull origin <wrong-branch>` will
integrate <wrong-branch> into your current branch, which could get confusing if
you accidentally pulled while on the wrong branch. Personally I use `git pull`
without any arguments, and it feels safer to me that way because I know that I'm
likely to have set my upstream to something reasonable.
I also did some extremely informal and low-sample-size Mastodon polling
and my sense so far is that folks tend to run `git pull` with no arguments in
practice. So I think it makes sense to highlight the no-arguments version.
And in any case if you want to get really specific about what you're pulling I
think going straight to "manually fetch and then run `git merge` yourself" is
a safer approach instead of passing arguments to `git pull`.
All of that is to say: my best idea for how to resolve all of this is as follows:
> 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 for the current branch.
> Then it integrates that branch into the current branch.
This explains what the "appropriate branch" is in (I think) the most common
use case and deals with the "same arguments" issue.
| `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' | ||
| with uncommitted changes is discouraged: while possible, it leaves you | ||
| in a state that may be hard to back out of in the case of a conflict. | ||
| You can also set the configuration options `pull.rebase`, `pull.squash`, |
There was a problem hiding this comment.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> From user feedback:
>
> - One user is confused about why `git reset --merge`
> (why not just `git reset`?). Handle this by mentioning
> `git merge --abort` and `git reset --abort` instead, which have a
> more obvious meaning.
"git reset --merge" _can_ be helpful when merging, but won't fully
abort a rebase. Great.
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:
> You can also set the configuration options `pull.rebase`, `pull.squash`,
> or `pull.ff` with your preferred behaviour.
>
> -In Git 1.7.0 or later, to cancel a conflicting merge, use
> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'
> -with uncommitted changes is discouraged: while possible, it leaves you
> -in a state that may be hard to back out of in the case of a conflict.
> -
> -If any of the remote changes overlap with local uncommitted changes,
> -the merge will be automatically canceled and the work tree untouched.
> -It is generally best to get any local changes in working order before
> -pulling or stash them away with linkgit:git-stash[1].
> +If there's a merge conflict during the merge or rebase that you don't
> +want to handle, you can safely abort it with `git merge --abort` or `git
> +--rebase abort`.
This information is also mentioned in the advice given by conflicts
(and git status), so while I originally wondered if we need to say "to
know which to use, run…", I now think we can trust users to know
whether they asked for a merge or rebase and read the advice/git
status output when they don't.
Hah, just kidding. Nobody* reads that output. But I still don't think
it's worth muddying here, because the same folks are unlikely to see
the help here, right? Or maybe we say "Information in `git status`
will summarize these options for you." ?
[*] Obviously untrue, but you all know what I mean
--
D. Ben KnobleThere was a problem hiding this comment.
On the Git mailing list, "Julia Evans" wrote (reply to this):
On Wed, Sep 24, 2025, at 4:29 PM, D. Ben Knoble wrote:
> On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget
> <[email protected]> wrote:
>>
>> From: Julia Evans <[email protected]>
>>
>> From user feedback:
>>
>> - One user is confused about why `git reset --merge`
>> (why not just `git reset`?). Handle this by mentioning
>> `git merge --abort` and `git reset --abort` instead, which have a
>> more obvious meaning.
>
> "git reset --merge" _can_ be helpful when merging, but won't fully
> abort a rebase. Great.
>
>> --- a/Documentation/git-pull.adoc
>> +++ b/Documentation/git-pull.adoc
>> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:
>> You can also set the configuration options `pull.rebase`, `pull.squash`,
>> or `pull.ff` with your preferred behaviour.
>>
>> -In Git 1.7.0 or later, to cancel a conflicting merge, use
>> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'
>> -with uncommitted changes is discouraged: while possible, it leaves you
>> -in a state that may be hard to back out of in the case of a conflict.
>> -
>> -If any of the remote changes overlap with local uncommitted changes,
>> -the merge will be automatically canceled and the work tree untouched.
>> -It is generally best to get any local changes in working order before
>> -pulling or stash them away with linkgit:git-stash[1].
>> +If there's a merge conflict during the merge or rebase that you don't
>> +want to handle, you can safely abort it with `git merge --abort` or `git
>> +--rebase abort`.
>
> This information is also mentioned in the advice given by conflicts
> (and git status), so while I originally wondered if we need to say "to
> know which to use, run…", I now think we can trust users to know
> whether they asked for a merge or rebase and read the advice/git
> status output when they don't.
>
> Hah, just kidding. Nobody* reads that output. But I still don't think
> it's worth muddying here, because the same folks are unlikely to see
> the help here, right? Or maybe we say "Information in `git status`
> will summarize these options for you." ?
I think it's a nice way to reiterate that `git pull` is running a merge or
rebase under the hood, but if folks feel strongly that this isn't relevant
I'd be happy to remove the `git merge --abort` / `git rebase --abort` note.
|
This patch series was integrated into seen via git@db6d7cb. |
|
User |
|
This patch series was integrated into seen via git@712b411. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@66f0c86. |
|
This patch series was integrated into seen via git@305a9a2. |
|
There was a status update in the "Cooking" section about the branch Documentation updates. source: <[email protected]> |
|
This patch series was integrated into seen via git@1c7229f. |
|
This patch series was integrated into seen via git@f66db48. |
|
This patch series was integrated into seen via git@2156993. |
|
This patch series was integrated into seen via git@89e35af. |
|
This patch series was integrated into seen via git@412b031. |
|
This patch series was integrated into seen via git@5ef8c8e. |
|
This patch series was integrated into seen via git@020584a. |
|
There was a status update in the "Cooking" section about the branch Documentation updates. source: <[email protected]> |
From user feedback:
- it's confusing that we use both <branch> and <refspec> to refer to the
second argument
- one user is not clear about what `refs/heads/*:refs/remotes/origin/*`
is meant to be an example of ("is it like a path?")
The DESCRIPTION section is also doing a lot right now: it's trying to
describe both how the <repository> and <refspec> arguments work (which
is pretty complex, as seen in the DEFAULT BEHAVIOUR section)
as well as how `git pull` calls `git fetch` and merge/rebase/etc
depending on the arguments.
Handle this by moving the description of the <repository> and <refspec>
arguments to the OPTIONS section, so that we can focus on the
merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks
to the later sections for details.
Use the term "upstream" instead of 'the "remote" and "merge"
configuration for the current branch' since users are more likely to
know what an "upstream" is.
Signed-off-by: Julia Evans <[email protected]>
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 <[email protected]>
From user feedback: this example is confusing because it implies that `git pull` will run `git merge` by default, but the default is `--ff-only`. We could instead show an example of a fast-forward merge, but that may not add a lot since fast-forward merges are relatively simple. This lets us keep the description short. Signed-off-by: Julia Evans <[email protected]>
From user feedback: - One user is confused about why `git reset --merge` (why not just `git reset`?). Handle this by mentioning `git merge --abort` and `git reset --abort` instead, which have a more obvious meaning. - 2 users want to know what "In older versions of Git" means exactly (in versions older than 1.7.0). Handle this by removing the warning since it was added 15 years ago (in 3f8fc18) Signed-off-by: Julia Evans <[email protected]>
|
This patch series was integrated into seen via git@42a49fb. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I got feedback from 15 Git users on the current
git pullman page, using this tool: https://text-feedback.wizardzines.com/git-pull.My goals here are to be clear about the relationship between
git pulland fetch/merge/rebase etc, make sure users know the current default forgit pull(--ff-only) since some folks still remember the old default, and to help users quickly figure out what command they need to run to merge/rebase/squash/etc.I've taken a pretty aggressive approach because I think it's possible to have a pretty short and focused DESCRIPTION section here while keeping the most important info. Open to hearing that I've removed too much.
This references the UPSTREAM BRANCHES section from https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/ , so if that isn't merged I'll need to revisit the approach here.
cc: "D. Ben Knoble" [email protected]
cc: Chris Torek [email protected]