IpynbDiff: Better diff for Jupyter Notebooks

This is a simple diff tool that cleans up Jupyter notebooks, transforming each notebook into a readable markdown file, keeping the output of cells, and running the diff after. Markdowns are generated using an opinionated Jupyter to Markdown conversion. This means that the entire file is readable on the diff.

The result are diffs that are much easier to read:

Diff IpynbDiff
Diff text IpynbDiff text
Diff image IpynbDiff image

This started as a port of ipynbdiff, but now has extended functionality although not working as git driver.

Usage

Generating diffs

IpynbDiff.diff(from_path, to_path, options)

Options:

@default_transform_options = {
  preprocess_input: true, # Whether the input should be transformed
  write_output_to: nil, # Pass a path to save the output to a file
  format: :text, # These are the formats Diffy accepts https://github.com/samg/diffy
  sources_are_files: false, # Weather to use the from/to as string or path to a file
  raise_if_invalid_notebook: false, # Raises an error if the notebooks are invalid, otherwise returns nil
  transform_options: @default_transform_options, # See below for transform options
  diff_opts: {
    include_diff_info: false # These are passed to Diffy https://github.com/samg/diffy
  }
}

Transforming the notebooks

It might be necessary to have the transformed files in addition to the diff.

IpynbDiff.transform(notebook, options)

Options:

@default_transform_options = {
    include_frontmatter: false, # Whether to include or not the notebook metadata (kernel, language, etc)
}