Diffs

MergeBoard allows you to view code changes in three ways:

Normal: The normal unified diff as used by git: Inserted lines get a green background, deleted ones a red background. Changes are matched as best as possible by comparing the content of files line by line.
No Whitespace: Same as Normal with the difference, that whitespace changes are ignored.
SemanticDiff: Instead of comparing lines, SemanticDiff compares code logic and matches old and new code based on that.

In the following we will take a close look at how MergeBoard displays a diff to you and how SemanticDiff makes your life easier!

The Normal Unified Diff

../../_images/review_diff_normal.png — An example of a normal diff. Click to view in higher resolution. Based on commit 292660fa from the open source project Linux (license: GPL-2.0).

The diff you are probably used to from command line tools like diff -u or git diff and hosters like GitHub etc, shows you what lines in your documents have been added or removed. Independent of the algorithm used to compute the diff (Myers, Minimal, Patience, and Histogram), the way how the output is displayed stays the same. While this kind of diff is guaranteed to show you all changes, it can sometimes lead to overwhelming results if code is reformatted or moved.

In the example above you can see what a reformatting merge request looks like. Changed lines are matched, where the old and thus deleted line is above the new i.e. inserted line. Deleted lines are shown with a red background, whereas added lines are shown with a green background.

SemanticDiff

../../_images/review_diff_ast.png — An example of an SemanticDiff diff. The code and changes are the same as in the example for normal mode. Click to view in higher resolution. Based on commit 292660fa from the open source project Linux (license: GPL-2.0).

As already introduced above, MergeBoard’s SemanticDiff mode allows you to compare actual code logic. This is done by parsing the code into an abstract syntax tree 1, both the old and new one, and generating an edit script from one tree to the other. This way MergeBoard is able to distinguish not only between insertions and deletions but also updates and moves of code blocks. All this is additionally done on all hierarchical levels, i.e. not restricted to lines. This means e.g. SemanticDiff can detect an update of a variable name inside a moved code block and MergeBoard will show this to you.

Filtering unimportant changes

SemanticDiff often displays smaller diffs compared to The Normal Unified Diff as it can filter out changes that do not affect the program logic. This includes, for example, code reformatting and some language specific code invariances. If you compare the image above with the one from The Normal Unified Diff, you can see that all irrelevant changes are filtered out, because they do not affect the program flow. This example also makes it clear how much easier it is to spot important modifications using SemanticDiff.

Changes in logic

../../_images/diff_move_ast.png — Example of various changes in logic. Based on commit 41018a51 from the open source project Rocket (license: Apache or MIT).

If you move a code block, MergeBoard will visualize this for you as can be seen in the example above. Highlighted with a dashed box we can see a set of lines that have been moved from top to bottom.

Another way to look at this example is that we know that the moved block is the same as before. This is a very useful guarantee, because now you only need to focus on the actual changes and not check ever single word in each block.

../../_images/diff_update_ast.png — Example of grouped argument change updates. Based on commit 8c92d969 from the open source project GORM (license: MIT).

Also very handy is MergeBoard’s update detection, that gives you colored highlights for groups of similar changes, like e.g. variable renames or value changes. One of these examples can be seen in the image above, where db is replaced by tx at multiple locations.

Depending on how complex the update is, MergeBoard chooses between two depictions: If the updated variable is shown inside a box with dashed border all the changes that happened to this specific variable are shown inside the box and colored accordingly. In the example on the left this would be adding check_ to the already existing name.

If the variable is shown inside a solid box it has a partner, that can be found by hovering the variable and following the arrow that appears. Both together show the complete change that the variable has undergone. In the example on the left this would be swapping out the " parenthesis with '.

Note

SemanticDiff generally provides a cleaner and easier to understand diff, but in rare cases it may not have the desired effect. You can help us improve SemanticDiff by reporting such cases.

Footnotes

1: Currently MergeBoard can parse the following languages: C#, CSS / SCSS, Go, Java, JavaScript / JSX, JSON, PO (gettext), Python, Rust, TypeScript / TSX