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.
1. Quick start
1.1 Git diff
Open a file tracked by Git.
Run Fluid Diff: Git.
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.
1.2 From a diff editor
Open a single-file diff in VS Code, for example from the Source Control view or the Timeline view.
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.
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.
1.3 Compare two files
In the Explorer, select exactly two files.
Right-click and run Fluid Diff: Compare Selected.
Read the diff:
| Left pane |
Right pane |
| First file in the selection |
Second file in the selection |
2. Ways to open it
| Where |
How |
| Command Palette |
Cmd+Shift+P (macOS) or Ctrl+Shift+P, then a command from the table below |
| Editor title bar |
Click Fluid Diff: Git while a text editor has focus |
| Keyboard shortcut |
Bind a key to a command id from the table below |
| 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 |
| Diff editor title bar |
Click Fluid Diff: From Diff Editor while a single-file diff is active |
| Command |
Id |
What it does |
| Fluid Diff: Git |
fluid-diff.fluidDiffGit |
Compares the open file with its HEAD version. Unsaved edits are included. |
| Fluid Diff: Compare Selected |
fluid-diff.fluidDiffSelected |
Compares the two files selected in the Explorer. |
| Fluid Diff: From Diff Editor |
fluid-diff.fromDiffEditor |
Reopens the active single-file diff. |
| Fluid Diff: Select Theme |
fluid-diff.selectTheme |
Sets the theme: Auto, Light, Dark, Dracula, or Follow VS Code. |
| Fluid Diff: Select Font |
fluid-diff.selectFont |
Sets the font: Small, Medium, Large, or Follow VS Code. |
3. 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, then scroll. Lists, a table, a figure, code, and the changed equation stay highlighted.
4. 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 |
Follow VS Code |
UI colors and syntax colors from the applied VS Code theme |
| Light |
Dark |
 |
 |
| Dracula |
Follow VS Code |
 |
 |
5. Font
Run Fluid Diff: Select Font from the Command Palette, or set fluid-diff.font in Settings.
| Font |
Look |
Small |
11px monospace, 16px line |
Medium (default) |
13px monospace, 20px line |
Large |
16px monospace, 24px line |
Follow VS Code |
Editor font, size, weight, and line height |
Select Font, then switch to Large, Small, and Follow VS Code. Follow VS Code uses the editor font.
An open panel updates when either setting, the VS Code color theme, or the editor font changes.
6. 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, Dracula, and Follow VS Code. Auto follows whether VS Code is light or dark. Follow VS Code uses the applied theme's colors.
- Font. Small, Medium, Large, or Follow VS Code. Follow VS Code uses the editor font, size, weight, and line height.
- Markdown preview. When both files are Markdown, switch between the source and a rendered preview. Math is typeset with KaTeX. Changed blocks stay highlighted.
7. Requirements
- VS Code
1.128.0 or newer
- Built-in Git extension enabled
8. 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 |
9. Roadmap
- [x] Compare the active file with its
HEAD version
- [x] Compare any two selected files
- [x] Overview scrollbar ruler
- [x] Themes: Auto, Light, Dark, Dracula
- [x] Reopen a built-in single-file diff
- [x] Stage, unstage, and revert single chunks in Git diffs
- [x] Diffing in Markdown preview
- [ ] Open changes from git graph
- [ ] word-level highlight in math equation
10. 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.
11. 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, md, or font to redo only some of them. See scripts/demo/README.md for requirements. The GIF click positions live in scripts/demo/scenes/.
| |