Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.

> Sergey Organov <sorganov@gmail.com> writes:
>
>>> ...
>>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>>> index 2a93c64..f14100a 100644
>>> --- a/Documentation/git-rebase.txt
>>> +++ b/Documentation/git-rebase.txt
>>> @@ -316,11 +316,8 @@ which makes little sense.
>>>  
>>>  -f::
>>>  --force-rebase::
>>> -	Force the rebase even if the current branch is a descendant
>>> -	of the commit you are rebasing onto.  Normally non-interactive rebase will
>>> -	exit with the message "Current branch is up to date" in such a
>>> -	situation.
>>> -	Incompatible with the --interactive option.
>>> +	Force a rebase even if the current branch is up-to-date and
>>> +	the command without `--force` would return without doing anything.
>>>  +
>>>  You may find this (or --no-ff with an interactive rebase) helpful after
>>>  reverting a topic branch merge, as this option recreates the topic branch with
>>
>> I dig more into it, and that's what I came up with, using some of your
>> suggestions as well.
>>
>> Please notice new text on essential interaction with --preserve-merges.
>>
>> I also thought about "Force the rebase that would otherwise be a no-op",
>> and while it is future-changes-agnostic indeed, it doesn't actually
>> explain anything, so I put some explanation back.
>
> A sentence "--force has no effect under --preserve-merges mode" does
> not tell the readers very much, either and leaves them wondering if
> it means "--preserve-merges mode always rebases every time it is
> asked, never noticing 'ah, the history is already in a good shape
> and there is no need to do anything further'" or "--preserve-merges
> mode ignores --force and refuses to recreate the history if the
> history is in the shape the mode deems is already desirable."

> I think the root cause of the issue we share in this thread, when
> trying to come up with an improvement of this part, is that we are
> trying to put more explanation to the description of --force, but if
> we step back a bit, it may be that the explanation does not belong
> there.  As far as the readers are concerned, --force is about
> forcing a rebase that would not otherwise be a no-op, but the real
> issue is that the condition under which a requested rebase becomes a
> no-op, iow, "the history is already in the desired shape, nothing to
> do", is different from mode to mode, because "the desired shape" is
> what distinguishes the modes.  Preserve-merge rebase may think that
> a history that is descendant of the "onto" commit is already in the
> desired shape while plain-vanilla rebase does not if it has a merge
> in between, for example.

> The desired outcome depends on the mode (and that is why there are
> modes), and not saying that explicitly will only help spread the
> confusion, I am afraid.  Isn't it a better solution to explain what
> that no-op condition is for the mode at the place in the document
> where we describe each mode?
>
> E.g. under "--preserve-merges" heading, we may say "make sure the
> history is a descendant of the 'onto' commit; if it already is,
> nothing is done because there is no need to do anything" or
> something along that line.  The description for the plain-vanilla
> rebase may say "flatten the history on top of the 'onto' commit by
> replaying the changes in each non-merge commit; if the history is
> already a descendant of the 'onto' commit without any merge in
> between, nothing is done because there is no need to".
>
> That would make description of the modes more understandable, too.
> The users can read what kind of resulting history they can get out
> of by using each mode in one place.