Re: re-mentioning --preserve-merges in the docs

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

[-- Attachment #1: Type: text/plain, Size: 2509 bytes --]

Hi Junio,

On Thu, 21 Jul 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
> > On Tue, Sep 07 2021, Johannes Schindelin via GitGitGadget wrote:
> >
> >> From: Johannes Schindelin <johannes.schindelin@gmx.de>
> >> [...]
> >> --p::
> >> ---preserve-merges::
> >> -	[DEPRECATED: use `--rebase-merges` instead] Recreate merge commits
> >> -	instead of flattening the history by replaying commits a merge commit
> >> -	introduces. Merge conflict resolutions or manual amendments to merge
> >> -	commits are not preserved.
> >
> > [In reply to an old commit]
> >
> > I opened "man git-rebase" today due to an on-list discussion and went
> > through pretty much:
> >
> >  1. /preserve-merges # fails
> >  2. skimming the SYNOPSIS, forgetting what the new thing is called
> >  3. Paging down, eventually findinging & remembering the new thing is
> >     "--rebase-merges".
> >
> > I wonder if there's objections to reinstating this in the docs
> > somewhere, just as something like:
> >
> > 	--preserve-merges:
> > 		An old "rebase" backend which is no longer supported,
> > 		and which was removed from git in version v2.35.0.
> >
> > We don't do that with all flags that we've dropped, but perhaps this one
> > was well known enough to not leave readers hanging...
>
> My impression is that we consider that we have done so already for a
> few releases by keeping "DEPRECATED: use rebase-merges", exactly
> because "this one was well known enough", and now it is time to go
> one step further, i.e. drop it from the document like the quoted
> patch does, while recognising an attempt to use the option and
> giving a custom message than the bog-standard "unknown option".
>
>     $ git rebase --preserve-merges
>     fatal: --preserve-merges was replaced by --rebase-merges
>     Note: Your `pull.rebase` configuration may also be set to 'preserve',
>     which is no longer supported; use 'merges' instead
>
> The next step will be to drop that custom error support, I think.

Fully agree.

I _could_ see us introducing a sentence in the explanation of
`--rebase-merges` that leaves a historical note about superseding the
now-removed `--preserve-merges` option. But such historical notes tend to
go pretty stale pretty quickly, and eventually cause more confusion than
clarification.

So just like you said, I'd rather not re-introduce any text mentioning
`--preserve-merges` into the manual page.

Ciao,
Dscho