Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 6, 2016, 18:06 UTC
Message-ID: <xmqqmvihl5df.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <87h98pps7a.fsf@javad.com>

Sergey Organov <sorganov@gmail.com> writes:

> Ah, I now see. I tried to keep the text intact as much as possible, and
> only split it into description and a note. Well, how about this then:

Much better than your earlier patch, but I am not sure if the updated one is that much better compared to the original.

The pre- and post- state of this "how about this" patch essentially say the same thing, and I suspect that the primary reason why you think the post- state is easier to read is because you wrote it, while the reason why I do not see much difference is because I didn't write the updated one ;-).

I do find "In this case, ... store the combined history" in the original a bit awkward to read, but most of that awkardness is inherited by the updated text. It may benefit from hinting why a new commit is not needed a bit stronger. Here is my attempt:

    When the commit we are merging is a descendant of the current
    HEAD, the history leading to the named commit can be, and by
    default is, taken as the combined history of the two.  Our
    history is "fast forwarded" to their history by updating `HEAD`
    along with the index to point at the named commit.

    This often happens when you are following along somebody else's
    work via "git pull" without doing your own development.

I think the awkwardness I felt in the original and your version is gone from the above attempt, but I doubt that it is better over either of them in any other way.

Show 29 quoted lines

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index b758d55..479400f 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -135,15 +135,17 @@ will exit early with the message "Already up-to-date."
>  FAST-FORWARD MERGE
>  ------------------
>  
> -Often the current branch head is an ancestor of the named commit.
> -This is the most common case especially when invoked from 'git
> -pull': you are tracking an upstream repository, you have committed
> -no local changes, and now you want to update to a newer upstream
> -revision.  In this case, a new commit is not needed to store the
> +When current branch head is an ancestor of the named commit,
> +a new commit is not needed to store the
>  combined history; instead, the `HEAD` (along with the index) is
>  updated to point at the named commit, without creating an extra
>  merge commit.
>  
> +This is very common case when 'git merge' is invoked from 'git
> +pull': you are tracking an upstream repository, you have committed
> +no local changes, and now you want to update to a newer upstream
> +revision.  
> +
>  This behavior can be suppressed with the `--no-ff` option.
>  
>  TRUE MERGE
>
> -- Sergey