Re: [PATCH] revision: --include-diversions adds helpful merges

From: Derrick Stolee <stolee@gmail.com>
Date: Apr 8, 2020, 23:59 UTC
Message-ID: <91fafa17-c58f-dcd0-320d-48c4512561f6@gmail.com>
In-Reply-To: <xmqqv9m9oe2p.fsf@gitster.c.googlers.com>

On 4/8/2020 5:35 PM, Junio C Hamano wrote:

Show 14 quoted lines

> Derrick Stolee <stolee@gmail.com> writes:
> 
>> Then I suppose we should focus on naming merge commits with this property:
>>
>>   A merge commit that is not TREESAME to its first parent (but is TREESAME
>>   to a later parent).
>>
>> The part in parentheses may be optional, because a merge commit that is
>> not TREESAME to any parent will be included by every history mode.
> 
> A merge that is TREESAME to its first parent does not introduce
> anything new to the mainline (as far as the paths that match the
> pathspec are concerned).  We are trying to find names to call merges
> that are not those no-op merges.  Hmph...

There are three situations for a merge commit:

1. TREESAME to _all_ parents. These are not included.
2. not TREESAME to _all_ parents. These are already included.
3. TREESAME to some, but not TREESAME to others.

The third mode is the one that default mode will drop, but --full-history will include. The new mode will include some of these (the ones that are NOT TREESAME to their first parent).

Show 13 quoted lines

>> In my latest attempt at documentation, I called these merges "diverters"
>> yet still used "--include-diversions". Here are a few other words that we
>> could use:
>>
>>  * diverters or diversions
>>  * redirects
>>  * switches (think railroad switch). Synonym: exchange
>>  * detours
> 
> ...none of the above tells me that they are not no-op (in other
> words, they do something meaningful), so I must be coming from
> a direction different from you are.  What redirects from what other
> thing, for example?

The merges do something meaningful: they "merge in" a "real" change.

I'll just submit my v2 as-is, which includes a significant change to the documentation that should make things more clear.

Thanks, -Stolee