# # # rename "wiki/ZipperMerge.moin" # to "wiki/ZipperMerge.mdwn" # # patch "wiki/ZipperMerge.mdwn" # from [ccfc87030e67fc1a285b328b4e4b74d84c1f29ce] # to [fe042ebc644780b3a756041303d6dfe8dc972bb0] # ============================================================ --- wiki/ZipperMerge.moin ccfc87030e67fc1a285b328b4e4b74d84c1f29ce +++ wiki/ZipperMerge.mdwn fe042ebc644780b3a756041303d6dfe8dc972bb0 @@ -1,22 +1,28 @@ -Zipper Merge is a BestPractices workflow pattern that uses the DAG structure to help simplify large complex merges. -It's an application of the same principles used by the DaggyFixes pattern, but for the scenario where you want to merge two branches together, rather than make the same change to two branches that must remain separate otherwise. +[[!toc ]] +[[tag migration-wip]] -= Scenario = +Zipper Merge is a BestPractices workflow pattern that uses the DAG +structure to help simplify large complex merges. +It's an application of the same principles used by the DaggyFixes +pattern, but for the scenario where you want to merge two branches +together, rather than make the same change to two branches that must +remain separate otherwise. + +# Scenario + You're trying to merge two paths of development that diverged some time ago, and that have had significant changes along each path in the meantime. -{{{ - A - / \ - / \ - B1 C1 - | | - B2 C2 - : : - Bn Cn -}}} + A + / \ + / \ + B1 C1 + | | + B2 C2 + : : + Bn Cn For one reason or another, these development paths haven't had @@ -28,43 +34,44 @@ The key point is that you have a lot of The key point is that you have a lot of merging work to do. -= Problems with an all-at-once merge = +# Problems with an all-at-once merge A simple `merge` or `propagate` command isn't ideal here, largely because the merging to be done isn't simple. These commands are most useful for smaller, simpler merges that might occur more often. They happen all the time within a single development branch, and they're usually very easy or trivial to do, because the heads being merged haven't diverged much since their most recent common ancestor. When there's much more significant divergence, attempts to use these commands to do all the merging in one hit can be frustrating: + * lots of files are involved, and `merge` will prompt you for interactive merging assistance for each file where there are conflicts, in apparently random order. - There's no easy way to order and organise your merging work. + *There's no easy way to order and organise your merging work.* * if something goes wrong (such as one of these interactive merges failing) the entire merge will fail, and you'll have to start again from the beginning. - There's no easy way to save and resume your merging work. + *There's no easy way to save and resume your merging work.* * if you get through all the content merges, the new revision will be created, even if some of the merges were wrong or buggy. - There's no easy way to preview and test the result of the merge before committing it. + *There's no easy way to preview and test the result of the merge before committing it.* You're trying a big-bang approach of merging all of the changes in a single step: -{{{ - A - / \ - / \ - B1 C1 - | | - B2 C2 - : : - Bn Cn - \ / - \ / - M -}}} + A + / \ + / \ + B1 C1 + | | + B2 C2 + : : + Bn Cn + \ / + \ / + M + + You want an easy way to do the things that there's no easy way to do in the above points. What you need is a way to break up the merging work into manageable chunks. -= Zipper Merge = +# Zipper Merge The key point about Zipper Merge is that that you don't actually need to do all the merging at once in the one revision. @@ -77,26 +84,24 @@ nodes that didn't happen previously alon This is essentially an effort in recreating the intermediate merging nodes that didn't happen previously along the way: -{{{ - A - / \ - / \ - B1 C1 - |\ / | - B2 M1 C2 - : | /: - Bn M2 Cn - \ : | - Mn / - |/ - M -}}} + A + / \ + / \ + B1 C1 + |\ / | + B2 M1 C2 + : | /: + Bn M2 Cn + \ : | + Mn / + |/ + M DAG history is DAG history - it doesn't really matter what calendar time each node in the graph was actually created, what matters is the placement of the changes in the tree. -== Benefits == +## Benefits You get to work incrementally, saving (and, ideally, testing) your work as you go. You could take as much time as you like progressively @@ -116,7 +121,7 @@ be scared of unmerged heads, even ones t This is one of several reasons we encourage developers not to be scared of unmerged heads, even ones that persist for some time. -== Using a separate branch == +## Using a separate branch It might be convenient to use a special zipper branch name for this purpose if you like. In this case, you could @@ -127,10 +132,10 @@ revision id's, that will produce the sam Otherwise, if you're happy just using `explicit_merge` and revision id's, that will produce the same DAG structure result. -== Tools == +## Tools Whether or not you use a separate branch, a graph visualisation tool (like monotone-viz) -can be '''''very''''' helpful to look at diffs along each side, +can be **very** helpful to look at diffs along each side, pick useful nodes to zipper together, and follow your progress. A good interactive merge assistance tool is also invaluable for @@ -138,7 +143,7 @@ See InterfacesFrontendsAndTools for tool See InterfacesFrontendsAndTools for tools that can help with both. -= Usage comments and notes for further development = +# Usage comments and notes for further development (please add comments of your own here, too)