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

Junio C Hamano [off-list ref] writes:

quoted

So I think the reasoning (i.e. "is a descendant" is not quite right)
is correct, but the updated text is not quite right.  Changing it
further to "only the committer timestamps and identities would
change" is probably not an improvement, either.  "Force the rebase
that would otherwise be a no-op" may be a better phrasing that does
not risk going stale even if we update what are preserved and what
are modified in the future.

Also I notice the sentence "Normally non-interactive...in such a
situation" is not helping the reader in this description very much.
I wonder if we should keep it if we are rewriting this paragraph.

How about doing it this way, perhaps?

-- >8 --
From: Sergey Organov <redacted>
Date: Tue, 12 Aug 2014 00:22:48 +0400
Subject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op

"Current branch is a descendant of the commit you are rebasing onto"
does not necessarily mean "rebase" requires "--force".  For a plain
vanilla "history flattening" rebase, the rebase can be done without
forcing if there is a merge between the tip of the branch being
rebased and the commit you are rebasing onto, even if the tip is
descendant of the other.

[jc: reworded both the text and the log description]

Signed-off-by: Sergey Organov <redacted>
Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/git-rebase.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

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

Junio C Hamano [off-list ref] writes:

quoted

So I think the reasoning (i.e. "is a descendant" is not quite right)
is correct, but the updated text is not quite right.  Changing it
further to "only the committer timestamps and identities would
change" is probably not an improvement, either.  "Force the rebase
that would otherwise be a no-op" may be a better phrasing that does
not risk going stale even if we update what are preserved and what
are modified in the future.

Also I notice the sentence "Normally non-interactive...in such a
situation" is not helping the reader in this description very much.
I wonder if we should keep it if we are rewriting this paragraph.

How about doing it this way, perhaps?

-- >8 --
From: Sergey Organov <redacted>
Date: Tue, 12 Aug 2014 00:22:48 +0400
Subject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op

"Current branch is a descendant of the commit you are rebasing onto"
does not necessarily mean "rebase" requires "--force".  For a plain
vanilla "history flattening" rebase, the rebase can be done without
forcing if there is a merge between the tip of the branch being
rebased and the commit you are rebasing onto, even if the tip is
descendant of the other.

[jc: reworded both the text and the log description]

Signed-off-by: Sergey Organov <redacted>
Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/git-rebase.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

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