diff --git a/faq.md b/faq.md index bc217b64a6..8ca217824c 100644 --- a/faq.md +++ b/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. diff --git a/package-lock.json b/package-lock.json index d61402ac65..817986fb25 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5,7 +5,7 @@ "packages": { "": { "devDependencies": { - "vitepress": "^1.1.4" + "vitepress": "^1.2.2" } }, "node_modules/@algolia/autocomplete-core": { @@ -805,18 +805,18 @@ ] }, "node_modules/@shikijs/core": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.5.1.tgz", - "integrity": "sha512-xjV63pRUBvxA1LsxOUhRKLPh0uUjwBLzAKLdEuYSLIylo71sYuwDcttqNP01Ib1TZlLfO840CXHPlgUUsYFjzg==", + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.6.1.tgz", + "integrity": "sha512-CqYyepN4SnBopaoXYwng4NO8riB5ask/LTCkhOFq+GNGtr2X+aKeD767eYdqYukeixEUvv4bXdyTYVaogj7KBw==", "dev": true }, "node_modules/@shikijs/transformers": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-1.5.1.tgz", - "integrity": "sha512-vir+y0elkjh2CepLVbqeGX+ftuc6WpfWNCMV/EBIallSLzhBfDO9r/TORDVOzegbTg9JMEmtOFv6PT9cSZTcyA==", + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-1.6.1.tgz", + "integrity": "sha512-m/h2Dh99XWvTzHL8MUQmEnrB+/gxDljIfgDNR00Zg941KENqORx8Hi9sKpGYjCgXoEJKASZlEMQdPnkHj9/8aQ==", "dev": true, "dependencies": { - "shiki": "1.5.1" + "shiki": "1.6.1" } }, "node_modules/@types/estree": { @@ -917,21 +917,21 @@ } }, "node_modules/@vue/devtools-api": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/@vue/devtools-api/-/devtools-api-7.1.3.tgz", - "integrity": "sha512-W8IwFJ/o5iUk78jpqhvScbgCsPiOp2uileDVC0NDtW38gCWhsnu9SeBTjcdu3lbwLdsjc+H1c5Msd/x9ApbcFA==", + "version": "7.2.1", + "resolved": "https://registry.npmjs.org/@vue/devtools-api/-/devtools-api-7.2.1.tgz", + "integrity": "sha512-6oNCtyFOrNdqm6GUkFujsCgFlpbsHLnZqq7edeM/+cxAbMyCWvsaCsIMUaz7AiluKLccCGEM8fhOsjaKgBvb7g==", "dev": true, "dependencies": { - "@vue/devtools-kit": "^7.1.3" + "@vue/devtools-kit": "^7.2.1" } }, "node_modules/@vue/devtools-kit": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/@vue/devtools-kit/-/devtools-kit-7.1.3.tgz", - "integrity": "sha512-NFskFSJMVCBXTkByuk2llzI3KD3Blcm7WqiRorWjD6nClHPgkH5BobDH08rfulqq5ocRt5xV+3qOT1Q9FXJrwQ==", + "version": "7.2.1", + "resolved": "https://registry.npmjs.org/@vue/devtools-kit/-/devtools-kit-7.2.1.tgz", + "integrity": "sha512-Wak/fin1X0Q8LLIfCAHBrdaaB+R6IdpSXsDByPHbQ3BmkCP0/cIo/oEGp9i0U2+gEqD4L3V9RDjNf1S34DTzQQ==", "dev": true, "dependencies": { - "@vue/devtools-shared": "^7.1.3", + "@vue/devtools-shared": "^7.2.1", "hookable": "^5.5.3", "mitt": "^3.0.1", "perfect-debounce": "^1.0.0", @@ -942,9 +942,9 @@ } }, "node_modules/@vue/devtools-shared": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/@vue/devtools-shared/-/devtools-shared-7.1.3.tgz", - "integrity": "sha512-KJ3AfgjTn3tJz/XKF+BlVShNPecim3G21oHRue+YQOsooW+0s+qXvm09U09aO7yBza5SivL1QgxSrzAbiKWjhQ==", + "version": "7.2.1", + "resolved": "https://registry.npmjs.org/@vue/devtools-shared/-/devtools-shared-7.2.1.tgz", + "integrity": "sha512-PCJF4UknJmOal68+X9XHyVeQ+idv0LFujkTOIW30+GaMJqwFVN9LkQKX4gLqn61KkGMdJTzQ1bt7EJag3TI6AA==", "dev": true, "dependencies": { "rfdc": "^1.3.1" @@ -1434,12 +1434,12 @@ "peer": true }, "node_modules/shiki": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.5.1.tgz", - "integrity": "sha512-vx4Ds3M3B9ZEmLeSXqBAB85osBWV8ErZfP69kuFQZozPgHc33m7spLTCUkcjwEjFm3gk3F9IdXMv8kX+v9xDHA==", + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.6.1.tgz", + "integrity": "sha512-1Pu/A1rtsG6HZvQm4W0NExQ45e02og+rPog7PDaFDiMumZgOYnZIu4JtGQeAIfMwdbKSjJQoCUr79vDLKUUxWA==", "dev": true, "dependencies": { - "@shikijs/core": "1.5.1" + "@shikijs/core": "1.6.1" } }, "node_modules/source-map-js": { @@ -1522,26 +1522,27 @@ } }, "node_modules/vitepress": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.1.4.tgz", - "integrity": "sha512-bWIzFZXpPB6NIDBuWnS20aMADH+FcFKDfQNYFvbOWij03PR29eImTceQHIzCKordjXYBhM/TjE5VKFTUJ3EheA==", + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.2.2.tgz", + "integrity": "sha512-uZ3nXR5NY4nYj3RJWCo5jev9qlNZAQo5SUXu1U0QSUx84cUm/o7hCTDVjZ4njVSVui+PsV1oAbdQOg8ygbaf4w==", "dev": true, "dependencies": { "@docsearch/css": "^3.6.0", "@docsearch/js": "^3.6.0", - "@shikijs/core": "^1.3.0", - "@shikijs/transformers": "^1.3.0", - "@types/markdown-it": "^14.0.1", + "@shikijs/core": "^1.5.2", + "@shikijs/transformers": "^1.5.2", + "@types/markdown-it": "^14.1.1", "@vitejs/plugin-vue": "^5.0.4", - "@vue/devtools-api": "^7.0.27", + "@vue/devtools-api": "^7.2.0", + "@vue/shared": "^3.4.27", "@vueuse/core": "^10.9.0", "@vueuse/integrations": "^10.9.0", "focus-trap": "^7.5.4", "mark.js": "8.11.1", "minisearch": "^6.3.0", - "shiki": "^1.3.0", - "vite": "^5.2.10", - "vue": "^3.4.25" + "shiki": "^1.5.2", + "vite": "^5.2.11", + "vue": "^3.4.27" }, "bin": { "vitepress": "bin/vitepress.js" diff --git a/package.json b/package.json index 986a6b1acd..01ad427625 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "private": true, "devDependencies": { - "vitepress": "^1.1.4" + "vitepress": "^1.2.2" }, "scripts": { "docs:dev": "vitepress dev", diff --git a/process-promise.md b/process-promise.md index b64f630066..d34e0a7b49 100644 --- a/process-promise.md +++ b/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()`