jupyterlab-diff

A JupyterLab extension for showing cell diffs with multiple diffing strategies.

Requirements

• JupyterLab >= 4.0.0

Installation

PyPI Installation

pip install jupyterlab_diff

Development Installation

# Clone the repository
git clone https://github.com/jupyter-ai-contrib/jupyterlab-diff.git
cd jupyterlab-diff

# Install the extension in development mode
pip install -e .
jupyter-builder develop . --overwrite

Usage

Commands

The extension provides commands to show diffs in multiple formats:

• jupyterlab-diff:split-cell-diff - Show cell diff using split view (side-by-side comparison)
• jupyterlab-diff:unified-cell-diff - Show cell diff using unified view
• jupyterlab-diff:unified-file-diff - Show file diff using unified view for regular Python files and other text files

https://github.com/user-attachments/assets/0dacd7f0-5963-4ebe-81da-2958f0117071

Programmatic Usage

Split Cell Diff (Side-by-side View)

app.commands.execute('jupyterlab-diff:split-cell-diff', {
  cellId: 'cell-id',
  originalSource: 'print("Hello")',
  newSource: 'print("Hello, World!")',
  showActionButtons: true,
  openDiff: true
});

Unified Cell Diff

app.commands.execute('jupyterlab-diff:unified-cell-diff', {
  cellId: 'cell-id',
  originalSource: 'print("Hello")',
  newSource: 'print("Hello, World!")',
  showActionButtons: true
});

Unified File Diff

app.commands.execute('jupyterlab-diff:unified-file-diff', {
  filePath: '/path/to/file.py',
  originalSource: 'print("Hello")',
  newSource: 'print("Hello, World!")',
  showActionButtons: true
});

Browser console via window.jupyterapp

The commands can also be run from the browser console (for example during development) via the app object exposed as window.jupyterapp. The commands can be executed exactly the same way using window.jupyterapp.commands.execute(...).

First JupyterLab needs to be started with the --expose-app-in-browser flag to expose window.jupyterapp:

jupyter lab --expose-app-in-browser

Then, in the browser dev tools console:

window.jupyterapp.commands.execute('jupyterlab-diff:split-cell-diff', {
  originalSource: `def add():\n  return\n`,
  newSource: `def add(a, b):\n  return a + b\n`,
  showActionButtons: true
});

Command Arguments

jupyterlab-diff:split-cell-diff (Split View)

jupyterlab-diff:unified-cell-diff (Unified View)

jupyterlab-diff:unified-file-diff (File Diff)

Architecture

Diff Strategies

The extension provides two diff viewing strategies:

• Split diff (split-cell-diff): Uses CodeMirror's two-pane view. Displays original and modified code side-by-side in separate panels with diff highlighting.

• Unified diff (unified-cell-diff/unified-file-diff): Uses CodeMirror's unifiedMergeView. Displays changes in a single unified view with added/removed lines clearly marked. Can be used for both cell diffs and regular file diffs.

Contributing

We welcome contributions from the community! To contribute:

• Fork the repository
• Make a development install of jupyterlab-diff
• Create a new branch
• Make your changes
• Submit a pull request For more details, check out our CONTRIBUTING.md.

Uninstall

To remove the extension, execute:

pip uninstall jupyterlab_diff

Troubleshoot

To check the frontend extension is installed:

jupyter labextension list