patchHave manpage reference new documentation on reverting merges.

Signed-off-by: Boyd Stephen Smith Jr <bss@iguanasuicide.net>
---
An example addition to the manpage for revert that references Nanako
Shiraishi's new documentation.

 Documentation/git-revert.txt |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

"Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:

I think these new lines need to be dedented, and the previous blank line should be turned into a line with a single '+'.

I'd also suggest removing "does not ... merge and it" from the above sentence to avoid confusing readers, because people who read only the above and do not read the howto document may get a wrong impression that the resulting tree may have some changes that came from the merge even after the revert, which is not the case. Revert will erase the effect the merge had to your tree and that part is complete.

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.

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.

On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:

Can do.

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.

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).

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.

"Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:

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.

Who's talking about giving a warning by computation? Please stay on the discussion of your documentation patch.

Signed-off-by: Boyd Stephen Smith Jr <bss@iguanasuicide.net>
---
On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:

Fixed, I wasn't familiar with asciidoc.

I took the alternative approach.

 Documentation/git-revert.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

"Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:

Thanks. I was thinking about doing this instead; how the reference to the HOW-TO is done is different, and I am hoping that it would give better result for HTML version at least.

 Documentation/git-revert.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

Signed-off-by: Boyd Stephen Smith Jr <bss@iguanasuicide.net>
---
On Sunday 2008 December 21 15:54:18 Junio C Hamano wrote:

Here's a pruned version of my prose, with your link style. I prefer my prose because I don't want to use the word "branch", which implies refs having some important in the later merges, which is not the case from what I understand.

 Documentation/git-revert.txt |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)