Re: [PATCH] doc: pull: fix rebase=false documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 22, 2021, 01:24 UTC
Message-ID: <60f8c8c92a215_1d0abb20859@natae.notmuch>
In-Reply-To: <xmqqtukn9p0g.fsf@gitster.g>

Junio C Hamano wrote:

Show 22 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
> > Felipe Contreras <felipe.contreras@gmail.com> writes:
> >
> >> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> >> index 5c3fb67c01..7f4b2d1982 100644
> >> --- a/Documentation/git-pull.txt
> >> +++ b/Documentation/git-pull.txt
> >> @@ -117,7 +117,7 @@ When set to `preserve` (deprecated in favor of `merges`), rebase with the
> >>  `--preserve-merges` option passed to `git rebase` so that locally created
> >>  merge commits will not be flattened.
> >>  +
> >> -When false, merge the current branch into the upstream branch.
> >> +When false, merge the upstream branch into the current branch.
> >>  +
> >>  When `interactive`, enable the interactive mode of rebase.
> >>  +
> >
> > Looks correct.  Will queue.  Thanks.
> 
> By the way, I'll update the proposed log message to say only that
> the documentation needs to be fixed as it does not say what the
> command does.

Fine by me, although I'd appreciate if you minimize the use of your words and maximize the use of mine.

  The documentation says --rebase=false merges our current branch into
  the upstream branch, and while many people think that's what should
  happen, that's not what actually happens; it's the *opposite*.

  Fix the documentation so that we explain what the code actually does.

> We should be able to fix the inaccuracies in the
> documentation quickly without advocating different behaviour or
> trashing the current behaviour in the proposed log message.

I'm not trashing the current behavior, I'm explaining what the consensus is. I spent several man-days re-reading old threads, and this is the consensus of what should happen:

  1. git pull              # merge HEAD into upstream
  2. git pull origin topic # merge topic into HEAD

Of the people that expressed an opinion, 100% of them stated that what `git pull` does in the first case today is not desirable.

> I also happen to think that "flipping the merge order" is not a good
> thing to do anyway [*1*]; keeping the log message to state just "the
> description does not reflect reality-fix it" has the added benefit
> that we do not have to debate it.

But people have spent many hours debating it already.

Yes, you are correct that if *everyone* followed the topic branch workflow, everything would work correctly, but that's not what happens in reality, in reality people do all kinds of workflows, and wrong merges are pervasive.

Everyone--including Linus, Jeff, and you--agree that there's two different ways of using `git pull`: integrator versus developer.

When a user is doing `git pull` to synchronize changes to push to the same branch, that's a centralized two-way workflow, so he is acting both as an integrator and as a developer, and it's in that particular case that the order of the parents should be reversed. Everyone agrees on that.

When the user the opposite explicitely: `git pull origin master` Linus calls it a "back-merge" [1], and in that case the order of the parents should not be reversed.

This has already been discussed many times, and the problem remains.

[1] https://lore.kernel.org/git/CA+55aFwM0vy+pw-Xv=gA19ULMwAXNPhdO3qR5A3hkMrZKJFNSQ@mail.gmail.com/

-- 
Felipe Contreras