doc: git-pull: clarify DESCRIPTION section #1976
+40
−53
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,68 +15,53 @@ SYNOPSIS | |
| DESCRIPTION | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> 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.
In other words, you cloned or made yourself in-sync with the remote
earlier, the remote may or may not have progressed before your
'pull'. If you created your own commits on top of the state that
was in sync with them, you diverged from them and --ff-only is
stopped in such a case. If you haven't changed your branch since
you were in sync with them the last time, --ff-only would
fast-forward your branch to match what they have.
> +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.
> +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.
There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email protected]> 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.There was a problem hiding this comment. On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this): On Thu, Oct 9, 2025, at 23:31, Julia Evans wrote:
> On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:
>>>[snip]
>>> +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".
(confusing)
>
> 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 wonder if “integration” is like “upstream”; frequently used but not
really explained? (see gitworkflows(7); one mention in gitglossary(7)).
I think Martin Fowler has the correct (useful) view on branches:[1]
In thinking about these patterns, I find it useful to develop two
main categories. One group looks at integration, how multiple
developers combine their work into a coherent whole. The other looks
at the path to production, using branching to help manage the route
from an integrated code base to a product running in production.
Specifically the first category.
Then later:
Branching is about managing the interplay of isolation and
integration. Having everyone work on a single shared codebase all
the time, doesn't work because I can't compile the program if you're
in the middle of typing a variable name. So at least to some degree,
we need a notion of a private workspace that I can work on for a
while. Modern source code controls tools make it easy to branch and
monitor changes to those branches. At some point however we need to
integrate. Thinking about branching strategies is really all about
deciding how and when we integrate.
🔗 1: https://martinfowler.com/articles/branching-patterns.html
The point of *most* branches ought to be this: you need isolation, but
you also want to eventually integrate with upstream, the trunk, or
whatever else.
• Everyone working on everything at the same time is chaos
• Everyone working on their own thing in isolation forever is
Balkanization
• Forking a private space to integrate later in a timely manner strikes
the right balance
• (Then there are the dozens of variations of long-living forks, private
forks for the changes that you want to make but few others want...)
So I don’t think that
> "combine the changes in the two branches in some unspecified way"
is quite it, because the direction is towards one integration branch,
one upstream, one trunk, main branch (not whichever one).
> 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
... and regarding “unspecified”: I suspect the contention might be
distinction between integrating the branchy itself (with those commits)
with replaying fresh commits (rebase). But I don’t know.
>
>[snip]There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans" <[email protected]> writes:
> 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.
It is how I was using it, too.
> I'm not sure what
> you mean when you say "integrate" (is it "merge"?).
Not limited to "merge", but I view it more as between two parties,
one side supplies changes while the other side serves as a base. A
merge looks as if the changes of a side branch gets incorporated
into the trunk. A rebase looks as if the changes you have created
gets incorporated into the trunk by replaying them onto the trunk.
> 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.
I am not particularly good at finding verbs, sorry.
> 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.
Very true.
|
||
| ----------- | ||
|
|
||
| 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. | ||
| 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`, | ||
|
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` :)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.There was a problem hiding this comment. On the Git mailing list, Ben Knoble wrote (reply to this): > Le 7 oct. 2025 à 17:01, Julia Evans <[email protected]> a écrit :
>
>
>
>> 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.
While fiddling around: turns out reset’s merge flag does abort the merge properly. TMTOWTDI, I suppose.
>>
>>> --- 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.
I’d probably prefer to keep the pull->{merge,rebase} implication. I just want « how do I know which one » to be clear. |
||
| or `pull.ff` with your preferred behaviour. | ||
|
|
||
| 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`. | ||
|
|
||
| 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,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 <<fetch-refspec,<refspec>>> below under "Options related to fetching" | ||
| for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below | ||
| for how `git pull` uses this argument to determine which remote branch | ||
| to integrate. | ||
|
|
||
| -q:: | ||
| --quiet:: | ||
| This is passed to both underlying git-fetch to squelch reporting of | ||
|
|
@@ -145,6 +130,7 @@ include::urls-remotes.adoc[] | |
|
|
||
| include::merge-strategies.adoc[] | ||
|
|
||
| [[DEFAULT-BEHAVIOUR]] | ||
| DEFAULT BEHAVIOUR | ||
| ----------------- | ||
|
|
||
|
|
||
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
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Chris Torek wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):