{"thread":{"id":"37330","subject":"[PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","startedAt":"2014-08-11T20:22:48Z","lastAt":"2014-08-19T10:05:06Z","messageCount":14,"participants":["Sergey Organov","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"247596","messageId":"87bnrq22uf.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":null,"subject":"[PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-11T20:22:48Z","receivedAt":"2014-08-11T20:22:48Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Previous description of -f option was wrong as \"git rebase\" does not\nrequire -f to perform rebase when \"current branch is a descendant of\nthe commit you are rebasing onto\", provided commit(s) to be rebased\ncontain merge(s).\n\nSigned-off-by: Sergey Organov \n---\n Documentation/git-rebase.txt | 7 +++----\n 1 file changed, 3 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 2a93c64..62dac31 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -316,10 +316,9 @@ which makes little sense.\n \n -f::\n --force-rebase::\n-\tForce the rebase even if the current branch is a descendant\n-\tof the commit you are rebasing onto. Normally non-interactive rebase will\n-\texit with the message \"Current branch is up to date\" in such a\n-\tsituation.\n+\tForce the rebase even if the result will only change commit\n+\ttimestamps. Normally non-interactive rebase will exit with the\n+\tmessage \"Current branch is up to date\" in such a situation.\n \tIncompatible with the --interactive option.\n +\n You may find this (or --no-ff with an interactive rebase) helpful after\n-- \n1.9.3\n"},{"id":"247619","messageId":"xmqq4mxh5w34.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"87bnrq22uf.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-12T19:47:27Z","receivedAt":"2014-08-12T19:47:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Previous description of -f option was wrong as \"git rebase\" does not\n> require -f to perform rebase when \"current branch is a descendant of\n> the commit you are rebasing onto\", provided commit(s) to be rebased\n> contain merge(s).\n\nBoth the above and the updated documentation are a bit hard to read\nfor me, so let me disect what you are and you are not saying to see\nif I understood them correctly:\n\n - The plain-vanilla \"git rebase\" that flattens the history will be\n a no-op *only* when the current tip is a linear descendant of the\n \"onto\" commit without any merge in between.\n\n - Merge-preserving form of \"git rebase -m/-p\" is a no-op when the\n current tip is a descendant of the \"onto\" commit.\n\n - \"rebase -f\" is a way to force rebase when it would otherwise be a\n no-op.\n\n - When you force a rebase that would otherwise be a no-op, only the\n timestamps would change.\n\nI think you are right that 'current branch is a descendant of the\n\"onto\" commit' is not necessarily equal to 'rebase that would\notherwise be a no-op'. I am not sure if a 'rebase that would\notherwise be a no-op' is equal to 'only timestamp would change',\nthough. What happens if you do this, for example?\n\n $ GIT_COMMITTER_NAME='Somebody Else' git commit\n $ git rebase --force --onto HEAD^ HEAD^ HEAD^0\n\nSo I think the reasoning (i.e. \"is a descendant\" is not quite right)\nis correct, but the updated text is not quite right. Changing it\nfurther to \"only the committer timestamps and identities would\nchange\" is probably not an improvement, either. \"Force the rebase\nthat would otherwise be a no-op\" may be a better phrasing that does\nnot risk going stale even if we update what are preserved and what\nare modified in the future.\n\nAlso I notice the sentence \"Normally non-interactive...in such a\nsituation\" is not helping the reader in this description very much.\nI wonder if we should keep it if we are rewriting this paragraph.\n\nThanks.\n\n> Signed-off-by: Sergey Organov \n> ---\n> Documentation/git-rebase.txt | 7 +++----\n> 1 file changed, 3 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index 2a93c64..62dac31 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -316,10 +316,9 @@ which makes little sense.\n> \n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> +\tForce the rebase even if the result will only change commit\n> +\ttimestamps. Normally non-interactive rebase will exit with the\n> +\tmessage \"Current branch is up to date\" in such a situation.\n> \tIncompatible with the --interactive option.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n"},{"id":"247621","messageId":"xmqqzjf94f5n.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"xmqq4mxh5w34.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-12T20:38:28Z","receivedAt":"2014-08-12T20:38:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> So I think the reasoning (i.e. \"is a descendant\" is not quite right)\n> is correct, but the updated text is not quite right. Changing it\n> further to \"only the committer timestamps and identities would\n> change\" is probably not an improvement, either. \"Force the rebase\n> that would otherwise be a no-op\" may be a better phrasing that does\n> not risk going stale even if we update what are preserved and what\n> are modified in the future.\n>\n> Also I notice the sentence \"Normally non-interactive...in such a\n> situation\" is not helping the reader in this description very much.\n> I wonder if we should keep it if we are rewriting this paragraph.\n\nHow about doing it this way, perhaps?\n\n-- >8 --\nFrom: Sergey Organov \nDate: Tue, 12 Aug 2014 00:22:48 +0400\nSubject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op\n\n\"Current branch is a descendant of the commit you are rebasing onto\"\ndoes not necessarily mean \"rebase\" requires \"--force\". For a plain\nvanilla \"history flattening\" rebase, the rebase can be done without\nforcing if there is a merge between the tip of the branch being\nrebased and the commit you are rebasing onto, even if the tip is\ndescendant of the other.\n\n[jc: reworded both the text and the log description]\n\nSigned-off-by: Sergey Organov \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-rebase.txt | 7 ++-----\n 1 file changed, 2 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 2a93c64..f14100a 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -316,11 +316,8 @@ which makes little sense.\n \n -f::\n --force-rebase::\n-\tForce the rebase even if the current branch is a descendant\n-\tof the commit you are rebasing onto. Normally non-interactive rebase will\n-\texit with the message \"Current branch is up to date\" in such a\n-\tsituation.\n-\tIncompatible with the --interactive option.\n+\tForce a rebase even if the current branch is up-to-date and\n+\tthe command without `--force` would return without doing anything.\n +\n You may find this (or --no-ff with an interactive rebase) helpful after\n reverting a topic branch merge, as this option recreates the topic branch with\n-- \n2.1.0-rc2-238-g2566d2d\n"},{"id":"247648","messageId":"87mwb8ahtb.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqzjf94f5n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-13T08:56:48Z","receivedAt":"2014-08-13T08:56:48Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> So I think the reasoning (i.e. \"is a descendant\" is not quite right)\n>> is correct, but the updated text is not quite right. Changing it\n>> further to \"only the committer timestamps and identities would\n>> change\" is probably not an improvement, either. \"Force the rebase\n>> that would otherwise be a no-op\" may be a better phrasing that does\n>> not risk going stale even if we update what are preserved and what\n>> are modified in the future.\n>>\n>> Also I notice the sentence \"Normally non-interactive...in such a\n>> situation\" is not helping the reader in this description very much.\n>> I wonder if we should keep it if we are rewriting this paragraph.\n>\n> How about doing it this way, perhaps?\n\n[...]\n\n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> -\tIncompatible with the --interactive option.\n> +\tForce a rebase even if the current branch is up-to-date and\n> +\tthe command without `--force` would return without doing anything.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n> reverting a topic branch merge, as this option recreates the topic branch with\n\nIt's OK with me, as in fact I think that there is no good explanation\nfor current git behavior, and thus it's git behavior that should have\nbeen changed, not the documentation. I.e., git must not rebase anything\nwhen \"Current branch is a descendant of the commit you are rebasing\nonto\", unless -f is given. Simple, reasonable, straightforward.\n\nThe version you propose at least does not lie, so it's definiteley an\nimprovement. However,\n\n\"Force the rebase when the command exits with \"Current branch is up to\ndate\" message.\"\n\nreads even more simple and clear for me.\n\n-- \nSergey.\n"},{"id":"247672","messageId":"xmqqha1g49q5.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"87mwb8ahtb.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-13T16:48:02Z","receivedAt":"2014-08-13T16:48:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> ... I.e., git must not rebase anything\n> when \"Current branch is a descendant of the commit you are rebasing\n> onto\", unless -f is given. Simple, reasonable, straightforward.\n\nIt may be simple and straightforward, but breaks the use case the\nplain vanilla rebase is used for, doesn't it? You seem to ignore,\nor perhaps you don't realize the existence of, the need of those who\nwant to flatten the history on top of the tip from the other side;\nyour statements in the \"pull --rebase[=preserve]\" thread may be\ncoming from the same place, I suspect.\n\nFor the \"flatten the history on top of that commit\" use case, two\nconditions must be satisfied before the command can say \"the history\nis already in the desired shape and nothing needs to be done\" to\nallow it to make a short-cut. It is not sufficient for the current\ntip to be merely descendant of the tip from the other side (which is\nthe documentation bug we are fixing here). The history between the\ntwo commits need also to be linear, or it would not be flattening.\n\nPunting when when only one of the two conditions is met and\nrequiring \"--force\" to perform what the user wanted to ask the\ncommand to do does not fall into the \"reasonable\" category.\n\nIf your workflow does not involve the flattening plain vanilla\n\"rebase\", not using it is perfectly fine. But please do not break\nit for other people only because you do not use it yourself.\n"},{"id":"247738","messageId":"87d2c22cnx.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqzjf94f5n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-15T11:52:02Z","receivedAt":"2014-08-15T11:52:02Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> So I think the reasoning (i.e. \"is a descendant\" is not quite right)\n>> is correct, but the updated text is not quite right. Changing it\n>> further to \"only the committer timestamps and identities would\n>> change\" is probably not an improvement, either. \"Force the rebase\n>> that would otherwise be a no-op\" may be a better phrasing that does\n>> not risk going stale even if we update what are preserved and what\n>> are modified in the future.\n>>\n>> Also I notice the sentence \"Normally non-interactive...in such a\n>> situation\" is not helping the reader in this description very much.\n>> I wonder if we should keep it if we are rewriting this paragraph.\n>\n> How about doing it this way, perhaps?\n>\n> -- >8 --\n> From: Sergey Organov \n> Date: Tue, 12 Aug 2014 00:22:48 +0400\n> Subject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op\n>\n> \"Current branch is a descendant of the commit you are rebasing onto\"\n> does not necessarily mean \"rebase\" requires \"--force\". For a plain\n> vanilla \"history flattening\" rebase, the rebase can be done without\n> forcing if there is a merge between the tip of the branch being\n> rebased and the commit you are rebasing onto, even if the tip is\n> descendant of the other.\n>\n> [jc: reworded both the text and the log description]\n>\n> Signed-off-by: Sergey Organov \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-rebase.txt | 7 ++-----\n> 1 file changed, 2 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index 2a93c64..f14100a 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -316,11 +316,8 @@ which makes little sense.\n> \n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> -\tIncompatible with the --interactive option.\n> +\tForce a rebase even if the current branch is up-to-date and\n> +\tthe command without `--force` would return without doing anything.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n> reverting a topic branch merge, as this option recreates the topic branch with\n\n\nJunio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> So I think the reasoning (i.e. \"is a descendant\" is not quite right)\n>> is correct, but the updated text is not quite right. Changing it\n>> further to \"only the committer timestamps and identities would\n>> change\" is probably not an improvement, either. \"Force the rebase\n>> that would otherwise be a no-op\" may be a better phrasing that does\n>> not risk going stale even if we update what are preserved and what\n>> are modified in the future.\n>>\n>> Also I notice the sentence \"Normally non-interactive...in such a\n>> situation\" is not helping the reader in this description very much.\n>> I wonder if we should keep it if we are rewriting this paragraph.\n>\n> How about doing it this way, perhaps?\n>\n> -- >8 --\n> From: Sergey Organov \n> Date: Tue, 12 Aug 2014 00:22:48 +0400\n> Subject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op\n>\n> \"Current branch is a descendant of the commit you are rebasing onto\"\n> does not necessarily mean \"rebase\" requires \"--force\". For a plain\n> vanilla \"history flattening\" rebase, the rebase can be done without\n> forcing if there is a merge between the tip of the branch being\n> rebased and the commit you are rebasing onto, even if the tip is\n> descendant of the other.\n>\n> [jc: reworded both the text and the log description]\n>\n> Signed-off-by: Sergey Organov \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-rebase.txt | 7 ++-----\n> 1 file changed, 2 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index 2a93c64..f14100a 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -316,11 +316,8 @@ which makes little sense.\n> \n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> -\tIncompatible with the --interactive option.\n> +\tForce a rebase even if the current branch is up-to-date and\n> +\tthe command without `--force` would return without doing anything.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n> reverting a topic branch merge, as this option recreates the topic branch with\n\nI dig more into it, and that's what I came up with, using some of your\nsuggestions as well.\n\nPlease notice new text on essential interaction with --preserve-merges.\n\nI also thought about \"Force the rebase that would otherwise be a no-op\",\nand while it is future-changes-agnostic indeed, it doesn't actually\nexplain anything, so I put some explanation back.\n\n-- >8 --\n\nFrom: Sergey Organov \nDate: Tue, 12 Aug 2014 00:10:19 +0400\nSubject: [PATCH] Documentation/git-rebase.txt: fix -f description to match\n\n\"Current branch is a descendant of the commit you are rebasing onto\"\ndoes not necessarily mean \"rebase\" requires \"--force\". Presence of\nmerge commit(s) makes \"rebase\" perform its default flattening actions\nanyway.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/git-rebase.txt | 9 ++++-----\n 1 file changed, 4 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 2a93c64..9153369 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -316,11 +316,10 @@ which makes little sense.\n \n -f::\n --force-rebase::\n-\tForce the rebase even if the current branch is a descendant\n-\tof the commit you are rebasing onto. Normally non-interactive rebase will\n-\texit with the message \"Current branch is up to date\" in such a\n-\tsituation.\n-\tIncompatible with the --interactive option.\n+\tIf --preserve-merges is given, has no effect. Otherwise forces\n+\trebase even if the current branch is a descendant of the commit\n+\tyou are rebasing onto and there are no merge commits among\n+\tthose to be rebased.\n +\n You may find this (or --no-ff with an interactive rebase) helpful after\n reverting a topic branch merge, as this option recreates the topic branch with\n-- \n1.9.3\n"},{"id":"247749","messageId":"xmqq38cx1w0e.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"87d2c22cnx.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-15T17:51:45Z","receivedAt":"2014-08-15T17:51:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> ...\n>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n>> index 2a93c64..f14100a 100644\n>> --- a/Documentation/git-rebase.txt\n>> +++ b/Documentation/git-rebase.txt\n>> @@ -316,11 +316,8 @@ which makes little sense.\n>> \n>> -f::\n>> --force-rebase::\n>> -\tForce the rebase even if the current branch is a descendant\n>> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n>> -\texit with the message \"Current branch is up to date\" in such a\n>> -\tsituation.\n>> -\tIncompatible with the --interactive option.\n>> +\tForce a rebase even if the current branch is up-to-date and\n>> +\tthe command without `--force` would return without doing anything.\n>> +\n>> You may find this (or --no-ff with an interactive rebase) helpful after\n>> reverting a topic branch merge, as this option recreates the topic branch with\n>\n> I dig more into it, and that's what I came up with, using some of your\n> suggestions as well.\n>\n> Please notice new text on essential interaction with --preserve-merges.\n>\n> I also thought about \"Force the rebase that would otherwise be a no-op\",\n> and while it is future-changes-agnostic indeed, it doesn't actually\n> explain anything, so I put some explanation back.\n\nA sentence \"--force has no effect under --preserve-merges mode\" does\nnot tell the readers very much, either and leaves them wondering if\nit means \"--preserve-merges mode always rebases every time it is\nasked, never noticing 'ah, the history is already in a good shape\nand there is no need to do anything further'\" or \"--preserve-merges\nmode ignores --force and refuses to recreate the history if the\nhistory is in the shape the mode deems is already desirable.\"\n\nI think the root cause of the issue we share in this thread, when\ntrying to come up with an improvement of this part, is that we are\ntrying to put more explanation to the description of --force, but if\nwe step back a bit, it may be that the explanation does not belong\nthere. As far as the readers are concerned, --force is about\nforcing a rebase that would not otherwise be a no-op, but the real\nissue is that the condition under which a requested rebase becomes a\nno-op, iow, \"the history is already in the desired shape, nothing to\ndo\", is different from mode to mode, because \"the desired shape\" is\nwhat distinguishes the modes. Preserve-merge rebase may think that\na history that is descendant of the \"onto\" commit is already in the\ndesired shape while plain-vanilla rebase does not if it has a merge\nin between, for example.\n\nThe sentence that follows \"Otherwise\" in this version encourages the\nreaders to be in a wrong mind-set that rebase is only about \"making\nthe branch a descendant of the 'onto' commit\", which isn't the case.\n\nThe desired outcome depends on the mode (and that is why there are\nmodes), and not saying that explicitly will only help spread the\nconfusion, I am afraid. Isn't it a better solution to explain what\nthat no-op condition is for the mode at the place in the document\nwhere we describe each mode?\n\nE.g. under \"--preserve-merges\" heading, we may say \"make sure the\nhistory is a descendant of the 'onto' commit; if it already is,\nnothing is done because there is no need to do anything\" or\nsomething along that line. The description for the plain-vanilla\nrebase may say \"flatten the history on top of the 'onto' commit by\nreplaying the changes in each non-merge commit; if the history is\nalready a descendant of the 'onto' commit without any merge in\nbetween, nothing is done because there is no need to\".\n\nThat would make description of the modes more understandable, too.\nThe users can read what kind of resulting history they can get out\nof by using each mode in one place.\n\nHmm?\n\n> -- >8 --\n>\n> From: Sergey Organov \n> Date: Tue, 12 Aug 2014 00:10:19 +0400\n> Subject: [PATCH] Documentation/git-rebase.txt: fix -f description to match\n>\n> \"Current branch is a descendant of the commit you are rebasing onto\"\n> does not necessarily mean \"rebase\" requires \"--force\". Presence of\n> merge commit(s) makes \"rebase\" perform its default flattening actions\n> anyway.\n>\n> Signed-off-by: Sergey Organov \n> ---\n> Documentation/git-rebase.txt | 9 ++++-----\n> 1 file changed, 4 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index 2a93c64..9153369 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -316,11 +316,10 @@ which makes little sense.\n> \n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> -\tIncompatible with the --interactive option.\n> +\tIf --preserve-merges is given, has no effect. Otherwise forces\n> +\trebase even if the current branch is a descendant of the commit\n> +\tyou are rebasing onto and there are no merge commits among\n> +\tthose to be rebased.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n> reverting a topic branch merge, as this option recreates the topic branch with\n"},{"id":"247755","messageId":"87ioltik7g.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqq38cx1w0e.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-15T20:14:43Z","receivedAt":"2014-08-15T20:14:43Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> ...\n>>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n>>> index 2a93c64..f14100a 100644\n>>> --- a/Documentation/git-rebase.txt\n>>> +++ b/Documentation/git-rebase.txt\n>>> @@ -316,11 +316,8 @@ which makes little sense.\n>>> \n>>> -f::\n>>> --force-rebase::\n>>> -\tForce the rebase even if the current branch is a descendant\n>>> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n>>> -\texit with the message \"Current branch is up to date\" in such a\n>>> -\tsituation.\n>>> -\tIncompatible with the --interactive option.\n>>> +\tForce a rebase even if the current branch is up-to-date and\n>>> +\tthe command without `--force` would return without doing anything.\n>>> +\n>>> You may find this (or --no-ff with an interactive rebase) helpful after\n>>> reverting a topic branch merge, as this option recreates the topic branch with\n>>\n>> I dig more into it, and that's what I came up with, using some of your\n>> suggestions as well.\n>>\n>> Please notice new text on essential interaction with --preserve-merges.\n>>\n>> I also thought about \"Force the rebase that would otherwise be a no-op\",\n>> and while it is future-changes-agnostic indeed, it doesn't actually\n>> explain anything, so I put some explanation back.\n>\n> A sentence \"--force has no effect under --preserve-merges mode\" does\n> not tell the readers very much, either and leaves them wondering if\n> it means \"--preserve-merges mode always rebases every time it is\n> asked, never noticing 'ah, the history is already in a good shape\n> and there is no need to do anything further'\" or \"--preserve-merges\n> mode ignores --force and refuses to recreate the history if the\n> history is in the shape the mode deems is already desirable.\"\n\nIn fact there is no way to force rebase when --preserve-merges is given.\nNeither --force nor --no-ff has any effect.\n\nMaybe some clarification could be given in --preserve-merges\ndescription, provided it's not clear that \"has no effect\" for --force\nmeans that one can't force the rebase in this case.\n\n> I think the root cause of the issue we share in this thread, when\n> trying to come up with an improvement of this part, is that we are\n> trying to put more explanation to the description of --force, but if\n> we step back a bit, it may be that the explanation does not belong\n> there. As far as the readers are concerned, --force is about\n> forcing a rebase that would not otherwise be a no-op, but the real\n> issue is that the condition under which a requested rebase becomes a\n> no-op, iow, \"the history is already in the desired shape, nothing to\n> do\", is different from mode to mode, because \"the desired shape\" is\n> what distinguishes the modes. Preserve-merge rebase may think that\n> a history that is descendant of the \"onto\" commit is already in the\n> desired shape while plain-vanilla rebase does not if it has a merge\n> in between, for example.\n\nI think the root cause is even deeper, in the current design of the\nrebase interface, but those my opinion you already know and I'll leave\ndiscussion for another post that I currently try to formulate.\n\n> The sentence that follows \"Otherwise\" in this version encourages the\n> readers to be in a wrong mind-set that rebase is only about \"making\n> the branch a descendant of the 'onto' commit\", which isn't the case.\n\nI'm not happy with the wording myself either.\n\n> The desired outcome depends on the mode (and that is why there are\n> modes), and not saying that explicitly will only help spread the\n> confusion, I am afraid. Isn't it a better solution to explain what\n> that no-op condition is for the mode at the place in the document\n> where we describe each mode?\n>\n> E.g. under \"--preserve-merges\" heading, we may say \"make sure the\n> history is a descendant of the 'onto' commit; if it already is,\n> nothing is done because there is no need to do anything\" or\n> something along that line. The description for the plain-vanilla\n> rebase may say \"flatten the history on top of the 'onto' commit by\n> replaying the changes in each non-merge commit; if the history is\n> already a descendant of the 'onto' commit without any merge in\n> between, nothing is done because there is no need to\".\n>\n> That would make description of the modes more understandable, too.\n> The users can read what kind of resulting history they can get out\n> of by using each mode in one place.\n\nI think you've lost me here, though I think that all the suggested\nvariants are still better than what is there right now.\n\n-- \nSergey.\n"},{"id":"247759","messageId":"xmqqioltza8z.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"87ioltik7g.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-15T21:57:48Z","receivedAt":"2014-08-15T21:57:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> A sentence \"--force has no effect under --preserve-merges mode\" does\n>> not tell the readers very much, either and leaves them wondering if\n>> it means \"--preserve-merges mode always rebases every time it is\n>> asked, never noticing 'ah, the history is already in a good shape\n>> and there is no need to do anything further'\" or \"--preserve-merges\n>> mode ignores --force and refuses to recreate the history if the\n>> history is in the shape the mode deems is already desirable.\"\n>\n> In fact there is no way to force rebase when --preserve-merges is given.\n> Neither --force nor --no-ff has any effect.\n>\n> Maybe some clarification could be given in --preserve-merges\n> description, provided it's not clear that \"has no effect\" for --force\n> means that one can't force the rebase in this case.\n\nI am not sure if that is an intended behaviour or simply a bug (I\nrarely use preserve-merges myself, so I offhand do not know for\ncertain).\n"},{"id":"247832","messageId":"87ha1advqe.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqioltza8z.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-18T08:53:45Z","receivedAt":"2014-08-18T08:53:45Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> A sentence \"--force has no effect under --preserve-merges mode\" does\n>>> not tell the readers very much, either and leaves them wondering if\n>>> it means \"--preserve-merges mode always rebases every time it is\n>>> asked, never noticing 'ah, the history is already in a good shape\n>>> and there is no need to do anything further'\" or \"--preserve-merges\n>>> mode ignores --force and refuses to recreate the history if the\n>>> history is in the shape the mode deems is already desirable.\"\n>>\n>> In fact there is no way to force rebase when --preserve-merges is given.\n>> Neither --force nor --no-ff has any effect.\n>>\n>> Maybe some clarification could be given in --preserve-merges\n>> description, provided it's not clear that \"has no effect\" for --force\n>> means that one can't force the rebase in this case.\n>\n> I am not sure if that is an intended behaviour or simply a bug\n\nI think nobody actually ever needed to make it work, even though\nfundamentally it could have the same usage as in the case of flattening\nrebase. Once again, it seems that most uses of rebase handle already\nflat history and thus are served by vanilla invocation.\n\n> (I rarely use preserve-merges myself, so I offhand do not know for\n> certain).\n\nI wonder, don't you yourself use preserve-merges because you don't care\nand just use the default, or because you actually use vanilla\nhistory-flattening feature?\n\n-- \nSergey.\n"},{"id":"247837","messageId":"87a972rkqh.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqha1g49q5.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-18T13:27:34Z","receivedAt":"2014-08-18T13:27:34Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> ... I.e., git must not rebase anything\n>> when \"Current branch is a descendant of the commit you are rebasing\n>> onto\", unless -f is given. Simple, reasonable, straightforward.\n>\n> It may be simple and straightforward, but breaks the use case the\n> plain vanilla rebase is used for, doesn't it?\n\nI hope it does not. I don't think plain vanilla rebase's \"flattening\"\nfeature is usually used, as those who care about flat history mostly\ndon't merge. Either not at all, or do merges temporarily and undo them\nlater. At least that's the impression I've got from recent conversations\nabout the issue.\n\nMoreover, I'm afraid rare person would correctly predict the result of\nhistory flattening he will get from git rebase of even remotely complex\ngraph.\n\nThat said, I'm still to hear from somebody who would actually suffer. I\nmean I see some use-case(s), but they: 1) are unlikely to be used in\npractice. 2) are better handled by other means. 3) abuse bug/feature\nthat contradicts documentation. 4) won't be broken that hard anyway.\n\n> You seem to ignore, or perhaps you don't realize the existence of, the\n> need of those who want to flatten the history on top of the tip from\n> the other side;\n\nNo, I do realize and I don't ignore the possibility. Please recall that\nI didn't suggest to get rid of any functionality that is already there.\n\nI didn't want to get into lengthy discussion about it, but here we are.\n\nIn fact there are 2 issues here (please notice that I don't cut any\nexisting functionality):\n\n1. Better design of interface to \"git rebase\" features.\n\n2. How far we are currently from those \"better\", is it worth the trouble\n to move in the direction of \"better\" at all, and how far and how fast\n we are going to move, considering backward compatibility issues.\n\nIf we don't agree on (1), i.e., where is point B, there is no reason to\ndiscuss (2), i.e., the way from point A to point B. I'm trying to\ndiscuss (1), and you are mostly objecting by pointing me to the fact\nthat changes could break some workflow, i.e., by discussing (2).\n\nWhat about those better design? Here is my bet:\n\n1. \"git rebase\" with no options takes a set of commits and rebases them\n on top of another commit, preserving precious history as much as\n possible.\n\n Reason: most common operation: \"rebase my work on top of different\n commit\". Nothing more, nothing less. That's what --preserve mode does\n right now. I.e., the result should be as close as possible to the\n case where I had started to do all the work on top of the new base\n commit from the beginning.\n\n2. \"git rebase\" onto the same base should be no-op, unless --force\n option is given.\n\n Reason: if command changes base, it's natural to do nothing when base\n is not changed. Alternatively, rebase would have to be performed\n always, and commit dates etc. would be changed as a result. This\n would be just annoying most of times.\n\n3. \"git rebase\" may have an option to flatten the history instead of\n preserving its shape (--flatten or some such). This mode may imply\n some relaxing of (2) by always performing the rebase when there are\n merge commits among those to be rebased.\n\n Reason: somebody somewhere could probably find a real use for such a\n feature. BTW, there could be different modes of flattening, so this\n option may take corresponding values (e.g., squash every merged set\n of commits to a single commit). Please also notice that function of\n (3) could be achieved by other means, so it's not a requirement,\n rather a convenience (that's why I said \"may have an option\").\n\nWe can discuss this if somebody interested. If not, let's just fix\ndocumentation to match current historical design, please.\n\n> your statements in the \"pull --rebase[=preserve]\" thread may be\n> coming from the same place, I suspect.\n\nYes, it's the same place. It's all started from a big trouble I ran into\nby simply following current git documentation for \"git pull\" and \"git\nrebase\" and from assumption that defaults are usually safe (and sane,\nyes, in my understanding of \"sane\" ;-) ).\n\nAnd yes, they share the same reasoning. That is, by default a command\nmust perform its primary job, and only it. Everything else should be an\noption. For \"git pull\" it'd mean to fetch the changes from upstream, and\nthen either merge or rebase to integrate with them. For \"git pull\", my\nplan would be to introduce new \"pull.rebase=flatten\" value and deprecate\n\"pull.rebase=true\". Bare \"pull --rebase\" should be deprecated as well\nin favor of explicit \"pull --rebase=flatten\", then later \"pull\n--rebase\" could be given saner and safer meaning of \"pull\n--rebase=preserve\", or rather removed.\n\n> For the \"flatten the history on top of that commit\" use case, two\n> conditions must be satisfied before the command can say \"the history\n> is already in the desired shape and nothing needs to be done\" to\n> allow it to make a short-cut. It is not sufficient for the current\n> tip to be merely descendant of the tip from the other side (which is\n> the documentation bug we are fixing here). The history between the\n> two commits need also to be linear, or it would not be flattening.\n>\n> Punting when when only one of the two conditions is met and\n> requiring \"--force\" to perform what the user wanted to ask the\n> command to do does not fall into the \"reasonable\" category.\n\nCurrent behavior you described above would be \"reasonable\" for \"git\nflatten\" command. If it were reasonable for \"git rebase\", why is it\nthat difficult to correctly document it? Good design is usually easily\ndocumentable.\n\n> If your workflow does not involve the flattening plain vanilla\n> \"rebase\", not using it is perfectly fine. But please do not break\n> it for other people only because you do not use it yourself.\n\nI only aim at making \"git rebase\" better. Backward compatibility\nshouldn't be forgotten, but you seem to disagree that my suggestion(s)\ndo make it better in the first place, so no need to discuss any breakage\nat this point.\n\nAnyway, those imaginary people, if any, who would suffer from the change\nthat would require --force to rebase *on the same commit* currently\nsilently rely on the feature that contradicted documentation, and that\nsometimes needs to be punished ;-)\n\n-- \nSergey.\n"},{"id":"247844","messageId":"xmqqtx59yd0h.fsf@gitster.dls.corp.google.com","threadId":"37330","inReplyTo":"87ha1advqe.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-18T16:32:30Z","receivedAt":"2014-08-18T16:32:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> (I rarely use preserve-merges myself, so I offhand do not know for\n>> certain).\n>\n> I wonder, don't you yourself use preserve-merges because you don't care\n> and just use the default, or because you actually use vanilla\n> history-flattening feature?\n\nThe latter.\n"},{"id":"247899","messageId":"87y4ukajiz.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqioltza8z.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-19T09:57:56Z","receivedAt":"2014-08-19T09:57:56Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> A sentence \"--force has no effect under --preserve-merges mode\" does\n>>> not tell the readers very much, either and leaves them wondering if\n>>> it means \"--preserve-merges mode always rebases every time it is\n>>> asked, never noticing 'ah, the history is already in a good shape\n>>> and there is no need to do anything further'\" or \"--preserve-merges\n>>> mode ignores --force and refuses to recreate the history if the\n>>> history is in the shape the mode deems is already desirable.\"\n>>\n>> In fact there is no way to force rebase when --preserve-merges is given.\n>> Neither --force nor --no-ff has any effect.\n>>\n>> Maybe some clarification could be given in --preserve-merges\n>> description, provided it's not clear that \"has no effect\" for --force\n>> means that one can't force the rebase in this case.\n>\n> I am not sure if that is an intended behaviour or simply a bug (I\n> rarely use preserve-merges myself, so I offhand do not know for\n> certain).\n\nIt seems that there is some problem there anyway. Probably a slight\nmisfeature rather than a bug, as --preserve-merges always pretends it\ndoes something, even when it does not:\n\n$ git log --oneline --graph --decorate\n* 6f25bd5 (HEAD, topic) M\n|\\ \n| * c5a4a43 C\n* | 3c6ab7a (master) N\n* | 99ff328 B\n|/ \n* 130ae2d A\n$ git rebase --preserve-merges master\nSuccessfully rebased and updated refs/heads/topic.\n$ git log --oneline --graph --decorate\n* 6f25bd5 (HEAD, topic) M\n|\\ \n| * c5a4a43 C\n* | 3c6ab7a (master) N\n* | 99ff328 B\n|/ \n* 130ae2d A\n$\n\n\"git reflog topic\" doesn't show any changes either.\n\n-- \nSergey.\n"},{"id":"247900","messageId":"87oavg6bhp.fsf@osv.gnss.ru","threadId":"37330","inReplyTo":"xmqqzjf94f5n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-08-19T10:05:06Z","receivedAt":"2014-08-19T10:05:06Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n> Junio C Hamano writes:\n[...]\n> How about doing it this way, perhaps?\n\nCould you please apply this your suggestion, as we seem not to agree\non anything better?\n\n> -- >8 --\n> From: Sergey Organov \n> Date: Tue, 12 Aug 2014 00:22:48 +0400\n> Subject: [PATCH] Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op\n>\n> \"Current branch is a descendant of the commit you are rebasing onto\"\n> does not necessarily mean \"rebase\" requires \"--force\". For a plain\n> vanilla \"history flattening\" rebase, the rebase can be done without\n> forcing if there is a merge between the tip of the branch being\n> rebased and the commit you are rebasing onto, even if the tip is\n> descendant of the other.\n>\n> [jc: reworded both the text and the log description]\n>\n> Signed-off-by: Sergey Organov \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-rebase.txt | 7 ++-----\n> 1 file changed, 2 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index 2a93c64..f14100a 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -316,11 +316,8 @@ which makes little sense.\n> \n> -f::\n> --force-rebase::\n> -\tForce the rebase even if the current branch is a descendant\n> -\tof the commit you are rebasing onto. Normally non-interactive rebase will\n> -\texit with the message \"Current branch is up to date\" in such a\n> -\tsituation.\n> -\tIncompatible with the --interactive option.\n> +\tForce a rebase even if the current branch is up-to-date and\n> +\tthe command without `--force` would return without doing anything.\n> +\n> You may find this (or --no-ff with an interactive rebase) helpful after\n> reverting a topic branch merge, as this option recreates the topic branch with\n\n-- \nSergey.\n"}]}