Fluid Diff

Side-by-side diff viewer for VS Code, in the style of Meld and SmartGit.

Intuitive Diff UI · Aligned panes · Word-level highlights

Preview

Scroll either pane and the other follows, with connectors linking each changed chunk.

Hover a mark on the ruler to highlight its chunk, then click to jump to it.

---

Quick start

Git diff

1. Open a file tracked by Git.

2. Run Fluid Diff: Git.

3. Read the diff:

   Left pane	Right pane
   File as committed in HEAD	Current editor buffer, unsaved edits included

Stage, unstage, and revert chunks

In Fluid Diff: Git, each changed chunk has buttons at the right edge of the right pane, just above the chunk.

Button	What it does
↶ Revert	Replaces the chunk in the editor buffer with its HEAD version. The file is not saved.
+ Stage	Stages only this chunk, like picking one hunk in git add -p. The file on disk is not touched.
− Unstage	Removes this chunk from the staging area. Other staged chunks stay staged.

• Staged chunks are faded and drawn with dashed outlines, so unstaged work stands out. The left pane still shows HEAD, so a staged chunk stays visible until you commit it.
• Staging uses the editor buffer, so unsaved edits can be staged. The file's line endings and executable bit are kept.
• Revert is disabled on a chunk that is partly or fully staged. Unstage it first.
• Press Ctrl+Z (Cmd+Z on macOS) in the panel to undo the last revert. If you edited the file after that revert, use undo in the editor instead.
• The view refreshes after every action and whenever you switch back to its tab, and keeps your scroll position.

Revert two chunks, then stage and unstage two more.

Selected files

1. In the Explorer, select exactly two files.

2. Right-click and run Fluid Diff: Compare Selected.

3. Read the diff:

   Left pane	Right pane
   First file in the selection	Second file in the selection

From a diff editor

1. Open a single-file diff in VS Code, for example from the Source Control view or the Timeline view.

2. Click the Fluid Diff: From Diff Editor icon in the editor title bar. If you don't see the icon, click ... in the editor title bar and pick Fluid Diff: From Diff Editor from the menu.

3. Read the diff:

   Left pane	Right pane
   Original side of the diff	Modified side of the diff

Multi-file diffs, such as a whole commit opened from the Source Control Graph, are not supported. Open a single file's diff instead.

Ways to open it

Where	How
Command Palette	Cmd+Shift+P (macOS) or Ctrl+Shift+P, then Fluid Diff: Git
Editor title bar	Click Fluid Diff: Git while a text editor has focus
Keyboard shortcut	Bind a key to fluid-diff.fluidDiffGit
Explorer, one file	Right-click a file and click Fluid Diff: Git
Explorer, two files	Select exactly two files, right-click, and click Fluid Diff: Compare Selected (fluid-diff.fluidDiffSelected)
Diff editor title bar	Click Fluid Diff: From Diff Editor (fluid-diff.fromDiffEditor) while a single-file diff is active

Markdown preview

When both files are Markdown, a Preview button sits between the two paths. Click it to render both panes, including math. Raw switches back to the source. Chunk colors, word highlights, and aligned scrolling stay on.

• Display math ($$ … $$ or \[ … \]) and inline math ($ … $ or \( … \)) are typeset with KaTeX from VS Code's built-in Markdown Math extension.
• Changed words in the prose are marked. An equation is highlighted as one block.
• Scroll position is kept across the switch.

Click Preview to render the Markdown, including the changed equation.

Themes

Run Fluid Diff: Select Theme from the Command Palette, or set fluid-diff.theme in Settings.

Theme	Look
Auto (default)	Light when VS Code uses a light or high-contrast light theme, Dark otherwise
Light	Light background, VS Code Light+ syntax colors
Dark	Dark background, VS Code Dark+ syntax colors
Dracula	Dracula palette, with comments brightened for readability

The theme applies to diff panels opened after the change.

Light	Dark	Dracula

Features

• Aligned panes. Inserted or deleted lines never push the two sides out of step.
• Block colors. Inserted, deleted, and replaced blocks each get their own background.
• Word highlights. Inside replaced lines, the exact changed words are marked.
• Syntax coloring. Each pane uses the language of its own file.
• Overview scrollbar rulers. A ruler beside each pane maps that whole file. Green marks inserts, red marks deletes, and yellow marks replacements. A translucent box shows the visible window. Click a ruler to jump that pane to the clicked spot.
• Chunk actions. In Git diffs, stage, unstage, or revert a single chunk from the diff view.
• Compare any two selected files. Pick two files in the Explorer and open them side by side. This command reads the two files directly.
• Reopen any VS Code diff. From a built-in single-file diff, such as a past commit in the Timeline view, reopen the same two sides in Fluid Diff.
• Themes. Auto, Light, Dark, and Dracula. Auto follows the VS Code color theme.
• Markdown preview. When both files are Markdown, switch between the source and a rendered preview. Math is typeset with KaTeX. Changed blocks stay highlighted.

Requirements

• VS Code 1.128.0 or newer
• Built-in Git extension enabled

Troubleshooting

These messages come from Fluid Diff: Git. If a check fails, the panel stays closed.

Error says	Fix
built-in Git extension is disabled	Enable the Git extension in the Extensions view
file is not in a git repository	Open a file inside a Git repository
No git HEAD version of the file	Commit the file once, then retry

These messages come from the chunk buttons. The panel stays open.

Message says	Meaning
File changed since render; view refreshed	The file changed after the view was drawn, so the button's chunk no longer exists. Click the button again in the refreshed view
File was edited after the revert	Ctrl+Z in the panel won't overwrite later edits. Use undo in the editor instead

Roadmap

• Compare the active file with its HEAD version
• Compare any two selected files
• Overview scrollbar ruler
• Themes: Auto, Light, Dark, Dracula
• Reopen a built-in single-file diff
• Stage, unstage, and revert single chunks in Git diffs
• Diffing in Markdown preview
• Open changes from git graph
• word-level highlight in math equation

Limits

• A gap bigger than 25M cells (about 5000×5000 lines) with no unique line inside becomes one replace chunk.
• Edit-similarity scoring only runs on gaps up to 1M cells.
• A chunk larger than 4M token pairs gets background color only, no word marks.

Development

npm install
npm run compile   # build once
npm run watch     # rebuild on change
npm test          # compile, lint, then run tests

Press F5 in VS Code to start an Extension Development Host with Fluid Diff loaded.

To refresh the README images after a UI change, run scripts/demo/make-images.sh on macOS, or pass stills, git, chunks, compare, timeline, or md to redo only some of them. See scripts/demo/README.md for requirements. The GIF click positions live in scripts/demo/scenes/.