skills/nilbuild__diffity
1
0
Fork 0
mirror of https://github.com/nilbuild/diffity.git synced 2026-09-19 07:26:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve examples for diffing

Browse Source
This commit is contained in:
Kamran Ahmed
2026-03-17 22:55:45 +00:00
parent 02623b9d31
commit 09ec352309
2 changed files with 77 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+43 -25
View File
@@ -17,19 +17,27 @@ It works with Claude Code, Cursor, Codex, and any AI coding agent.
Run `diffity` inside any git repo — your browser opens with a GitHub-style, syntax-highlighted diff.
```bash
diffity # working tree changes
diffity HEAD~1 # last commit
diffity HEAD~3 # last 3 commits
diffity main..feature # compare branches
diffity v1.0.0..v2.0.0 # compare tags
# everyday use
diffity # review all uncommitted changes
diffity HEAD~1 # review your last commit
diffity HEAD~3 # review your last 3 commits
# branch workflows
diffity main # compare current branch against main
diffity main..feature # compare feature branch against main
diffity main feature # same as above, shorthand syntax
diffity --base main --compare feature # same as above, explicit flags
# releases and tags
diffity v1.0.0 v2.0.0 # compare two releases
diffity v1.0.0 # what changed since v1.0.0
# specific commits
diffity abc1234 # changes since a specific commit
diffity abc1234..def5678 # changes between two commits
```
New to git refs? Here's what the syntax means:
- `HEAD` is your current commit. `HEAD~1` means "one commit back", `HEAD~3` means "three commits back".
- `main..feature` means "what's in feature that's not in main" — exactly what a PR would show.
- `main..HEAD` means "what will my PR look like" — committed changes on your branch vs main.
- `diffity main` (no dots) compares main against your working tree, including uncommitted changes.
The `--base`/`--compare` flags use the same terminology as GitHub PRs — base is what you're comparing against, compare is the branch with changes. You can also use range syntax (`main..feature`) or just pass two positional args (`diffity main feature`).
You can leave comments on any diff — working tree changes, branch comparisons, commit ranges. Copy them into your agent with a button and ask it to resolve them, or use the skills below to let your agent auto-review and auto-solve them.
@@ -45,11 +53,12 @@ Then use the slash commands:
### `/diffity-diff`
Opens the diff viewer in your browser. Optionally pass a ref:
Opens the diff viewer in your browser. Accepts the same refs as the CLI, plus natural language:
```
/diffity-diff # working tree changes
/diffity-diff main..feature # branch diff
/diffity-diff HEAD~1 # last commit
/diffity-diff last 3 commits # natural language works too
```
@@ -57,19 +66,26 @@ Leave comments on any line — when you're done, run `/diffity-resolve` to have
### `/diffity-review`
Your agent reviews the diff and leaves comments in the viewer. Uses severity tags: `[must-fix]`, `[suggestion]`, `[nit]`, `[question]`. Supports refs, focus areas, and natural language:
Your agent reviews the diff and leaves inline comments in the viewer. Uses severity tags (`[must-fix]`, `[suggestion]`, `[nit]`, `[question]`) so you can triage by importance. Supports refs, focus areas, and natural language:
```
/diffity-review # review working tree
/diffity-review main..feature # review branch diff
/diffity-review security # focus on security
/diffity-review main to feature # natural language
/diffity-review what I'm merging into main # also works
/diffity-review # review working tree changes
/diffity-review main..feature # review what you're merging into main
/diffity-review security # focus on security issues
/diffity-review performance in src/lib # focus on performance in specific dir
/diffity-review last 3 commits # natural language works too
```
### `/diffity-resolve`
Reads all open comments and makes the requested code changes. Works with both your comments and AI review comments.
Reads all open comments and makes the requested code changes. Works with both your comments and AI review comments:
```
/diffity-resolve # resolve all open comments
/diffity-resolve abc123 # resolve a specific thread by ID
```
A typical workflow: run `/diffity-review` to get AI feedback, check the comments in the browser, then run `/diffity-resolve` to apply the fixes.
## Multiple projects
@@ -93,12 +109,14 @@ diffity list --json # machine-readable output
## Options
```
--port <port> Custom port (default: auto-assigned from 5391)
--no-open Don't open browser
--dark Dark mode
--unified Unified view (default: split)
--quiet Minimal terminal output
--new Stop existing instance and start fresh
--base <ref> Base ref to compare from (e.g. main, HEAD~3, v1.0.0)
--compare <ref> Ref to compare against base (default: working tree)
--port <port> Custom port (default: auto-assigned from 5391)
--no-open Don't open browser
--dark Dark mode
--unified Unified view (default: split)
--quiet Minimal terminal output
--new Stop existing instance and start fresh
```
## License
packages/cli/src/index.ts
+34 -14
View File
@@ -22,7 +22,9 @@ program
.name('diffity')
.description('GitHub-style git diff viewer in the browser')
.version(pkg.version)
.argument('[refs...]', 'Git refs to diff (e.g. HEAD~3, main, main..feature)')
.argument('[refs...]', 'Git refs to diff')
.option('--base <ref>', 'Base ref to compare from (e.g. main, HEAD~3, v1.0.0)')
.option('--compare <ref>', 'Ref to compare against base (default: working tree)')
.option('--port <port>', 'Port to use (default: auto-assigned from 5391)', '5391')
.option('--no-open', 'Do not open browser automatically')
.option('--quiet', 'Minimal terminal output')
@@ -30,29 +32,47 @@ program
.option('--unified', 'Open in unified view (default: split)')
.option('--new', 'Stop existing instance and start fresh')
.addHelpText('after', `
Examples:
$ diffity Working tree changes
$ diffity HEAD~1 Last commit vs working tree
$ diffity HEAD~3 Last 3 commits vs working tree
$ diffity abc1234 Changes since a specific commit
$ diffity main..feature Compare branches
$ diffity main feature Same as main..feature
$ diffity v1.0.0..v2.0.0 Compare tags`)
Common usage:
$ diffity See all uncommitted changes
$ diffity main What changed since main
$ diffity HEAD~1 Review your last commit
$ diffity --base main --compare feature Compare two branches
$ diffity v1.0.0 v2.0.0 Compare two tags
The --base/--compare flags are optional — positional args and
range syntax (main..feature, main...feature) also work.`)
.action(async (refs: string[], opts) => {
if (!isGitRepo()) {
console.error(pc.red('Error: Not a git repository'));
process.exit(1);
}
// --base/--compare flags take precedence over positional args
if (opts.base || opts.compare) {
if (refs.length > 0) {
console.error(pc.red('Error: Cannot use --base/--compare with positional ref arguments.'));
console.log(` Use either ${pc.cyan('diffity --base main --compare feature')} or ${pc.cyan('diffity main feature')}, not both.`);
process.exit(1);
}
if (opts.compare && !opts.base) {
console.error(pc.red('Error: --compare requires --base.'));
console.log(` Example: ${pc.cyan('diffity --base main --compare feature')}`);
process.exit(1);
}
refs.push(opts.base);
if (opts.compare) {
refs.push(opts.compare);
}
}
for (const ref of refs) {
if (!isValidGitRef(ref)) {
console.error(pc.red(`Error: '${ref}' is not a valid git reference.`));
console.log('');
console.log('Usage:');
console.log(` ${pc.cyan('diffity')} Working tree changes`);
console.log(` ${pc.cyan('diffity HEAD~1')} Last commit vs working tree`);
console.log(` ${pc.cyan('diffity main..feature')} Compare branches`);
console.log(` ${pc.cyan('diffity main feature')} Same as main..feature`);
console.log('Examples:');
console.log(` ${pc.cyan('diffity')} See all uncommitted changes`);
console.log(` ${pc.cyan('diffity main')} What changed since main`);
console.log(` ${pc.cyan('diffity --base main --compare feature')} Compare two branches`);
console.log('');
console.log(`Run ${pc.cyan('diffity --help')} for more options.`);
process.exit(1);