cssgrep 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-07-02
+
+### Added
+- `-S`/`--follow` to follow symbolic links while recursing with `-r`
+  (skipped by default). Cycle-safe: each physical directory is visited once.
+
+### Fixed
+- Large result sets are no longer truncated when stdout is a pipe (the process
+  exited before async pipe writes had flushed).
+- Columns (`-n`, `-A`/`-B`/`-C`, `--json`) now count bytes — what vim's
+  `grepformat %c` expects — instead of UTF-16 code units, so non-ASCII text
+  before a match no longer skews the locator.
+- A value-taking option with no value (e.g. a trailing `--ignore` or `--attr`)
+  now fails cleanly with exit 2 instead of crashing or being silently ignored.
+- `**/` in globs stops at path-segment boundaries: `--include '**/foo.html'`
+  no longer matches `barfoo.html`.
+- `--attr` matches attribute names case-insensitively (the parser lowercases
+  them), and exits 1 when every match was skipped for lacking the attribute.
+- `-w`/`--max-width` no longer cuts an astral character in half.
+- Binary detection now also applies to standard input.
+- Slash-containing globs (e.g. `--include 'src/*.html'`) now match on Windows:
+  paths are normalized to `/` separators before glob matching.
+- Recursive walks visit directory entries in sorted order, so output order is
+  deterministic across platforms.
+
+### Changed
+- Bare `--color` now means `auto`, matching GNU grep (was `always`).
+- `-c` prints zero counts (`file:0`, or a lone `0` for a single input),
+  matching grep.
+
 ## [1.1.0] - 2026-07-02
 
 ### Added
@@ -34,6 +64,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `-0`/`--null`, `--color`, `-w`/`--max-width`, `-V`/`--version`.
 - Standalone binaries (Bun, Node SEA), shell completions, and a man page.
 
-[Unreleased]: https://github.com/msbatarce/cssgrep/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/msbatarce/cssgrep/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/msbatarce/cssgrep/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/msbatarce/cssgrep/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/msbatarce/cssgrep/releases/tag/v1.0.0

package/README.md

@@ -83,9 +83,10 @@ locator appears only with `-n`:
 | `-i`, `--ignore <glob>` | Skip files/dirs matching `<glob>` while recursing (repeatable). `node_modules`, `*.min.html`, `build/` (dir-only), or path globs like `src/vendor/**`. |
 | `--exclude <glob>` | Alias for `--ignore` (grep's name for the same thing). |
 | `--ignore-file <path>` | Load ignore globs from a file, one per line (`#` comments and blank lines ignored) — like a `.gitignore`. |
+| `-S`, `--follow` | Follow symbolic links while recursing with `-r` (they are skipped by default). Each physical directory is visited once, so symlink cycles are safe. |
 | `-n`, `--line-number` | Prefix each match with its `line:col` locator. Mutually exclusive with `-c` and `-p`. |
 | `-p`, `--print` | Pretty-print the matched node's HTML, re-indented from scratch (works on minified input). No `line:col` locator is shown. |
-| `--attr <name>` | Print the value of attribute `<name>` for each match (nodes without it are skipped). Honors `-n` and `-w`. |
+| `--attr <name>` | Print the value of attribute `<name>` for each match (nodes without it are skipped; if every match is skipped the exit status is 1). The name is matched case-insensitively. Honors `-n` and `-w`. |
 | `--text` | Print the matched node's text content, whitespace collapsed. Honors `-n` and `-w`. |
 | `--json` | Print one JSON object per match (NDJSON), with `file`, `line`, `col`, `html`, `text`. |
 | `--parent <n>` | Report the `n`-th element ancestor of each match instead of the match itself (de-duplicated). Pairs well with `-p`. |
@@ -94,8 +95,8 @@ locator appears only with `-n`:
 | `-B`, `--before-context <n>` | Print `n` source lines before each match. |
 | `-C`, `--context <n>` | Print `n` source lines before and after each match. |
 | `-m`, `--max-count <n>` | Stop after `n` matches per file (caps `-c` too). |
-| `-M`, `--max-total <n>` | Stop after `n` matches in total across all files. |
-| `-c`, `--count` | Print only the match count (per file when relevant). |
+| `-M`, `--max-total <n>` | Stop after `n` matches in total across all files. The budget counts matches, not files — combined with `-l`/`-L`, scanning stops once `n` matches have been seen, which can cut the file list short. |
+| `-c`, `--count` | Print only the match count (per file when relevant, zeros included — `file:0`, like grep). |
 | `-l`, `--files-with-matches` | Print only the names of files that contain a match. |
 | `-L`, `--files-without-match` | Print only the names of files with no match. |
 | `-q`, `--quiet` | Print nothing; exit `0` on the first match, `1` if none. Stops early. |
@@ -103,7 +104,7 @@ locator appears only with `-n`:
 | `-0`, `--null` | Output a NUL after each file name instead of `:` (or, with `-l`/`-L`, instead of the newline) — pipe to `xargs -0`. |
 | `-H`, `--with-filename` | Always print the `file:` prefix, even for a single file or stdin. |
 | `--no-filename` | Never print the `file:` prefix, even when searching multiple files. |
-| `--color[=<when>]` | Colorize output: `auto` (default — color only when stdout is a terminal), `always`, or `never`. A bare `--color` means `always`. |
+| `--color[=<when>]` | Colorize output: `auto` (default — color only when stdout is a terminal), `always`, or `never`. A bare `--color` means `auto`, like grep; use `--color=always` to force color into pipes. |
 | `-h`, `--help` | Show help. |
 | `-V`, `--version` | Print the version and exit. |
 
@@ -115,7 +116,7 @@ segment), `**` (across `/`), `?` (one non-slash char), and brace alternation
 like `*.{html,htm}`. A trailing `/` matches directories only; a pattern with a
 `/` matches against the path, otherwise the basename — gitignore-flavored.
 
-Binary files are detected (a NUL byte or a high ratio of control bytes in the
+Binary input is detected (a NUL byte or a high ratio of control bytes in the
 first 8 KB) and skipped with a note on stderr — parsing them as HTML is never
 useful. Suppress the note with `-s` (or `-q`).
 
@@ -206,4 +207,6 @@ a flag.)
 - [`css-select`](https://github.com/fb55/css-select) matches the selector
   against that DOM (the same engine cheerio uses).
 - Offsets are converted to 1-based `line:col` via a precomputed line index;
-  `col` points at the opening `<` of the matched tag.
+  `col` points at the opening `<` of the matched tag and counts *bytes* — what
+  vim's `grepformat` `%c` expects — so multibyte UTF-8 text earlier on the line
+  doesn't skew the cursor.

package/completions/_cssgrep

@@ -12,6 +12,7 @@ _cssgrep() {
     '*'{-i,--ignore}'[skip files/dirs matching glob while recursing]:glob:' \
     '*--exclude[alias for --ignore]:glob:' \
     '--ignore-file[read ignore globs from a file]:file:_files' \
+    '(-S --follow)'{-S,--follow}'[follow symbolic links while recursing]' \
     '(-n --line-number)'{-n,--line-number}'[prefix each match with line:col]' \
     '(-p --print)'{-p,--print}'[pretty-print the matched node HTML]' \
     '--attr[print the value of an attribute]:attribute name:' \

package/completions/cssgrep.bash

@@ -6,7 +6,7 @@ _cssgrep() {
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-    opts="-r --recursive --max-depth --ext --include -i --ignore --exclude --ignore-file -n --line-number \
+    opts="-r --recursive --max-depth --ext --include -i --ignore --exclude --ignore-file -S --follow -n --line-number \
 -p --print --attr --text --json --parent -w --max-width \
 -A --after-context -B --before-context -C --context \
 -m --max-count -M --max-total -c --count \

package/completions/cssgrep.fish

@@ -8,6 +8,7 @@ complete -c cssgrep -l include -x -d 'Only search files matching glob (replaces
 complete -c cssgrep -s i -l ignore -x -d 'Skip files/dirs matching glob while recursing'
 complete -c cssgrep -l exclude -x -d 'Alias for --ignore'
 complete -c cssgrep -l ignore-file -r -F -d 'Read ignore globs from a file'
+complete -c cssgrep -s S -l follow -d 'Follow symbolic links while recursing'
 complete -c cssgrep -s n -l line-number -d 'Prefix each match with line:col'
 complete -c cssgrep -s p -l print -d 'Pretty-print the matched node HTML'
 complete -c cssgrep -l attr -x -d 'Print the value of an attribute'

package/index.js

@@ -12,7 +12,7 @@ const { html: beautify } = require('js-beautify');
 // package.json, so it survives compilation into a standalone binary (Bun
 // --compile / Node SEA), where package.json won't sit next to the executable.
 // Keep in sync with package.json on release.
-const VERSION = '1.1.0';
+const VERSION = '1.2.0';
 
 const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
 
@@ -35,6 +35,8 @@ Options:
   -i, --ignore <glob>    Skip files/dirs matching <glob> when recursing (repeatable).
       --exclude <glob>   Alias for --ignore.
       --ignore-file <path>   Read ignore globs from <path> (one per line, # comments).
+  -S, --follow           Follow symbolic links when recursing with -r
+                         (default: skip them; loops are detected).
   -n, --line-number      Prefix each match with its line:col (excludes -c, -p).
   -p, --print            Pretty-print the matched node's HTML above its location.
       --attr <name>      Print the value of attribute <name> (skips nodes without it).
@@ -47,7 +49,8 @@ Options:
   -C, --context <n>          Print <n> source lines before and after each match.
   -m, --max-count <n>    Stop after <n> matches per file.
   -M, --max-total <n>    Stop after <n> matches in total (across all files).
-  -c, --count            Print only a count of matches (per file when relevant).
+  -c, --count            Print only a count of matches (per file when
+                         relevant, zeros included, like grep).
   -l, --files-with-matches   Print only the names of files that have a match.
   -L, --files-without-match  Print only the names of files with no match.
   -q, --quiet            Print nothing; exit 0 on first match, 1 if none.
@@ -55,7 +58,8 @@ Options:
   -0, --null             Separate the file name with a NUL byte (for xargs -0).
   -H, --with-filename    Always print the file name prefix (even for one file).
       --no-filename      Never print the file name prefix (even for many files).
-      --color[=<when>]   Colorize output: auto (default), always or never.
+      --color[=<when>]   Colorize output: auto (default, also what a bare
+                         --color means, like grep), always or never.
   -h, --help             Show this help.
   -V, --version          Show version and exit.
 
@@ -92,6 +96,7 @@ function parseArgs(argv) {
     positionals: [],
     paths: [],
     recursive: false,
+    follow: false,
     exts: ['html', 'htm'],
     extGiven: false,
     maxDepth: 0,
@@ -153,16 +158,22 @@ function parseArgs(argv) {
     const a = argv[i];
 
     // Long options: --name or --name=value. A missing inline value is taken
-    // from the next argument (except --color, where a bare flag means "always").
+    // from the next argument (except --color, where a bare flag means "auto",
+    // as in GNU grep).
     if (a.startsWith('--') && a.length > 2) {
       const eq = a.indexOf('=');
       const name = eq === -1 ? a : a.slice(0, eq);
       const inline = eq === -1 ? null : a.slice(eq + 1);
-      const value = () => (inline != null ? inline : argv[++i]);
+      const value = () => {
+        if (inline != null) return inline;
+        if (i + 1 >= argv.length) fail(`option ${name} requires a value`);
+        return argv[++i];
+      };
       switch (name) {
         case '--help': process.stdout.write(USAGE + '\n'); process.exit(0); break;
         case '--version': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
         case '--recursive': opts.recursive = true; break;
+        case '--follow': opts.follow = true; break;
         case '--line-number': opts.lineNumber = true; break;
         case '--print': opts.print = true; break;
         case '--count': opts.count = true; break;
@@ -181,14 +192,15 @@ function parseArgs(argv) {
         case '--max-count': setMaxCount(value()); break;
         case '--max-total': setMaxTotal(value()); break;
         case '--max-depth': setMaxDepth(value()); break;
-        case '--attr': opts.attr = value(); break;
+        // htmlparser2 lowercases HTML attribute names, so match case-insensitively.
+        case '--attr': opts.attr = value().toLowerCase(); break;
         case '--text': opts.text = true; break;
         case '--json': opts.json = true; break;
         case '--parent': setParent(value()); break;
         case '--after-context': setAfter(value()); break;
         case '--before-context': setBefore(value()); break;
         case '--context': setContext(value()); break;
-        case '--color': case '--colour': opts.color = inline != null ? inline : 'always'; break;
+        case '--color': case '--colour': opts.color = inline != null ? inline : 'auto'; break;
         default: fail(`unknown option: ${name}`);
       }
       continue;
@@ -202,6 +214,7 @@ function parseArgs(argv) {
         const ch = a[j];
         if (shortValueFlags[ch]) {
           const rest = a.slice(j + 1);          // attached value, if any
+          if (rest === '' && i + 1 >= argv.length) fail(`option -${ch} requires a value`);
           shortValueFlags[ch](rest !== '' ? rest : argv[++i]);
           break;                                // value swallowed the cluster tail
         }
@@ -209,6 +222,7 @@ function parseArgs(argv) {
           case 'h': process.stdout.write(USAGE + '\n'); process.exit(0); break;
           case 'V': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
           case 'r': opts.recursive = true; break;
+          case 'S': opts.follow = true; break;
           case 'n': opts.lineNumber = true; break;
           case 'p': opts.print = true; break;
           case 'c': opts.count = true; break;
@@ -309,7 +323,12 @@ function offsetToPosition(starts, src, offset) {
   if (text.endsWith('\r')) text = text.slice(0, -1);
   return {
     line: lo + 1,            // 1-based
+    // col in UTF-16 code units: a JS string index into `text`, used by the
+    // highlight math. bcol in bytes: what gets printed — vim's grepformat %c
+    // and terminals count bytes, so non-ASCII text before the match would
+    // otherwise land the cursor short.
     col: offset - lineStart + 1, // 1-based
+    bcol: Buffer.byteLength(src.slice(lineStart, offset), 'utf8') + 1, // 1-based
     text,
   };
 }
@@ -325,10 +344,18 @@ function lineTextAt(starts, src, lineNo) {
   return { lineStart, text };
 }
 
+// Never cut between the halves of a surrogate pair: a lone half is invalid
+// Unicode and serializes as U+FFFD garbage. Backing off one unit loses at most
+// one display column.
+function safeCut(text, at) {
+  const c = text.charCodeAt(at - 1);
+  return c >= 0xd800 && c <= 0xdbff ? at - 1 : at;
+}
+
 function truncate(text, maxWidth) {
   if (!maxWidth || text.length <= maxWidth) return text;
-  if (maxWidth <= 1) return text.slice(0, maxWidth);
-  return text.slice(0, maxWidth - 1) + '…'; // …
+  if (maxWidth <= 1) return text.slice(0, safeCut(text, maxWidth));
+  return text.slice(0, safeCut(text, maxWidth - 1)) + '…'; // …
 }
 
 // Produce the visible match text: truncate first (so --max-width still measures
@@ -507,7 +534,7 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
       if (label) prefix += c(COLORS.file, label) + (opts.nul ? '\0' : sepColored);
       if (opts.lineNumber) {
         prefix += c(COLORS.line, String(L));
-        prefix += m ? c(COLORS.sep, ':') + c(COLORS.line, String(m.pos.col)) + ' '
+        prefix += m ? c(COLORS.sep, ':') + c(COLORS.line, String(m.pos.bcol)) + ' '
                     : c(COLORS.sep, '-');
       }
       const body = m
@@ -539,10 +566,11 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   const cap = Math.min(opts.maxCount || Infinity, limit);
   const limited = Number.isFinite(cap) ? matches.slice(0, cap) : matches;
   if (opts.count) {
-    if (limited.length) {
-      const fileSep = opts.nul ? '\0' : ':';
-      out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
-    }
+    // grep parity: every searched file reports a count, zeros included, so
+    // scripts get one row per file (exit status still says whether anything
+    // matched at all).
+    const fileSep = opts.nul ? '\0' : ':';
+    out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
     return limited.length;
   }
   const starts = opts.print ? null : lineIndex(src);
@@ -563,6 +591,10 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     emitContext(src, starts, name, showLabel, targets, opts, out);
     return limited.length;
   }
+  // From here on the return value is the number of *emitted* records (which is
+  // what the -M budget and the exit status should count): --attr can skip
+  // matches lacking the attribute, and --parent dedup can merge several
+  // matches into one printed ancestor.
   if (opts.json) {
     // NDJSON: one self-contained record per match. `html` is the exact source
     // slice; newlines are escaped by JSON.stringify, so each record stays on
@@ -574,18 +606,20 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
       out.push(JSON.stringify({
         file: name,
         line: pos.line,
-        col: pos.col,
+        col: pos.bcol,
         html: src.slice(off, nodeEnd),
         text: collapseWs(textOf(el)),
       }));
     }
-    return limited.length;
+    return targets.length;
   }
+  let emitted = 0;
   for (const el of targets) {
     if (opts.print) {
       // -p shows the re-indented node only; no line:col locator. With --parent,
       // the original matched descendants are highlighted inside the container.
       out.push(prettyPrint(el, originsByTarget.get(el), opts), ''); // blank separator
+      emitted++;
       continue;
     }
     const off = el.startIndex == null ? 0 : el.startIndex;
@@ -615,11 +649,12 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     let prefix = '';
     if (label) prefix += c(COLORS.file, label) + fileSep;
     if (opts.lineNumber) {
-      prefix += c(COLORS.line, String(pos.line)) + sep + c(COLORS.line, String(pos.col)) + ' ';
+      prefix += c(COLORS.line, String(pos.line)) + sep + c(COLORS.line, String(pos.bcol)) + ' ';
     }
     out.push(prefix + text);
+    emitted++;
   }
-  return limited.length;
+  return emitted;
 }
 
 // Translate a glob to a regex body. `*` matches within a path segment, `**`
@@ -632,9 +667,15 @@ function globToRegex(glob) {
     const c = glob[i];
     if (c === '*') {
       if (glob[i + 1] === '*') {            // **  (crosses /)
-        re += '.*';
         i++;
-        if (glob[i + 1] === '/') i++;       // consume the slash in **/
+        if (glob[i + 1] === '/') {
+          // `**/` spans whole segments (or none): `**/foo` matches `foo` and
+          // `a/b/foo`, but not `barfoo` — the `.*` must end at a `/`.
+          re += '(?:.*/)?';
+          i++;
+        } else {
+          re += '.*';
+        }
       } else {
         re += '[^/]*';
       }
@@ -672,16 +713,25 @@ function compileIgnore(pattern) {
 }
 
 // True if name/path matches any compiled glob matcher (shared by --ignore/
-// --exclude and --include).
+// --exclude and --include). Globs always use `/` as the separator (gitignore
+// semantics), so normalize Windows backslash paths before matching.
 function matchesAny(name, full, isDir, matchers) {
+  const fullPosix = path.sep === '/' ? full : full.split(path.sep).join('/');
   for (const m of matchers) {
     if (m.dirOnly && !isDir) continue;
-    if (m.re.test(m.hasSlash ? full : name)) return true;
+    if (m.re.test(m.hasSlash ? fullPosix : name)) return true;
   }
   return false;
 }
 
-function* walk(dir, opts, depth = 1) {
+// `visited` (only with -S/--follow) holds the realpath of every directory
+// already entered, so symlink cycles — and two links to the same physical
+// directory — are traversed once. Without --follow, symlinks are skipped.
+function* walk(dir, opts, depth = 1, visited = null) {
+  if (opts.follow && visited === null) {
+    visited = new Set();
+    try { visited.add(fs.realpathSync(dir)); } catch (e) { /* walked anyway */ }
+  }
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -689,14 +739,30 @@ function* walk(dir, opts, depth = 1) {
     if (!opts.noMessages) process.stderr.write(`cssgrep: ${dir}: ${e.code || e.message}\n`);
     return;
   }
+  // readdir order is filesystem-dependent; sort so output order (and therefore
+  // -M/-m truncation points) is stable across platforms.
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   for (const e of entries) {
     const full = path.join(dir, e.name);
-    const isDir = e.isDirectory();
+    let isDir = e.isDirectory();
+    let isFile = e.isFile();
+    if (opts.follow && e.isSymbolicLink()) {
+      const st = fs.statSync(full, { throwIfNoEntry: false }); // resolves the link
+      if (!st) continue;                                       // broken link
+      isDir = st.isDirectory();
+      isFile = st.isFile();
+    }
     if (opts.ignore.length && matchesAny(e.name, full, isDir, opts.ignore)) continue;
     if (isDir) {
+      if (opts.follow) {
+        let real;
+        try { real = fs.realpathSync(full); } catch (err) { continue; }
+        if (visited.has(real)) continue;    // cycle or already-walked dir
+        visited.add(real);
+      }
       // --max-depth caps how far we descend; depth 1 = the target's children.
-      if (!opts.maxDepth || depth < opts.maxDepth) yield* walk(full, opts, depth + 1);
-    } else if (e.isFile()) {
+      if (!opts.maxDepth || depth < opts.maxDepth) yield* walk(full, opts, depth + 1, visited);
+    } else if (isFile) {
       // --include replaces the extension filter; otherwise filter by --ext.
       if (opts.include.length) {
         if (matchesAny(e.name, full, false, opts.include)) yield full;
@@ -709,7 +775,7 @@ function* walk(dir, opts, depth = 1) {
 }
 
 function readStdin() {
-  return fs.readFileSync(0, 'utf8');
+  return fs.readFileSync(0); // Buffer: sniffed for binary before decoding
 }
 
 // Heuristic binary-file detector (grep/git style). A NUL byte in the first 8 KB
@@ -765,7 +831,14 @@ function main() {
 
   try {
     if (useStdin) {
-      total += searchSource(readStdin(), '(standard input)', showLabel, opts, out, room());
+      const buf = readStdin();
+      if (looksBinary(buf)) {
+        if (!opts.noMessages && !opts.quiet) {
+          process.stderr.write('cssgrep: (standard input): binary input (skipped)\n');
+        }
+      } else {
+        total += searchSource(buf.toString('utf8'), '(standard input)', showLabel, opts, out, room());
+      }
     } else {
       for (const f of files) {
         if (room() <= 0) break;               // -M: global budget exhausted
@@ -805,8 +878,11 @@ function main() {
   }
   // Normally success means "a match was found". With -L it means "a file
   // without a match was printed", which is decoupled from the match total.
+  // Set exitCode rather than calling process.exit(): stdout writes to a pipe
+  // are async, and exit() would drop whatever hasn't flushed yet, truncating
+  // large result sets mid-stream.
   const success = opts.filesWithoutMatch ? out.length > 0 : total > 0;
-  process.exit(success ? 0 : 1);
+  process.exitCode = success ? 0 : 1;
 }
 
 main();

package/man/cssgrep.1

@@ -1,6 +1,6 @@
 .\" Man page for cssgrep. Keep the OPTIONS section in sync with the USAGE
 .\" string in index.js.
-.TH CSSGREP 1 "2026-07-02" "cssgrep 1.1.0" "User Commands"
+.TH CSSGREP 1 "2026-07-02" "cssgrep 1.2.0" "User Commands"
 .SH NAME
 cssgrep \- search HTML by CSS selector, grep-style
 .SH SYNOPSIS
@@ -33,9 +33,9 @@ Input is read from the
 .I file
 arguments, recursively from directories with
 .BR \-r ,
-or from standard input when no path is given. Binary files (a NUL byte or a
-high ratio of control bytes in the first 8 KB) are skipped with a note on
-standard error, suppressible with
+or from standard input when no path is given. Binary input, including standard
+input (a NUL byte or a high ratio of control bytes in the first 8 KB), is
+skipped with a note on standard error, suppressible with
 .B \-s
 or
 .BR \-q .
@@ -91,10 +91,21 @@ one per line
 comments and blank lines ignored), like a
 .IR .gitignore .
 .TP
+.BR \-S ", " \-\-follow
+Follow symbolic links while recursing with
+.B \-r
+(they are skipped by default). Each physical directory is visited once, so
+symlink cycles are safe.
+.TP
 .BR \-n ", " \-\-line\-number
 Prefix each match with its
 .IR line : col
-locator. Excludes
+locator. The column counts bytes (what vim's
+.B grepformat
+.I %c
+expects), pointing at the opening
+.B <
+of the matched tag. Excludes
 .B \-c
 and
 .BR \-p .
@@ -107,7 +118,8 @@ locator is shown.
 .BI \-\-attr " name"
 Print the value of attribute
 .I name
-for each match (nodes without it are skipped).
+for each match (nodes without it are skipped; if every match is skipped the
+exit status is 1). The name is matched case-insensitively.
 .TP
 .B \-\-text
 Print the matched node's text content, whitespace collapsed.
@@ -149,10 +161,17 @@ matches per file.
 .BR \-M ", " \-\-max\-total " \fIn\fR"
 Stop after
 .I n
-matches in total across all files.
+matches in total across all files. The budget counts matches, not files;
+combined with
+.B \-l
+or
+.B \-L
+scanning stops once the budget is spent, which can cut the file list short.
 .TP
 .BR \-c ", " \-\-count
-Print only a count of matches (per file when relevant).
+Print only a count of matches (per file when relevant). Files with no match
+report a zero count, as in
+.BR grep .
 .TP
 .BR \-l ", " \-\-files\-with\-matches
 Print only the names of files that have a match.
@@ -184,7 +203,12 @@ Colorize output:
 A bare
 .B \-\-color
 means
-.IR always .
+.IR auto ,
+as in
+.BR grep ;
+use
+.B \-\-color=always
+to force color into a pipe.
 .TP
 .BR \-h ", " \-\-help
 Show help and exit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssgrep",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
   "main": "index.js",
   "bin": {