e24922828c
repository.json describes vDiff itself; "tags": true means a release is a pushed git tag. channel.json is the file users add to their "channels" setting - it holds nothing but repository URLs, so packages added to it later reach existing users without them changing anything. The two are easy to confuse: Package Control rejects a file under "channels" unless it has a top-level "repositories" key, so a repository file belongs in "repositories". The README spells that out. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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`:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```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.
|