Files
skillshare/website/docs/reference/commands/diff.md
T
Willie c638b46096 fix(sync): replace copy-mode copies with links when switching back to merge (#506)
* fix(sync): replace copy-mode copies with links when switching back to merge

Switching a target from copy back to merge left every copy whose entry name
did not change as a real folder. Merge sync treated it as the user's own
folder, so status and doctor kept saying "run skillshare sync" while sync
changed nothing, and only `sync --force` turned it into a link.

Copy mode already replaces merge-mode links with copies on its own, so merge
sync now replaces a folder the manifest records with a checksum (a copy-mode
copy) with a link, without --force. Folders the manifest does not record, or
records as a link, stay untouched. The pre-sync target backup is unchanged.

The CLI and dashboard diffs name these entries as copies sync replaces
instead of suggesting --force, and the sync-modes docs describe the switch.

* fix(sync): keep copy-mode copies the user edited when switching to merge

The first version replaced any folder the manifest recorded as a copy-mode
copy. The manifest checksum is only a record, so a copy edited since copy
mode made it was deleted too, and `sync --json` and project-mode dashboard
sync take no pre-sync backup to restore it from.

Replace the folder only while it still hashes to the recorded checksum
(Manifest.OwnsCopy). An edited copy is kept and `sync --force` still
replaces it; diff keeps suggesting --force for it. A copy whose name: was
rewritten by prefixed naming, or that was made with custom ignore patterns,
no longer hashes to the source checksum and is kept the same way.

* fix(ui): say a copy-mode copy in a merge target is replaced by a link

The Sync page picks a row's text from the diff item's action alone. The
copy-mode copy that merge sync now replaces comes from the server as an
update, which the page worded as "Link is broken or points elsewhere. Will
be relinked" even though no link exists yet.

Match the server's reason and show "Copy made by copy mode. Will be replaced
by a link" instead, in all eleven dashboard languages.

* docs(sync): say only unedited copy-mode copies are replaced on merge sync

The sync-modes paragraph promised that copies copy mode made are replaced
with links without --force. Merge sync keeps a copy that no longer hashes to
the checksum copy mode recorded, so an edited copy, or one whose name: copy
mode rewrote for prefixed naming, still needs --force.

State the three cases in sync-modes and qualify the diff Modified and Local
override labels, in English and the ja, ko, zh-Hans and zh-Hant copies.

* fix(sync): keep the copy until its replacement link exists

Replacing a copy-mode copy removed the folder first and then created the
link. If creating the link failed (no symlink or junction rights on a
Windows or network filesystem), sync returned an error with the skill gone
from the target. This path now also runs on a plain sync, not only on
--force.

Park the folder beside the entry, create the link, then delete the parked
folder; on failure the folder is moved back. A parked folder left by a run
that died mid-way may be the only copy, so the next sync stops with a message
instead of deleting it. The manifest also forgets the copy-mode mtime and
naming records of an entry that is now a link.

* test(sourcefs): register replaceWithLink's target writes in the raw-write ratchet

The previous commit moved the merge-mode folder replacement into
replaceWithLink, which the ratchet reports as new raw os calls and the old
os.RemoveAll allowance as stale. All of them act on the sync target, not the
skills source, like the neighbouring entries.

* fix(sync): bound the parked copy's name and document the naming exception

The folder parked while a link is created was named after the entry, so an
entry near the 255-byte filename limit (a long flattened nested skill)
could not be moved aside and its replacement failed. The parked name is now
a fixed-length hash of the entry name.

sync-modes also says what happens when `target_naming` changes in the same
sync: the copy gets a new entry name and the prune pass removes it as an
orphan whether or not it was edited, as it did before this change.
2026-10-10 00:13:29 +08:00

264 lines
7.4 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
```
## 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)
### 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 (need 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