Re: [PATCH] Have manpage reference new documentation on reverting merges.

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

"Boyd Stephen Smith Jr." [off-list ref] writes:

quoted

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

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index caa0729..ea36bdf 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt

@@ -45,6 +45,10 @@ OPTIONS
 	the mainline and allows revert to reverse the change
 	relative to the specified parent.

+	Reverting a merge commit does not completely "undo" the effect of the
+	merge and it may make future merges more difficult.  For more details,
+	please read Documentation/howto/revert-a-faulty-merge.txt.
+

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

Can do.

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.

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.

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

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.
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/