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

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

[Boyd Stephen Smith Jr.]

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

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.
+
 --no-edit::
 	With this option, 'git-revert' will not start the commit
 	message editor.
-- 
1.5.6
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

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

[Junio C Hamano]

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

> 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(-)
>
> 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 '+'.

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.

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

[Boyd Stephen Smith Jr.]

[-- Attachment #1: Type: text/plain, Size: 3303 bytes --]

On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:
> "Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:
> > ---
> > 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/                      \_/     

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

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

[Junio C Hamano]

"Boyd Stephen Smith Jr." <bss@iguanasuicide.net> 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.

[PATCHv2] Have manpage reference new documentation on reverting merges.

[Boyd Stephen Smith Jr.]

Signed-off-by: Boyd Stephen Smith Jr <bss@iguanasuicide.net>
---
On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote:
> "Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:
> > +	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 '+'.

Fixed, I wasn't familiar with asciidoc.

> 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.
>
> An alternative is to give a complete but brief explanation.  Perhaps like
> this:

I took the alternative approach.

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

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index caa0729..daa77a9 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -44,6 +44,13 @@ OPTIONS
 	option specifies the parent number (starting from 1) of
 	the mainline and allows revert to reverse the change
 	relative to the specified parent.
++
+Reverting a merge commit declares to git that you will never want the tree
+changes brought in by the merge but never alters the history changes caused by
+the merge.  The history allows git to remember you rejected the tree changes
+and, as a result, later merges will only bring in changes introduced by commits
+that are not ancestors of the revert commit.  This may or may not be what you
+want.  See the 'revert-a-faulty-merge' HOWTO for more details.
 
 --no-edit::
 	With this option, 'git-revert' will not start the commit
-- 
1.5.6
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

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

[Junio C Hamano]

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

> I took the alternative approach.

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

diff --git c/Documentation/git-revert.txt w/Documentation/git-revert.txt
index caa0729..b87f2b3 100644
--- c/Documentation/git-revert.txt
+++ w/Documentation/git-revert.txt
@@ -44,6 +44,15 @@ OPTIONS
 	option specifies the parent number (starting from 1) of
 	the mainline and allows revert to reverse the change
 	relative to the specified parent.
++
+By reverting a merge, you are telling git that you never want the changes
+the merge made to your tree.  If the branch the reverted merge merged is
+updated later, and you merge from it again, git remembers this, and only
+brings in the changes on the branch that are made after the previously
+reverted merge.  This may or may not be what you want.
++
+See link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for
+more details.
 
 --no-edit::
 	With this option, 'git-revert' will not start the commit

[PATCHv3] Have git revert documentation reference new HOWTO on reverting faulty merges.

[Boyd Stephen Smith Jr.]

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

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

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index caa0729..ee9cb82 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -44,6 +44,14 @@ OPTIONS
 	option specifies the parent number (starting from 1) of
 	the mainline and allows revert to reverse the change
 	relative to the specified parent.
++
+Reverting a merge commit declares that you will never want the tree changes
+brought in by the merge.  As a result, later merges will only bring in tree
+changes introduced by commits that are not ancestors of the revert commit.
+This may or may not be what you want.
++
+See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for
+more details.
 
 --no-edit::
 	With this option, 'git-revert' will not start the commit
-- 
1.6.0.2
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

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

[Boyd Stephen Smith Jr.]

[-- Attachment #1: Type: text/plain, Size: 966 bytes --]

On Sunday 2008 December 21 15:54:18 you wrote:
> "Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:
> > I took the alternative approach.
>
> 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.

I like the different link style (still learning asciidoc here), although I am 
mainly concerned with the manpage output.

However, I intentionally avoided using the word "branch" in my prose, because 
that implies (to me) that the ref is what is remembered and important.  
That's not technically correct, as refs are not part of the history that is 
considered during the later merge.
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]