Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Comparing Notebooks
A key feature of Wolfram/DiffTools is its ability to make sense of changes to notebook files and structures. This document shows some of the flexibility and power of notebook comparison features, and how you can leverage them in your own workflows.
Load the paclet:
In[1]:=
Needs["Wolfram`DiffTools`"]
Quick Start: Palettes
If you don't want lots of details about how this works, or why it works, and you just want to jump in and start comparing notebooks or cells: make sure the paclet is loaded, and then head to the Palettes menu in the main menu bar. This paclet provides the Compare Notebooks and Compare Cells palettes, which you can use to initiate comparisons of notebooks and cells that are open in your current session. Enjoy!
If you want some more details, keep reading.
Notebooks
Notebook files contain an ASCII representation of a Wolfram Language expression with head . That expression fully represents the content you see and interact with on screen. Every time you make an edit in a notebook, the result is a change to the underlying expression. Saving the notebook updates the expression stored in the corresponding file.
Unfortunately, viewing the raw ASCII contents of a notebook file is only meaningful to those with a deep understanding of the (largely undocumented) subset of the Wolfram Language which is used by expressions. And viewing differences between two such notebook files, as text, is often more confusing than helpful.
Functions in the Wolfram/DiffTools paclet have a deep knowledge of the kinds of expressions used in notebook files, and goes to great lengths to illuminate differences in a human-understandable way.
That starts with , which when applied to notebooks -- specified via , , or -- compares the notebook contents as a flat list of cells and a sequence of notebook options. It also notices any changes in cell grouping, which is reported separately. (In the case, any data in the file which is outside the expression is ignored.)
In[2]:=
obj=
[Notebook[{Cell["title","Title"],Cell["2+2","Input"]}],Notebook[{Cell["title","Title"],Cell["2+3","Input"],Cell["5","Output"]},WindowSize{100,100}]]
 | Diff |
Out[2]=
If you click the "+" button in the result, you'll see that the content changes are stored at the granularity of cells.
Notebook differences can also be viewed as a report that indicates visually which cells were determined to have been added, removed, or edited; and the same thing for notebook options. This particular view also includes the itself, in case that is useful for further processing.
List the formats supported by notebook comparisons:
In[3]:=
 | DiffView |
Out[3]=
{SummaryBox,Minimal,Report,SideBySide,Unified,SideBySideMarkers,UnifiedMarkers,ArrayPlot,AlignmentChart}
This report does not pre-calculate the differences between cells which are thought to have been edited. However, this report serves as an interface which will calculate those differences on demand, if you choose to open the details of a particular cell change. That calculation and resulting view is exactly what you would see if you compared those two expressions or references directly.
In[4]:=
| Diff |
Out[4]=
Aligning Cells
One interesting problem to solve to effectively compare notebook files is how to align cells. Say the original notebook has a single cell where, in the edited notebook, there are now multiple cells. How can one best determine which cells are new and which cells (if any) are edited or deleted?
is an option to and which the front end uses to ensure it has a unique way to refer to those objects. Every time you create a new notebook or add a new cell, it will automatically get an option set to a new unique identifier.
Except… It's not always unique. Think about notebook files in source control. When comparing an older version of a notebook with a newer version of a notebook, the newer notebook will likely have many of the same settings as the older version. And we definitely don't want the front end to enforce uniqueness here, because the provides important historical information about the cell, and makes aligning cells a breeze!
So by default, if the notebooks given to contain settings, which they should when being read from a file or a , then those settings are used when deciding how to align cells.
As long as the front end is managing these UUIDs in the usual way, this approach will often produce a much more accurate alignment than other heuristics that one could imagine using. But if for some reason these UUIDs cannot be trusted (because of user error in notebook handling, for instance), alternate alignment approaches are available.
The option controls this. By setting to or , you are opting out of UUID-based alignment, and instead will use heuristic alignment, or no alignment (i.e., relying on the alignment provided by of the expressions), respectively.
Another way to opt out of UUID-based alignment would be to actively ignore the value of the option entirely.
is an option to which let you say which changes you care about, and which you don't. You can choose to ignore changes to particular options, or all options and styles.
There may be circumstance in which you're comparing two notebooks, but all you really care about are changes in cell contents. You don't want the resulting report littered with changes to cell options, or notebook options. To do that, use the option.
Don't bother comparing notebook options
In[5]:=
| Diff |
 | IgnoreElements |
Out[5]=
Conflicts and Merging
Coming soon!
 |
|
 |
|
""