Introduction

Download the CLICKABLE MOCKUP !

A Configuration diff and merge tool to allow users to model new configuration based on existing configuration, easily compare configuration to see what has changed, and merge changes into the same configuration. Include features that help compare and model Magnolia trees specifically including the ability to compare trees in the JCR with trees loaded from file, the ability to ignore order, and the ability to equate nodes of different names so that their subtrees can be compared with each other.

Use Cases

Model configuration based on existing configuration

• The Problem: 
  • The user would like to create a business object such as a content app by basing it off of an existing content app
  • When the configuration is large, it is difficult to tell what one configuration has that the other may still need
  • It is tedious to create properties in the new business object to match the existing business object by hand or using duplicate/move
  • It is tedious to compare either by scrolling or by placing two windows next to each other
• The Solution:
  
  • In the Compare Config App, select the root node for the baseline business object on the left of the split view and the root for the new business object on the right
  • Use the colored rows which highlight the differences to easily tell what nodes and properties the baseline business object has that the new business object does not
  • Use actions supplied by the Compare Config App to quickly migrate these differences from the baseline business object to the new business object
  • Use the colored rows to review the differences between the baseline and new business objects to make sure all differences are on purpose
  • Use sample business objects supplied by Magnolia to get started quickly

Analyze and merge changes from other developers

• The Problem: 
  
  • Several developers may make changes to bootstrap files at the same time and it is not clear how to merge these changes
• The Solution: 
  
  • In the Compare Config App, load one bootstrap file on the left and one on the right
  • Use the colored rows which highlight the differences to easily tell what one has that the other doesn't
  • Use actions supplied by the Compare Config App to quickly merge differences from one to the other
  • Use export actions supplied by the Compare Config App to quickly update the bootstrap files 

Know what to export and write version handlers for

• The Problem:
  
  • After doing many edits in the configuration tree while working on a higher level goal, one is unsure what bootstrap files and/or version handlers need to be updated
• The Solution:
  • Before starting on the higher level goal, one exports a snapshot of the configuration tree
  • After working on the higher level goal, in the Compare Config App, one loads the snapshot of the tree in the left of the split view and the current tree on the right of the split view
  • Use the colored rows which highlight the differences to easily tell what configuration has changed and needs to be updated in bootstrap files/version handlers
  • Use export actions supplied by the Compare Config App to quickly create new bootstrap files

Check bootstrap files and version handlers create the correct tree

• The Problem:
  
  • After creating bootstrap files and version handlers, it is hard to tell if they faithfully recreate the configuration tree created by hand
• The Solution:
  
  • One exports a snapshot of the configuration tree configured by hand
  • One deletes the repository and uses the bootstrap files and/or version handlers to recreate it
  • In the Compare Config App, load the snapshot of the hand-crafted tree in the left of the split view and the recreated tree on the right
  • Use the colored rows which highlight the differences to easily tell whether the configurations are the same, or whether any differences are intentional
  • If there are any mistakes, use export actions to quickly correct the bootstrap files

Feature Overview

• Load trees from JCR or files
• Define root where to start
• Select whether or not to ignore order and if so whether to display based on left or right tree order
• Uses split view or collated view to display the comparison
• Use colors to show what is highlight differences
• Equate nodes of different names so that their subtrees can be compared
• Expand subtree of selected no intelligently to show all differences
• Copy selected nodes from left to right or vice versa
• Can export easily

Why Don't Normal Text Diff Tools Work?

• Text diff does not understand tree hierarchy, causing incorrect differences to be highlighted
• Text diff cannot take order into account, causing incorrect differences to be highlighted
• Text diff does not allow you to move changes to from tree to the other easily
• Text diff does not show you the collated tree pieced together from various sources
• Text diff does not allow you to navigate the text as a tree by expanding and collapsing
• Text diff cannot conveniently compare against trees in the JCR

Comparison to JSON and YAML Diff Tools

• JSON Diff: http://tlrobinson.net/projects/javascript-fun/jsondiff
  
  • Good
    
    • Takes JSON syntax and hierarchy into consideration so no incorrect diffs
    • Ignores order so no incorrect diffs
    • Resulting tree displaying the diffs can be expanded and collapsed
  • Bad
    
    • No merge facilities
    • Cannot only diff one snippet of JSON at a time, not directory tree of JSON files
    • Cannot diff collated configuration tree
    • Cannot link nodes with different names to treat them as the same node
    • Can only diff JSON, not JSON with JCR etc.
    • Does not show visually what is a folder, node, or property

• YAML Diff: https://github.com/wallace/yamldiff