docs: describe verbose and quiet (#835)

* docs: describe verbose and quiet inners

* chore: update vitepress to v1.2.2

faq.md

@@ -62,6 +62,54 @@ jobs:
           EOF
 ```
 
+## Verbose and Quiet
+zx has internal logger, which captures events if a condition is met:
+
+| Event  | Verbose | Quiet   | Description                  |
+|--------|---------|---------|------------------------------|
+| stdout | `true`  | `false` | Spawned process stdout       |
+| stderr | `any`   | `false` | Process stderr data          |
+| cmd    | `true`  | `false` | Command execution            |
+| fetch  | `true`  | `false` | Fetch resources by http(s)   |
+| cd     | `true`  | `false` | Change directory             |
+| retry  | `true`  | `false` | Capture exec error           |
+| custom | `true`  | `false` | User-defined event           |
+
+By default, both `$.verbose` and `$.quiet` options are `false`, so only `stderr` events are written. Any output goes to the `process.stderr` stream.
+
+You may control this flow globally or in-place
+```js
+// Global debug mode on
+$.verbose = true
+await $`echo hello`
+
+// Suppress the particular command
+await $`echo fobar`.quiet()
+
+// Suppress everything
+$.quiet = true
+await $`echo world`
+
+// Turn on in-place debug
+await $`echo foo`.verbose()
+```
+
+You can also override the default logger with your own:
+```js
+// globally
+$.log = (entry) => {
+  switch (entry.kind) {
+    case 'cmd':
+      console.log('Command:', entry.cmd)
+      break
+    default:
+      console.warn(entry)
+  }
+}
+// or in-place
+$({log: () => {}})`echo hello`
+```
+
 ## Canary / Beta / RC builds
 
 Impatient early adopters can try the experimental zx versions.

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "devDependencies": {
-    "vitepress": "^1.1.4"
+    "vitepress": "^1.2.2"
   },
   "scripts": {
     "docs:dev": "vitepress dev",

process-promise.md

@@ -170,11 +170,25 @@ if ((await $`[[ -d path ]]`.nothrow()).exitCode == 0) {
 
 ## `quiet()`
 
-Changes behavior of `$` to disable verbose output.
+Changes behavior of `$` to enable suppress mode.
 
 ```js
-// Command and output will not be displayed.
+// Command output will not be displayed.
 await $`grep something from-file`.quiet()
+
+$.quiet = true
+await $`echo foo`.quiet(false) // Disable for the specific command
+```
+
+## `verbose()`
+
+Enables verbose output. Pass `false` to disable.
+
+```js
+await $`grep something from-file`.verbose()
+
+$.verbose = true
+await $`echo foo`.verbose(false) // Turn off verbose mode once
 ```
 
 ## `timeout()`