Junio C Hamano <gitster@xxxxxxxxx> writes: > Sergey Organov <sorganov@xxxxxxxxx> 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." 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. -- Sergey. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html