Files
skillshare/website/docs/reference/commands/diff.md
T
Willie 7af9224896 fix(diff): list only what sync prunes, and have doctor follow it (#942)
Three previews disagreed with what sync does to a link no skill or
agent maps to.

The agent diff, in the CLI and the dashboard, listed every orphan link
as a removal. Agent sync prunes a link only in merge mode, and only when
it is broken or points into the source, so a live link to another
location was listed forever. Both diffs now ask the function prune uses.

The CLI diff listed no orphan links at all for merge-mode skills, so a
skill removed from the source showed nothing until sync pruned its
link. It now lists the links sync.OrphanLink says prune removes.

doctor called a broken link "did not create, kept" whenever OwnsLink was
false. Prune also removes a broken link under a name the manifest
records in any form once no skill maps to it, so doctor told the user to
delete by hand a link that sync removes. It now reports those as broken
and suggests sync. An empty source counts as "every entry is an orphan";
only a failed discovery turns the check off.

Closes #939
Closes #940
Closes #941
2026-11-17 13:38:31 +08:00

267 lines
7.8 KiB
Markdown

---
sidebar_position: 2
---
# diff
Show differences between source and targets.
```bash
skillshare diff # All targets (interactive TUI)
skillshare diff claude # Specific target
skillshare diff agents # Agent targets only
skillshare diff --stat # File-level changes
skillshare diff --patch # Full unified diff
```
```text
skillshare diff --no-tui
claude, claude-work, gemini, opencode, universal
New remotion-captions
cursor
Local only cursor-shortcuts
New remotion-captions
Extras
✓ commands ~/.claude/commands · in sync
✓ rules ~/.claude/rules · in sync
✓ rules ~/.cursor/rules · in sync
✓ team ~/.codex · in sync
✓ team ~/.claude · in sync
✓ team ~/.gemini · in sync
✓ team ~/notes · in sync
! 6 targets: 6 to sync
Next
skillshare sync apply the changes
skillshare collect copy local-only skills into source
```
Ambiguous agent variants appear as `(skill selection)` skip rows with a diagnostic. Use `include`/`exclude` or a source-local target override to select the desired variant. These rows explain skipped selection; they are not changes that sync can apply.
## Interactive TUI
On a TTY, `diff` opens an interactive view: targets on the left, and what differs for the selected target on the right, down to file-level diffs. The keys are listed at the bottom of the screen. Use `--no-tui`, or pipe the output, for plain text.
## When to Use
- See exactly what's different between source and a target before syncing
- Find skills that exist only in a target (local-only, not yet collected)
- Identify local copies that could be replaced by symlinks
- Inspect file-level changes with `--stat` or full text diff with `--patch`
## Example Output
```
claude
Local override local-copy
Local only my-local-skill
New another-skill, missing-skill
✓ cursor in sync
! 2 targets: 1 to sync, 1 in sync
Next
skillshare sync apply the changes
skillshare sync --force also replace local copies
skillshare collect copy local-only skills into source
```
### Grouped Multi-Target Output
When multiple targets have identical diff results, they are grouped into a single block to reduce noise:
```
agents, claude
New skill-1, skill-2
cursor
New skill-1
✓ codex, copilot in sync
```
Targets with different results (e.g. due to `include`/`exclude` filters) are still shown separately.
## Labels
| Label | Meaning | Action |
|-------|---------|--------|
| New | In source, missing in target | `sync` will add it |
| Restore | Was in target, deleted | `sync` will restore it |
| Modified | Content or target naming changed (copy mode), or an unedited copy-mode copy that merge sync replaces with a link | `sync` will update it |
| Renamed | Managed entry still under the name an earlier `target_naming` gave it | `sync` will rename it |
| Local only, skill kept under old name | A local folder holds the name the current `target_naming` gives a skill, so the skill stays under its old managed entry, shown as `name (stays at old-name)` | Rename or remove the folder, then `sync` |
| Local override | Local copy instead of symlink (including a copy-mode copy you edited) | `sync --force` to replace |
| Orphan | In manifest but not in source | `sync` will prune it |
| Local only | Only in target, not in source | `collect` to import |
## File-Level Details
### `--stat`
Shows which files differ within each skill:
```bash
skillshare diff --stat
```
```
claude
Modified my-skill
+ new-file.md (120 bytes)
~ SKILL.md (840 → 912 bytes)
- old-file.md (64 bytes)
```
### `--patch`
Shows full unified text diff for modified files:
```bash
skillshare diff --patch
```
```
claude
Modified my-skill
~ SKILL.md (840 → 912 bytes)
--- SKILL.md
- old line
+ new line
```
Both `--stat` and `--patch` imply `--no-tui` (plain text output).
## What Diff Shows
### Merge Mode Targets
For targets using merge mode (default):
- Lists skills in source not yet symlinked to target
- Shows skills that exist as local copies instead of symlinks
- Identifies local-only skills in target (not in source — preserved by sync)
- Shows links to skills no longer in source (will be pruned on sync)
### Copy Mode Targets
For targets using copy mode:
- Lists skills in source not yet managed (missing from manifest)
- Shows content changes via checksum comparison
- Shows orphan managed copies no longer in source (will be pruned on sync)
- Identifies local-only skills (not in source and not managed)
### Symlink Mode Targets
For targets using symlink mode:
- Simply checks if symlink points to correct source
- Shows "in sync" or warns about wrong symlink
## Use Cases
### Before Sync
Check what will change:
```bash
skillshare diff
# See what sync will do, then:
skillshare sync
```
### Finding Local Skills
Discover skills you created directly in a target:
```bash
skillshare diff claude
# Shows: Local only my-local-skill
skillshare collect claude # Import to source
```
### Inspecting Changes
See exactly what changed in a skill before syncing:
```bash
skillshare diff --patch claude # Full text diff
skillshare diff --stat claude # File-level summary
```
### Troubleshooting
When sync status shows issues:
```bash
skillshare status # Shows "needs sync"
skillshare diff claude # See exactly what's different
skillshare sync # Fix it
```
## Agent Diff {#agent-diff}
Use the `agents` keyword to diff only agent targets:
```bash
skillshare diff agents # All agent-capable targets
skillshare diff agents claude # Specific target
skillshare diff agents --json # JSON output
```
Agent diff shows missing agents (need sync), orphan symlinks that sync will prune, and local-only agent files. Only targets with an `agents` path configuration are included. See [Agents — Supported Targets](/docs/understand/agents#supported-targets) for the full list.
---
## Options
| Flag | Description |
|------|-------------|
| `--project, -p` | Use project mode |
| `--global, -g` | Use global mode |
| `--stat` | Show file-level changes (implies `--no-tui`) |
| `--patch` | Show full unified diff (implies `--no-tui`) |
| `--no-tui` | Plain text output (skip interactive TUI) |
| `--json` | Output as JSON (implies `--no-tui`) |
## JSON Output
```bash
skillshare diff --json
```
```json
{
"targets": [
{
"name": "claude",
"mode": "merge",
"synced": false,
"items": [
{"action": "add", "name": "missing-skill", "kind": "skill", "reason": "source only", "is_sync": true},
{"action": "modify", "name": "local-copy", "kind": "skill", "reason": "local copy (sync --force to replace)", "is_sync": true},
{"action": "remove", "name": "my-own-skill", "kind": "skill", "reason": "local only", "is_sync": false},
{"action": "kept", "name": "prototype", "kind": "skill", "reason": "local folder; the skill stays at _emil-design__skills__prototype", "is_sync": false}
],
"include": [],
"exclude": []
}
],
"duration": "0.045s"
}
```
`synced` is `true` when `sync` has nothing to do for the target. Items with `"is_sync": false`, such as folders that exist only in the target, are still listed but do not make it `false`. The text output likewise counts a target with only local-only folders as in sync.
`action` is `add`, `modify`, `remove`, or `kept`. `kept` means a local folder holds the name the current `target_naming` gives the skill, so the skill stays under its old name and sync leaves the folder alone.
## See Also
- [sync](/docs/reference/commands/sync) — Sync to targets
- [collect](/docs/reference/commands/collect) — Import local skills
- [status](/docs/reference/commands/status) — Quick overview