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

[Junio C Hamano <gitster@pobox.com>]

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