When you update to D and graft F::J, Mercurial runs a number of merges. It will start with this merge:
M = three_way_merge(local=D, other=F, base=E)
If we write +d for the delta between the states C and D, then we start with:
+d +e +f
---- C ---- D ---- E ---- F ----
Turn the graph 90 degrees clockwise and the above three-way merge looks like this:
-e
.---- D
/
E
\
'---- F
+f
That is, we pretend that we started with E and applied the opposite of -e to get to D. I think of as the reverse patch of +e. Starting in E we also went to state F with the normal delta +f. There’s nothing strange here — we have all the states (D, E, and F) in the repository already. So seen like this, it’s clear that we can merge D and F.
Merging is a matter of “completing the diamond”. So we find a new state M that is a mix of D and F and where the difference from D to M is similar to +f and the difference from F to M is similar to -e. It looks like this:
-e +f'
.---- D ----.
/ \
E M
\ /
'---- F ----'
+f -e'
The +f delta became +f' and the -e delta became -e'. This is just a normal three-way merge, but the effect is interesting: we’ve applied F onto D instead of E!
After the merge, the second parent of M to F is dropped:
-e +f'
.---- D ----.
/ \
E M
\
'---- F
+f
To reiterate: We have copied the “effect” of F onto D, that is, we have found a delta (+f') that applied to D give the same effect as when +f was applied to E. We can straighten the graph a bit to get:
+f'
--- D ---- M
\
'---- E ---- F
+e +f
The result is that F is grafted onto D using the full three-way machinery.
-
Q1: What just happened here? So……. how does that work? Why is it better?
A1: Using merges is better than patches since the merge machinery takes things like renames into account.
-
Q2: Is this merge just a normal 3-way merge using D, J’ and M1?
A2: Yes, grafting does not alter the topology of the graph.
-
Q3: Has mercurial stored/used extra information about the graft operation to help it with the merge?
A3: No.
-
Q4: What are the potential problems with a flow like this?
A4: From a merge perspective it should work okay. It will duplicate some history which might be confusing for people.