From 27bafd44ca12a6a526af6fc2f3a3e812a087c15f Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Fri, 25 Sep 2026 11:55:28 -0700 Subject: [PATCH] docs: correct -c framing for atomic diff, document --json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `atomic diff -c` was described as "compare against a specific change", which reads as a comparison target. It is a selector: the command answers two different questions depending on whether it is present — working copy vs. recorded state, or the state before vs. after a change. Agents were following the misleading phrasing. Also document --json (added in atomic#218), which takes precedence over the text format selectors, and note that a clean working copy now surfaces copy-pasteable -c commands rather than dead-ending. Append a trailing newline to code-intelligence/SKILL.md so the mirror stays byte-identical to the materialized working copy; the missing newline was the only diff between the two. --- skills/atomic-vcs/SKILL.md | 16 ++++++++++++++-- skills/code-intelligence/SKILL.md | 2 +- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/skills/atomic-vcs/SKILL.md b/skills/atomic-vcs/SKILL.md index 995ae14..a6a7ca6 100644 --- a/skills/atomic-vcs/SKILL.md +++ b/skills/atomic-vcs/SKILL.md @@ -119,19 +119,31 @@ depends on, who/what authored it, what it cost, and the reasoning that produced ## `atomic diff` — precise edits +`-c` **selects which change to show** — it is not a comparison target. The two modes +answer different questions: + ```bash atomic diff # working copy vs. recorded state, all modified tracked files atomic diff src/auth.rs # one or more specific files -atomic diff -c R4YQ # compare against a specific change +atomic diff -c R4YQ # what did change R4YQ do? (state before vs. after it) atomic diff --stat # summary: files + line counts atomic diff --name-only # just the changed paths atomic diff --name-status # paths with M/A/D indicators +atomic diff --json # versioned JSON: per-file hunks, typed lines, rollups atomic diff --untracked # include untracked files -atomic diff --view dev # compare against another view +atomic diff --view dev # working-copy comparison against another view atomic diff --word-diff # token-level highlighting (CRDT-powered) atomic diff --algorithm patience # better for moved blocks (default: myers) ``` +A clean working copy is not a dead end: `atomic diff` names real, copy-pasteable +`-c` commands for the most recent changes on the current view. Follow one. + +`--json` takes precedence over `--stat`/`--name-only`/`--name-status`, so a consumer +always gets one parseable document. A `-c` diff carries the change header under +`change` (hash, message, authors, date); a working-copy diff carries `view` instead. +A diff with nothing to show still emits valid JSON with an empty `files` array. + `--word-diff` is special to Atomic: it shows exactly which **tokens** changed within a line, not just that the line changed. Reach for it during code review when a line was edited subtly. diff --git a/skills/code-intelligence/SKILL.md b/skills/code-intelligence/SKILL.md index 65c07cc..961e315 100644 --- a/skills/code-intelligence/SKILL.md +++ b/skills/code-intelligence/SKILL.md @@ -129,4 +129,4 @@ This extracts file nodes, change history, and tree-sitter entities into the KG. - Chain: code → search → neighbors → entities → read_file. Each step narrows your focus. - The content index and KG are built by `atomic vault query enrich` — run it if results seem sparse - Node IDs are exact strings — a single wrong character means "not found" -- Use `--json` on any command when you need structured output for further processing \ No newline at end of file +- Use `--json` on any command when you need structured output for further processing