"Boyd Stephen Smith Jr." <bss@xxxxxxxxxxxxxxxxx> writes: > But that is not the whole effect of the merge. The effect of the merge is > both the modifications it makes to the tree and the modifications it makes to > the history. > > Going from the dictionary meaning for "revert", one might expect the those > effects to go away as well. I think a warning that the revert subcommand > does not fully revert the merge is appropriate. You may be technically correct, but think about the intended audience of the warning. People who know there are the "tree" aspect and the "history" aspect in the merge and the revert operation will not get confused by the issue we describe in the new HOW-TO, and they will understand the ramifications without the help from the warning in your new paragraph. The new warning is trying to help people who do not understand these two aspects.. I have a strong suspicion that the "tree" aspect is much easier to grasp by new people, while the understanding of the "history" aspect comes much later when one becomes more proficient in using git. Also, the immediate interest of people who are reading "git revert" manual page is to revert the effect of the merge in the "tree" aspect (iow, "I want to get the damn thing work again"); that is where the focus of their attention is when they read this manual page. Your "not completely" does not tell them that the incompleteness you talk about is "tree aspect only, not history aspect". That is what I meant by "... may get a wrong impression". Their attention is about the "tree" aspect, and your "not completely" will be easily misinterpreted as "the tree effect of the merge won't get reverted completely", which is not what you want to say. And that is why I think you are much better off not saying "not completely" if you do not explain what you mean by it. As I showed you how in the previous message, an alternative is to say (the equivalent of) "not completely", but explain what incompleteness you mean. >> Linus's "does not completely undo" only refers to the history part of the >> merge, and that only affects future re-merges from the same branch, which >> the reader who is interested in doing a revert of a merge right now (that >> is why s/he is reading this paragraph) may not yet care about. > > They may not care about it now, but it doesn't make much sense to warn about > it during the later merge (plus it might be computationally expensive to > detect). Who's talking about giving a warning by computation? Please stay on the discussion of your documentation patch. >> An alternative is to give a complete but brief explanation. Perhaps like >> this: >> >> By reverting a merge, you are declaring that you will never want the >> changes that were brought in by that merge you are reverting in your >> tree. If you do merge from the same branch again in the future after >> it is updated, git remembers your declaration, and only the changes on >> the branch that were made after the reverted merge will be brought in. >> This may or may not be what you want. See 'revert-a-faulty-merge' >> HOWTO for more details. > > I think the wording might need to be changed a little bit, but I do like the > longer, more complete and clear explanation and I'll work on a patch that has > one. -- 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
