{"thread":{"id":"16813","subject":"[PATCH] Have manpage reference new documentation on reverting merges.","startedAt":"2008-12-21T00:32:48Z","lastAt":"2008-12-22T00:26:03Z","messageCount":7,"participants":["Boyd Stephen Smith Jr.","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"98466","messageId":"200812201832.48992.bss@iguanasuicide.net","threadId":"16813","inReplyTo":null,"subject":"[PATCH] Have manpage reference new documentation on reverting merges.","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2008-12-21T00:32:48Z","receivedAt":"2008-12-21T00:32:48Z","isPatch":true,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":"Signed-off-by: Boyd Stephen Smith Jr \n---\nAn example addition to the manpage for revert that references Nanako\nShiraishi's new documentation.\n\n Documentation/git-revert.txt | 4 ++++\n 1 files changed, 4 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex caa0729..ea36bdf 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -45,6 +45,10 @@ OPTIONS\n \tthe mainline and allows revert to reverse the change\n \trelative to the specified parent.\n \n+\tReverting a merge commit does not completely \"undo\" the effect of the\n+\tmerge and it may make future merges more difficult. For more details,\n+\tplease read Documentation/howto/revert-a-faulty-merge.txt.\n+\n --no-edit::\n \tWith this option, 'git-revert' will not start the commit\n \tmessage editor.\n-- \n1.5.6\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"},{"id":"98472","messageId":"7vtz8ytft0.fsf@gitster.siamese.dyndns.org","threadId":"16813","inReplyTo":"200812201832.48992.bss@iguanasuicide.net","subject":"Re: [PATCH] Have manpage reference new documentation on reverting merges.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-12-21T02:36:43Z","receivedAt":"2008-12-21T02:36:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Boyd Stephen Smith Jr.\" writes:\n\n> Signed-off-by: Boyd Stephen Smith Jr \n> ---\n> An example addition to the manpage for revert that references Nanako\n> Shiraishi's new documentation.\n>\n> Documentation/git-revert.txt | 4 ++++\n> 1 files changed, 4 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\n> index caa0729..ea36bdf 100644\n> --- a/Documentation/git-revert.txt\n> +++ b/Documentation/git-revert.txt\n> @@ -45,6 +45,10 @@ OPTIONS\n> \tthe mainline and allows revert to reverse the change\n> \trelative to the specified parent.\n> \n> +\tReverting a merge commit does not completely \"undo\" the effect of the\n> +\tmerge and it may make future merges more difficult. For more details,\n> +\tplease read Documentation/howto/revert-a-faulty-merge.txt.\n> +\n\nI think these new lines need to be dedented, and the previous blank line\nshould be turned into a line with a single '+'.\n\nI'd also suggest removing \"does not ... merge and it\" from the above\nsentence to avoid confusing readers, because people who read only the\nabove and do not read the howto document may get a wrong impression that\nthe resulting tree may have some changes that came from the merge even\nafter the revert, which is not the case. Revert will erase the effect the\nmerge had to your tree and that part is complete.\n\nLinus's \"does not completely undo\" only refers to the history part of the\nmerge, and that only affects future re-merges from the same branch, which\nthe reader who is interested in doing a revert of a merge right now (that\nis why s/he is reading this paragraph) may not yet care about.\n\nAn alternative is to give a complete but brief explanation. Perhaps like\nthis:\n\n By reverting a merge, you are declaring that you will never want the\n changes that were brought in by that merge you are reverting in your\n tree. If you do merge from the same branch again in the future after\n it is updated, git remembers your declaration, and only the changes on\n the branch that were made after the reverted merge will be brought in.\n This may or may not be what you want. See 'revert-a-faulty-merge'\n HOWTO for more details.\n"},{"id":"98476","messageId":"200812202335.19006.bss@iguanasuicide.net","threadId":"16813","inReplyTo":"7vtz8ytft0.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Have manpage reference new documentation on reverting merges.","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2008-12-21T05:35:14Z","receivedAt":"2008-12-21T05:35:14Z","isPatch":true,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":"On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:\n> \"Boyd Stephen Smith Jr.\" writes:\n> > ---\n> > An example addition to the manpage for revert that references Nanako\n> > Shiraishi's new documentation.\n> >\n> > Documentation/git-revert.txt | 4 ++++\n> > 1 files changed, 4 insertions(+), 0 deletions(-)\n> >\n> > diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\n> > index caa0729..ea36bdf 100644\n> > --- a/Documentation/git-revert.txt\n> > +++ b/Documentation/git-revert.txt\n> > @@ -45,6 +45,10 @@ OPTIONS\n> > \tthe mainline and allows revert to reverse the change\n> > \trelative to the specified parent.\n> >\n> > +\tReverting a merge commit does not completely \"undo\" the effect of the\n> > +\tmerge and it may make future merges more difficult. For more details,\n> > +\tplease read Documentation/howto/revert-a-faulty-merge.txt.\n> > +\n>\n> I think these new lines need to be dedented, and the previous blank line\n> should be turned into a line with a single '+'.\n\nCan do.\n\n> I'd also suggest removing \"does not ... merge and it\" from the above\n> sentence to avoid confusing readers, because people who read only the\n> above and do not read the howto document may get a wrong impression that\n> the resulting tree may have some changes that came from the merge even\n> after the revert, which is not the case. Revert will erase the effect the\n> merge had to your tree and that part is complete.\n\nBut that is not the whole effect of the merge. The effect of the merge is \nboth the modifications it makes to the tree and the modifications it makes to \nthe history.\n\nGoing from the dictionary meaning for \"revert\", one might expect the those \neffects to go away as well. I think a warning that the revert subcommand \ndoes not fully revert the merge is appropriate.\n\n> Linus's \"does not completely undo\" only refers to the history part of the\n> merge, and that only affects future re-merges from the same branch, which\n> the reader who is interested in doing a revert of a merge right now (that\n> is why s/he is reading this paragraph) may not yet care about.\n\nThey may not care about it now, but it doesn't make much sense to warn about \nit during the later merge (plus it might be computationally expensive to \ndetect).\n\n> An alternative is to give a complete but brief explanation. Perhaps like\n> this:\n>\n> By reverting a merge, you are declaring that you will never want the\n> changes that were brought in by that merge you are reverting in your\n> tree. If you do merge from the same branch again in the future after\n> it is updated, git remembers your declaration, and only the changes on\n> the branch that were made after the reverted merge will be brought in.\n> This may or may not be what you want. See 'revert-a-faulty-merge'\n> HOWTO for more details.\n\nI think the wording might need to be changed a little bit, but I do like the \nlonger, more complete and clear explanation and I'll work on a patch that has \none.\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"},{"id":"98480","messageId":"7vzliqrm88.fsf@gitster.siamese.dyndns.org","threadId":"16813","inReplyTo":"200812202335.19006.bss@iguanasuicide.net","subject":"Re: [PATCH] Have manpage reference new documentation on reverting merges.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-12-21T08:00:55Z","receivedAt":"2008-12-21T08:00:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Boyd Stephen Smith Jr.\" writes:\n\n> But that is not the whole effect of the merge. The effect of the merge is \n> both the modifications it makes to the tree and the modifications it makes to \n> the history.\n>\n> Going from the dictionary meaning for \"revert\", one might expect the those \n> effects to go away as well. I think a warning that the revert subcommand \n> does not fully revert the merge is appropriate.\n\nYou may be technically correct, but think about the intended audience of\nthe warning.\n\nPeople who know there are the \"tree\" aspect and the \"history\" aspect in\nthe merge and the revert operation will not get confused by the issue we\ndescribe in the new HOW-TO, and they will understand the ramifications\nwithout the help from the warning in your new paragraph. The new warning\nis trying to help people who do not understand these two aspects..\n\nI have a strong suspicion that the \"tree\" aspect is much easier to grasp\nby new people, while the understanding of the \"history\" aspect comes much\nlater when one becomes more proficient in using git. Also, the immediate\ninterest of people who are reading \"git revert\" manual page is to revert\nthe effect of the merge in the \"tree\" aspect (iow, \"I want to get the damn\nthing work again\"); that is where the focus of their attention is when\nthey read this manual page.\n\nYour \"not completely\" does not tell them that the incompleteness you talk\nabout is \"tree aspect only, not history aspect\". That is what I meant by\n\"... may get a wrong impression\". Their attention is about the \"tree\"\naspect, and your \"not completely\" will be easily misinterpreted as \"the\ntree effect of the merge won't get reverted completely\", which is not what\nyou want to say. And that is why I think you are much better off not\nsaying \"not completely\" if you do not explain what you mean by it.\n\nAs I showed you how in the previous message, an alternative is to say (the\nequivalent of) \"not completely\", but explain what incompleteness you mean.\n\n>> Linus's \"does not completely undo\" only refers to the history part of the\n>> merge, and that only affects future re-merges from the same branch, which\n>> the reader who is interested in doing a revert of a merge right now (that\n>> is why s/he is reading this paragraph) may not yet care about.\n>\n> They may not care about it now, but it doesn't make much sense to warn about \n> it during the later merge (plus it might be computationally expensive to \n> detect).\n\nWho's talking about giving a warning by computation? Please stay on the\ndiscussion of your documentation patch.\n\n>> An alternative is to give a complete but brief explanation. Perhaps like\n>> this:\n>>\n>> By reverting a merge, you are declaring that you will never want the\n>> changes that were brought in by that merge you are reverting in your\n>> tree. If you do merge from the same branch again in the future after\n>> it is updated, git remembers your declaration, and only the changes on\n>> the branch that were made after the reverted merge will be brought in.\n>> This may or may not be what you want. See 'revert-a-faulty-merge'\n>> HOWTO for more details.\n>\n> I think the wording might need to be changed a little bit, but I do like the \n> longer, more complete and clear explanation and I'll work on a patch that has \n> one.\n"},{"id":"98500","messageId":"E1LEVxk-0001jS-Cc@rei.iguanasuicide.net","threadId":"16813","inReplyTo":"7vtz8ytft0.fsf@gitster.siamese.dyndns.org","subject":"[PATCHv2] Have manpage reference new documentation on reverting merges.","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2008-12-21T21:35:18Z","receivedAt":"2008-12-21T21:35:18Z","isPatch":false,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":"Signed-off-by: Boyd Stephen Smith Jr \n---\nOn Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:\n> \"Boyd Stephen Smith Jr.\" writes:\n> > +\tReverting a merge commit does not completely \"undo\" the effect of the\n> > +\tmerge and it may make future merges more difficult. For more details,\n> > +\tplease read Documentation/howto/revert-a-faulty-merge.txt.\n>\n> I think these new lines need to be dedented, and the previous blank line\n> should be turned into a line with a single '+'.\n\nFixed, I wasn't familiar with asciidoc.\n\n> I'd also suggest removing \"does not ... merge and it\" from the above\n> sentence to avoid confusing readers, because people who read only the\n> above and do not read the howto document may get a wrong impression that\n> the resulting tree may have some changes that came from the merge even\n> after the revert, which is not the case.\n>\n> An alternative is to give a complete but brief explanation. Perhaps like\n> this:\n\nI took the alternative approach.\n\n Documentation/git-revert.txt | 7 +++++++\n 1 files changed, 7 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex caa0729..daa77a9 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -44,6 +44,13 @@ OPTIONS\n \toption specifies the parent number (starting from 1) of\n \tthe mainline and allows revert to reverse the change\n \trelative to the specified parent.\n++\n+Reverting a merge commit declares to git that you will never want the tree\n+changes brought in by the merge but never alters the history changes caused by\n+the merge. The history allows git to remember you rejected the tree changes\n+and, as a result, later merges will only bring in changes introduced by commits\n+that are not ancestors of the revert commit. This may or may not be what you\n+want. See the 'revert-a-faulty-merge' HOWTO for more details.\n \n --no-edit::\n \tWith this option, 'git-revert' will not start the commit\n-- \n1.5.6\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"},{"id":"98504","messageId":"7vy6y9kxdh.fsf@gitster.siamese.dyndns.org","threadId":"16813","inReplyTo":"E1LEVxk-0001jS-Cc@rei.iguanasuicide.net","subject":"Re: [PATCHv2] Have manpage reference new documentation on reverting merges.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-12-21T21:54:18Z","receivedAt":"2008-12-21T21:54:18Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Boyd Stephen Smith Jr.\" writes:\n\n> I took the alternative approach.\n\nThanks. I was thinking about doing this instead; how the reference to the\nHOW-TO is done is different, and I am hoping that it would give better\nresult for HTML version at least.\n\n Documentation/git-revert.txt | 9 +++++++++\n 1 files changed, 9 insertions(+), 0 deletions(-)\n\ndiff --git c/Documentation/git-revert.txt w/Documentation/git-revert.txt\nindex caa0729..b87f2b3 100644\n--- c/Documentation/git-revert.txt\n+++ w/Documentation/git-revert.txt\n@@ -44,6 +44,15 @@ OPTIONS\n \toption specifies the parent number (starting from 1) of\n \tthe mainline and allows revert to reverse the change\n \trelative to the specified parent.\n++\n+By reverting a merge, you are telling git that you never want the changes\n+the merge made to your tree. If the branch the reverted merge merged is\n+updated later, and you merge from it again, git remembers this, and only\n+brings in the changes on the branch that are made after the previously\n+reverted merge. This may or may not be what you want.\n++\n+See link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for\n+more details.\n \n --no-edit::\n \tWith this option, 'git-revert' will not start the commit\n"},{"id":"98524","messageId":"200812211826.03208.bss@iguanasuicide.net","threadId":"16813","inReplyTo":"7vy6y9kxdh.fsf@gitster.siamese.dyndns.org","subject":"[PATCHv3] Have git revert documentation reference new HOWTO on reverting faulty merges.","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2008-12-22T00:26:03Z","receivedAt":"2008-12-22T00:26:03Z","isPatch":false,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":"Signed-off-by: Boyd Stephen Smith Jr \n---\nOn Sunday 2008 December 21 15:54:18 Junio C Hamano wrote:\n> Thanks. I was thinking about doing this instead; how the reference to the\n> HOW-TO is done is different, and I am hoping that it would give better\n> result for HTML version at least.\n\nHere's a pruned version of my prose, with your link style. I prefer my prose\nbecause I don't want to use the word \"branch\", which implies refs having some\nimportant in the later merges, which is not the case from what I understand.\n\n Documentation/git-revert.txt | 8 ++++++++\n 1 files changed, 8 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex caa0729..ee9cb82 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -44,6 +44,14 @@ OPTIONS\n \toption specifies the parent number (starting from 1) of\n \tthe mainline and allows revert to reverse the change\n \trelative to the specified parent.\n++\n+Reverting a merge commit declares that you will never want the tree changes\n+brought in by the merge. As a result, later merges will only bring in tree\n+changes introduced by commits that are not ancestors of the revert commit.\n+This may or may not be what you want.\n++\n+See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for\n+more details.\n \n --no-edit::\n \tWith this option, 'git-revert' will not start the commit\n-- \n1.6.0.2\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"}]}