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

From: Derrick Stolee <stolee@gmail.com>
Date: Apr 9, 2020, 17:20 UTC
Message-ID: <63667043-dbca-0092-209d-865c2f60efc8@gmail.com>
In-Reply-To: <xmqqeeswodol.fsf@gitster.c.googlers.com>

On 4/9/2020 11:56 AM, Junio C Hamano wrote:

Show 34 quoted lines

> Philip Oakley <philipoakley@iee.email> writes:
> 
>>> Yes, but "redirect", "switch", "detour", or "divert" do not quite
>>> mean "merging in a real change", at least to me.
>>>
>>>> I'll just submit my v2 as-is, which includes a significant change to
>>>> the documentation that should make things more clear.
>>> Thanks.
>> Can I suggest "--side-merges" as a possible descriptor for these
>> non-mainline diversions?
>>
>> My thesaurus had suggested detour and sidetracked, which led to the
>> side-merge view.
> 
> Ahh, sorry Derrick for being slow and thanks Philip for repeating
> "diversion", as the word did not click for me at all when I saw the
> patch and wrote my response.
> 
> But I think it started slowly to dawn on me.  
> 
> Does it come from the worldview where we want to follow the "trunk"
> but because when we notice at a merge that we got everything that
> matters to us from a side branch, we switch the track out of the
> mainline and from then on follow that side branch?  Switching the
> track and following the side branch happens silently with the
> default "history simplification", but the new feature shows where
> that side-tracking happens more prominently---is that where the
> words "divert" etc. come from?
> 
> Then I can understand how these candidate words may have place in
> describing the situation we want to use the feature; I am not yet
> convinced any of the concrete option names floated on the thread (or
> what I can come up with right now) would be clear to our target
> audiences, but at least I am not as confused as I was before.

After thinking about all the great responses here, and having a chat with Dscho about this, then taking a break, I had an "Aha!" moment. We should call this option:

	--show-pulls

The direction here is important. Let's look at a potential "git log --graph --oneline" output to explore this idea:

	* (master) A
	|\
	| * (feature) B
	| |\
	| | *   (topic) C
	| | |\
	| | | |
	| | * | D
	| | | |
	| * | | E
	| | | |
	* | | | F
	| |_|/
	|/| |
	* | |   G
	|/ /
	* /     H
	|/
	*       I

I use (master), (feature), and (topic) to decorate branches that are updated only by "git commit" or "git pull". The file 'foo' was created by commit I.

In this graph, the single-parent commits G and D change 'foo'. The commit G enters master using "git commit".

The commit G enters topic using "git pull" starting from D. The developer on that branch resolves conflicts by taking the version of 'foo' from D. Thus C is TREESAME to D but not G.

The commit B is created by running "git pull topic" from the feature branch.

The commit A is created by running "git pull feature" from the master branch.

Thus, A and B "pulled" the change into their branches. The commit C "pulled" G into the branch, but did not keep the change to 'foo'.

Thus 'git log --graph --oneline master -- foo' would output:

	* D
	* I

'git log --graph --oneline --show-pulls master -- foo' shows:

	* A
	* B
	* D
	* I

'git log --graph --oneline --full-history -- foo' shows:

	* (master) A
	|\
	| * (feature) B
	| |\
	| | *   (topic) C
	| | |\
	| | | |
	| | * | D
	| |_|/
	|/| |
	* | |   G
	|/ /
	| /
	|/
	*       I

'git log --graph --oneline --full-history --simplify-merges -- foo' would show:

	*   C
	|\
	* | D
	| |
	| * G
	|/
	*   I

'git log --graph --oneline --full-history --simplify-merges --show-pulls -- foo' would show:

	* A
	* B
	*   C
	|\
	* | D
	| |
	| * G
	|/
	*   I

In conclusion, I think "--show-pulls" provides the right context for these extra merges to show in the history view. It also roots these merges in a Git-native name (that also happens to evoke the "pull request" concept that is _not_ native to Git).

What do you think?

Thanks, -Stolee