Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`

[Derrick Stolee <stolee@gmail.com>]

On 5/26/2020 11:16 AM, Junio C Hamano wrote:
> Martin Ågren <martin.agren@gmail.com> writes:
> 
>> Let's start a list for `--show-pulls` where we start actually discussing
>> the option, and keep the paragraphs preceding it out of that list. That
>> is, drop all those pluses before the new list we're adding here.
> 
> The way the "History Simplification" section is organized is
> somewhat peculiar in that it begins with a short list of what's
> available, followed by mixture of detailed explanation in prose.  I
> agree with you two that the result of this patch fits very well to
> the surrounding text.
> 
> This is not a new issue introduced by this patch, but ...
> 
>> +--show-pulls::
>> +	In addition to the commits shown in the default history, show
>> +	each merge commit that is not TREESAME to its first parent but
>> +	is TREESAME to a later parent.
>>  +
>> +When a merge commit is included by `--show-pulls`, the merge is
>>  treated as if it "pulled" the change from another branch. When using
>>  `--show-pulls` on this example (and no other options) the resulting
>>  graph is:
> 
> ... "is treated AS IF" somewhat made me go "huh?"; with or without
> the option, the merge did pull the change from another branch,
> didn't it?  The only effect the option has is to make that fact
> stand out in the output.

I guess the 'as if it "pulled" the change from another branch' sentence
is literally talking about the "git pull" command, as opposed to the
"git merge" command, or creating the merge upon completion of a pull request
on a Git service (which is almost always using libgit2 to generate a merge
commit).

Perhaps there is no semantic difference between "pulling" and "merging"
and then this could be reworded to be less awkward.

Thanks,
-Stolee