cli: correct fs help and learn.md

crates/cli/src/cli.rs

@@ -1934,7 +1934,7 @@ pub enum FsCommand {
     /// --json, emits one NDJSON event per record (`upsert`, `delete`,
     /// `move`, plus `reset`/`sync` staging markers and `synced`/`closed`).
     Sync {
-        /// Path on the server (absolute, or relative to the server's cwd)
+        /// Path on the server (absolute, or relative to the client's cwd)
         path: String,
 
         /// Sync file contents too (hashes always sync)
@@ -2142,12 +2142,13 @@ pub enum FsCommand {
         #[arg(short = 'w', long)]
         word: bool,
 
-        /// Search gitignored files too; they rank after tracked ones.
-        /// Much slower on a tree with build output.
+        /// Search gitignored files and `.git` too. Results stay in path
+        /// order; ignored files are marked in --json. Much slower on a tree
+        /// with build output.
         #[arg(long)]
         no_ignore: bool,
 
-        /// Stop after this many matching files (0 = server default)
+        /// Stop after this many matching files (0 = no limit)
         #[arg(short = 'm', long, default_value_t = 0)]
         max_matches: u16,
 
@@ -2198,7 +2199,7 @@ pub enum FsCommand {
 pub enum GitCommand {
     /// Branch, ahead/behind, stash, and working-tree status
     Status {
-        /// Repository location on the server (default: server cwd)
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2228,7 +2229,7 @@ pub enum GitCommand {
         #[arg(last = true)]
         pathspec: Vec<String>,
 
-        /// Repository location on the server (default: server cwd)
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2284,7 +2285,7 @@ pub enum GitCommand {
         #[arg(last = true)]
         pathspec: Vec<String>,
 
-        /// Repository location on the server (default: server cwd)
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2318,12 +2319,15 @@ pub enum GitCommand {
     ///   yas git show HEAD:src/main.rs   # a file at a revision
     ///   yas git show v1.0:Cargo.toml
     ///   yas git show HEAD               # the commit object itself
+    ///   yas git show HEAD:src           # a directory, listed like ls-tree
     Show {
-        /// REV[:PATH]. Omit PATH for the commit object; omit REV
-        /// (`:path`) for HEAD.
+        /// REV[:PATH]. REV names a commit; reach trees and blobs by PATH.
+        /// Omit PATH for the commit object (in `git cat-file commit`
+        /// layout); a directory PATH is listed like ls-tree, and `REV:`
+        /// lists the root tree. Omit REV (`:path`) for HEAD.
         spec: String,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2340,7 +2344,7 @@ pub enum GitCommand {
         /// REV[:PATH]; omit PATH for the root tree
         spec: String,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2358,7 +2362,7 @@ pub enum GitCommand {
         #[arg(default_value = "")]
         path: String,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2375,7 +2379,7 @@ pub enum GitCommand {
         #[arg(required = true, num_args = 2..)]
         revs: Vec<String>,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2393,7 +2397,7 @@ pub enum GitCommand {
         /// File to blame
         path: String,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2428,7 +2432,7 @@ pub enum GitCommand {
         #[arg(default_value = "")]
         ref_name: String,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2450,7 +2454,7 @@ pub enum GitCommand {
     /// TSV: WORKDIR<TAB>GITDIR. Deduped by gitdir, so several paths
     /// resolving to one repository report once.
     Discover {
-        /// Directory to search (default: server cwd)
+        /// Directory to search (relative to the client's cwd)
         #[arg(default_value = ".")]
         path: String,
 
@@ -2484,7 +2488,7 @@ pub enum GitCommand {
         /// Refspecs to fetch (default: the remote's configured ones)
         refspecs: Vec<String>,
 
-        /// Repository path on the server
+        /// Repository path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         repo: String,
 
@@ -2599,7 +2603,7 @@ pub enum LspCommand {
         /// Position, 1-based (e.g. src/main.rs:10:4)
         spec: String,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2617,7 +2621,7 @@ pub enum LspCommand {
         #[arg(long)]
         declaration: bool,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2631,7 +2635,7 @@ pub enum LspCommand {
         /// Position, 1-based (e.g. src/main.rs:10:4)
         spec: String,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2648,7 +2652,7 @@ pub enum LspCommand {
         /// Position, 1-based (e.g. src/main.rs:10:4)
         spec: String,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2665,7 +2669,7 @@ pub enum LspCommand {
         /// Position, 1-based (e.g. src/main.rs:10:4)
         spec: String,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2684,7 +2688,7 @@ pub enum LspCommand {
         #[arg(long)]
         file: Option<String>,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2705,11 +2709,12 @@ pub enum LspCommand {
         #[arg(long)]
         watch: bool,
 
-        /// Wait for language servers to finish indexing first
+        /// Wait for language servers to finish indexing, then for the next
+        /// published diagnostics (or 5 seconds without any server update)
         #[arg(long)]
         wait: bool,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2727,7 +2732,7 @@ pub enum LspCommand {
         /// The new name
         new_name: String,
 
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 
@@ -2738,7 +2743,7 @@ pub enum LspCommand {
 
     /// Block until the workspace's language servers are ready
     Wait {
-        /// Workspace location on the server (default: server cwd)
+        /// Workspace path on the server (relative to the client's cwd)
         #[arg(long, default_value = ".")]
         root: String,
 

crates/cli/src/learn.md

@@ -268,13 +268,15 @@ yas fs grep needle                      # search contents, PATH:LINE:TEXT
 yas fs grep -e 'fn \w+' --root crates   # regex
 yas fs grep -sw Config                  # case-sensitive, whole word
 yas fs grep -l needle                   # matching paths only
+yas fs grep -m 3 needle                 # stop after three matching files
 yas fs grep --no-ignore TODO            # include gitignored files
 yas fs sync . --json                    # mirror a tree, stream changes
 ```
 
-`fs grep` is case-insensitive literal by default and honours `.gitignore`,
-which is what keeps it fast on a tree with build output — `--no-ignore`
-searches ignored files too and ranks them last. It exits 1 when nothing
+`fs grep` is case-insensitive literal by default, honours `.gitignore`, and
+skips `.git`, which is what keeps it fast on a tree with build output. Dotfiles
+are searched. `--no-ignore` searches ignored files and `.git` too; results
+stay in path order, with ignored files marked `"ignored": true` in `--json`. It exits 1 when nothing
 matched, like grep(1), so `if yas fs grep -l TODO; then …` works.
 
 Writes are compare-and-swap by default, so a concurrent change is a
@@ -284,16 +286,17 @@ conflict rather than a silent clobber (exit 1):
 echo hi | yas fs write notes.txt              # unconditional overwrite
 echo hi | yas fs write notes.txt --create     # fail if it exists
 echo hi | yas fs write notes.txt --if-hash H  # only if unchanged
-yas fs mkdir -p a/b        # create a directory
+yas fs mkdir --parents a/b # create a directory and its parents
 yas fs mv old new          # rename or move
-yas fs rm -r dir           # remove a subtree
+yas fs rm dir              # remove a file or a whole subtree
 yas fs ln -s target link   # symlink (omit -s for a hard link)
 ```
 
 ## Git
 
 Read-only introspection of repositories on the server. `--repo` picks the
-worktree (default: cwd); `--json` emits NDJSON.
+worktree; a relative path, and the default `.`, resolve against the client's
+cwd, as `--root` does for `fs` and `lsp`. `--json` emits NDJSON.
 
 ```bash
 yas git status                     # branch, ahead/behind, stash, worktree
@@ -302,14 +305,15 @@ yas git log                        # history, newest first
 yas git log v1.0                   # from a tag
 yas git log main..feature          # a range
 yas git log --follow -- src/main.rs
-yas git diff                       # unstaged
+yas git diff                       # unstaged (-p for hunks)
 yas git diff --staged              # staged
 yas git diff main dev              # between two commits
 yas git diff main...dev            # since they diverged (from the merge base)
 yas git diff --merge-base main     # worktree vs where main forked (a `base` line names it)
 yas git diff HEAD~2 -p -- src      # with hunks, limited to a path
 yas git show HEAD:src/main.rs      # a file's bytes at a revision
 yas git show HEAD                  # the commit object itself
+yas git show HEAD:src              # a directory, listed like ls-tree
 yas git ls-tree HEAD                # one tree level (MODE TYPE OID<TAB>NAME)
 yas git ls-tree HEAD:src            # descend by passing a path
 yas git merge-base main feature     # best common ancestors (exit 1 if unrelated)
@@ -335,12 +339,13 @@ having refused one refspec of several).
 Language servers (rust-analyzer, gopls, clangd, …) are discovered by
 project markers, spawned on the server, and stay warm across
 invocations. Positions are 1-based PATH:LINE:COL; all commands take
-`--root` (default: server cwd) and `--json` (NDJSON).
+`--root` (default: the client's cwd; relative paths resolve against it) and
+`--json` (NDJSON).
 
 ```bash
 yas lsp wait                        # block until servers finish indexing
 yas lsp diag                        # current diagnostics (exit 1 if any)
-yas lsp diag --wait                 # settle first — use after editing files
+yas lsp diag --wait                 # wait for the next publish — use after editing files
 yas lsp def src/main.rs:10:4        # definition of the symbol at 10:4
 yas lsp refs src/main.rs:10:4       # references (--declaration to include it)
 yas lsp hover src/main.rs:10:4      # type and docs
@@ -352,9 +357,11 @@ yas lsp rename src/main.rs:10:4 nm  # rename plan (prints edits, never applies)
 yas lsp list                        # running servers (ref, phase, memory)
 ```
 
-A first call in a fresh workspace may exit 2 with "warming up" — run
+A first call in a fresh workspace may exit 2 with `Busy: Warming` — run
 `yas lsp wait` once, then query. The edit loop: change files, then
-`yas lsp diag --wait` to see resulting errors.
+`yas lsp diag --wait` to see resulting errors. `--wait` waits for indexing,
+then for the next published diagnostics, or 5 seconds without any server
+update when nothing changes.
 
 ## Key/value store