glassbox 0.12.0-beta.1 → 0.12.0-beta.2

package/README.md

@@ -268,6 +268,8 @@ Create `.glassbox/settings.json` in your project directory to configure per-proj
 
 Glassbox installs a companion binary, `glassbox-difftool`, that lets you register it as your `git difftool` so `git difftool --dir-diff <refA> <refB>` opens the diff in Glassbox automatically.
 
+> Both binaries (`glassbox` + `glassbox-difftool`) are installed onto PATH together — `npm install -g glassbox` ships both via the `bin` map; the desktop app's **Install CLI** affordance symlinks both. If `glassbox` is on PATH but `glassbox-difftool` isn't (e.g. a pre-0.12 desktop install), re-run "Install CLI" from **Settings → General** to add the missing symlink.
+
 The easiest way to register it is to let the CLI do it for you:
 
 ```bash
@@ -282,19 +284,24 @@ If you'd rather wire it up by hand, the equivalent config is:
 
 ```bash
 git config --global diff.tool glassbox
-git config --global difftool.glassbox.cmd 'glassbox-difftool "$LOCAL" "$REMOTE"'
+git config --global difftool.glassbox.cmd 'glassbox-difftool "$LOCAL" "$REMOTE" "$MERGED"'
 git config --global difftool.prompt false
 ```
 
-Then:
+Then either:
 
 ```bash
-git difftool --dir-diff HEAD~1 HEAD
+git difftool --dir-diff HEAD~1 HEAD   # whole change set in one review (recommended)
+git difftool HEAD~1 HEAD              # step through changed files one at a time
 ```
 
-**Use `--dir-diff`, not the per-file mode.** Glassbox is a session-based reviewer; the per-file mode would launch a separate Glassbox instance for each changed file (and collide on the instance lock). `--dir-diff` invokes Glassbox once with both snapshots.
+**Both modes open the whole change set as a single review.** With `--dir-diff`, git hands Glassbox both snapshot directories at once. **Per-file mode** (without `--dir-diff`) gets you the same single-session result: git invokes `glassbox-difftool` once per changed file, and the wrapper forwards each file to one long-lived Glassbox server, so every file accumulates into **one** review rather than one tab per file. git steps through the files with **no Ctrl-C between them**, and the sidebar grows live as each arrives. Each file is labeled with its repo-relative path.
+
+When you're finished, click **Done** in the review (a difftool session shows this instead of the normal completion flow) — the `git difftool` command returns to your prompt cleanly, no Ctrl-C needed. Closing the browser tab ends the session too.
+
+**Desktop vs browser:** in a browser (npm) install the accumulating model above applies. If the desktop app is installed, `--dir-diff` opens the whole change set in one Glassbox window (matching what `glassbox --commit` does from the same folder) on macOS, Linux, and Windows; desktop per-file mode currently opens one window per file, so `--dir-diff` is the recommended desktop invocation.
 
-**Under the hood:** `git difftool --dir-diff` materializes its two snapshot directories asymmetrically — the right side is symlinks pointing into your working tree, which trips up plain `git diff --no-index`. `glassbox-difftool` dereferences those symlinks into a temp tree before handing the dirs to `glassbox --diff`, then cleans up on exit. Without the wrapper you'd see every modified file show up as a "deleted + added" pair instead of a modified entry.
+**Under the hood:** `git difftool --dir-diff` materializes its two snapshot directories asymmetrically — the right side is symlinks pointing into your working tree, which trips up plain `git diff --no-index`. `glassbox-difftool` dereferences those symlinks into a temp tree before handing the dirs to `glassbox --diff`, then cleans up when the session ends. In per-file mode the wrapper reads each file's content before it returns (git deletes the temp files the instant the tool exits) and POSTs it to the accumulating server; the last file holds the connection open so `git difftool` stays attached until you click Done. Without the wrapper you'd see every modified file show up as a "deleted + added" pair instead of a modified entry, and per-file mode would hang waiting for a manual Ctrl-C between files.
 
 **Alternative: skip git difftool entirely.** Glassbox's native ref-aware modes already cover the workflows `git difftool` is for and produce cleaner diffs (real `git diff`, not `--no-index`):