vdiff/README.md

vDiff

Review what a coding agent changed without leaving Sublime Text: the whole file, deletions in red, insertions in green, in the file's own syntax highlighting. Stage, unstage or discard the file, or jump to the real file at the caret's line.

Needs Sublime Text build 4213 or later, the build that replaced the Python 3.8 plugin host with Python 3.14. No dependencies.

Install with Package Control

vDiff is not on the default channel, so add this one first. Open Preferences → Package Settings → Package Control → Settings and put the channel URL in the channels array of the right-hand (User) pane:

{
    "channels": [
        "https://packagecontrol.io/channel_v3.json",
        "https://raw.githubusercontent.com/vaclavt/vdiff/main/channel.json"
    ]
}

Keep https://packagecontrol.io/channel_v3.json in the list — dropping it hides every default package. Then run Package Control: Install Package from the Command Palette and pick vDiff. Upgrades arrive through Package Control: Upgrade Package like any other package.

Install from source

Clone or symlink the repository into the Sublime Text Packages directory as vDiff:

git clone https://github.com/vaclavt/vdiff.git \
  "$HOME/Library/Application Support/Sublime Text/Packages/vDiff"

Use one method or the other, not both: an unpacked Packages/vDiff directory overrides the vDiff.sublime-package that Package Control installs.

Command Palette

• vDiff: Changed Files – uncommitted changes (staged, unstaged, untracked). Arrowing through the list previews each file; Enter keeps it, Esc goes back to what was shown.
• vDiff: Recent Commits – last N commits, then the files of the chosen commit. A key binding to vdiff_commits with {"sha": "HEAD"} skips the list and reviews the last commit directly.

Keys inside the review view

key	action
f / c	changed files / recent commits panel
s / u / d	stage / unstage / discard the file (uncommitted mode); s then moves on to the next unstaged file
C	commit the staged files, typing the message in an input panel
m	amend the last commit: edit its subject, keep its body, fold in anything staged
o or Enter	open the real file at this line
] / [	next / previous change (wraps at the ends)
n / p	next / previous file of the current list (wraps at the ends)
j / k	move down / up one line (vim keys)
r	refresh
?	show this key list in a popup
Esc	close the view

The header links do the same with the mouse. Settings: vDiff.sublime-settings.

The channel

Two files in this repository feed Package Control, and the distinction between them matters:

• repository.json — a repository file. Its top-level key is packages, and it describes vDiff itself: where the code lives and which releases exist. "tags": true means Package Control reads the repository's git tags, so publishing a release is just git tag v1.0.1 && git push --tags. A package whose tags are all unpushed resolves to zero releases, and Package Control drops it from the list without an error — if vDiff is missing from Install Package, check the tags reached GitHub.
• channel.json — a channel file. Its top-level key is repositories, and it is nothing but a list of repository-file URLs. This is the one users add to channels.

The indirection is what makes a channel worth having: users add one URL once, and every package you later append to repositories shows up in their Install Package list without them changing anything.

Adding another package to the channel

Append the URL of that package's repository file to repositories in channel.json:

{
    "$schema": "sublime://packagecontrol.io/schemas/channel",
    "schema_version": "4.0.0",
    "repositories": [
        "https://raw.githubusercontent.com/vaclavt/vdiff/main/repository.json",
        "https://raw.githubusercontent.com/vaclavt/vAI/main/channel.json"
    ]
}

Two things to watch:

• The URL must be a repository file (top-level packages), whatever it is named. vAI's channel.json is a repository file despite its name, so it belongs in a repositories array — Package Control rejects any file without a repositories key when it is listed under channels.
• Package Control fetches anonymously over HTTPS, so the URL has to be publicly readable. A package on a private host is not installable this way.

If you would rather skip the channel for a single package, a repository file can be added directly to the repositories array of Package Control's settings instead.