Junio C Hamano <gits...@pobox.com> writes:
> Sergey Organov <sorga...@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.
>>> - Force the rebase even if the current branch is a descendant
>>> - of the commit you are rebasing onto. Normally non-interactive rebase
>>> - 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
>> 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."
In fact there is no way to force rebase when --preserve-merges is given.
Neither --force nor --no-ff has any effect.
Maybe some clarification could be given in --preserve-merges
description, provided it's not clear that "has no effect" for --force
means that one can't force the rebase in this case.
> 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.
I think the root cause is even deeper, in the current design of the
rebase interface, but those my opinion you already know and I'll leave
discussion for another post that I currently try to formulate.
> The sentence that follows "Otherwise" in this version encourages the
> readers to be in a wrong mind-set that rebase is only about "making
> the branch a descendant of the 'onto' commit", which isn't the case.
I'm not happy with the wording myself either.
> 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.
I think you've lost me here, though I think that all the suggested
variants are still better than what is there right now.
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html