Docs for v8.0.0

.vitepress/config.mts

@@ -41,6 +41,8 @@ export default defineConfig({
             {text: 'API Reference', link: '/api'},
             {text: 'Configuration', link: '/configuration'},
             {text: 'CLI Usage', link: '/cli'},
+            {text: 'Package', link: '/package'},
+            {text: 'Migration from v7', link: '/migration-from-v7'},
           ],
         },
         {

api.md

@@ -1,5 +1,86 @@
 # API Reference
 
+## $.sync 
+Zx provides both synchronous and asynchronous command executions, returns [`ProcessOutput`](./process-output) or [`ProcessPromise`](./process-promise) respectively.
+
+```js
+const list = await $`ls -la`
+const dir = $.sync`pwd`
+```
+
+## $({...})
+
+`$` object holds the default zx [configuration](./configuration), which is used for all execution. To specify a custom preset use `$` as factory:
+
+```js
+const $$ = $({
+  verbose: false,
+  env: {NODE_ENV: 'production'},
+})
+
+const env = await $$`node -e 'console.log(process.env.NODE_ENV)'`
+const pwd = $$.sync`pwd`
+const hello = $({quiet: true})`echo "Hello!"`
+```
+
+### $({input})
+
+The input option passes the specified `stdin` to the command.
+
+```js
+const p1 = $({ input: 'foo' })`cat`
+const p2 = $({ input: Readable.from('bar') })`cat`
+const p3 = $({ input: Buffer.from('baz') })`cat`
+const p4 = $({ input: p3 })`cat`
+const p5 = $({ input: await p3 })`cat`
+```
+
+### $({signal})
+
+The signal option makes the process abortable.
+
+```js
+const {signal} = new AbortController()
+const p = $({ signal })`sleep 9999`
+
+setTimeout(() => signal.abort('reason'), 1000)
+```
+
+### $({timeout})
+
+The timeout option makes the process autokillable after the specified delay.
+
+```js
+const p = $({timeout: '1s'})`sleep 999`
+```
+
+The full options list:
+```ts
+interface Options {
+  cwd:            string
+  ac:             AbortController
+  signal:         AbortSignal
+  input:          string | Buffer | Readable | ProcessOutput | ProcessPromise
+  timeout:        Duration
+  timeoutSignal:  string
+  stdio:          StdioOptions
+  verbose:        boolean
+  sync:           boolean
+  env:            NodeJS.ProcessEnv
+  shell:          string | boolean
+  nothrow:        boolean
+  prefix:         string
+  postfix:        string
+  quote:          typeof quote
+  quiet:          boolean
+  detached:       boolean
+  spawn:          typeof spawn
+  spawnSync:      typeof spawnSync
+  log:            typeof log
+  kill:           typeof kill
+}
+```
+
 ## cd()
 
 Changes the current working directory.
@@ -133,10 +214,36 @@ The [which](https://github.com/npm/node-which) package.
 const node = await which('node')
 ```
 
-## argv
+## ps()
+
+The [@webpod/ps](https://github.com/webpod/ps) package to provide a cross-platform way to list processes.
+
+```js
+const all = await ps.lookup()
+const nodejs = await ps.lookup({ command: 'node' })
+const children = await ps.tree({ pid: 123 })
+const fulltree = await ps.tree({ pid: 123, recursive: true })
+```
+
+## kill()
+
+A process killer.
+
+```js
+await kill(123)
+await kill(123, 'SIGKILL')
+```
+
+## minimist
 
 The [minimist](https://www.npmjs.com/package/minimist) package.
 
+```js
+const argv = minimist(process.argv.slice(2), {})
+```
+
+## argv
+
 A minimist-parsed version of the `process.argv` as `argv`.
 
 ```js

configuration.md

@@ -14,6 +14,8 @@ Or use a CLI argument: `--shell=/bin/bash`
 
 Specifies a `spawn` api. Defaults to `require('child_process').spawn`.
 
+To override a sync API implementation, set `$.spawnSync` correspondingly.
+
 ## $.prefix
 
 Specifies the command that will be prefixed to all commands run.
@@ -22,19 +24,33 @@ Default is `set -euo pipefail;`.
 
 Or use a CLI argument: `--prefix='set -e;'`
 
+## $.postfix
+
+Like a `$.prefix`, but for the end of the command.
+
+```js
+$.postfix = '; exit $LastExitCode' // for PowerShell compatibility
+```
+
 ## $.quote
 
 Specifies a function for escaping special characters during
 command substitution.
 
 ## $.verbose
 
-Specifies verbosity. Default is `true`.
+Specifies verbosity. Default is `false`.
 
 In verbose mode, `zx` prints all executed commands alongside with their
 outputs.
 
-Or use the CLI argument `--quiet` to set `$.verbose = false`.
+Or use the CLI argument: `--verbose` to set `true`.
+
+## $.quiet
+
+Suppresses all output. Default is `false`.
+
+Via CLI argument: `--quiet` sets `$.quiet = true`.
 
 ## $.env
 

getting-started.md

@@ -35,6 +35,10 @@ gives sensible defaults.
 npm install zx
 ```
 
+```bash [bun]
+bun install zx
+```
+
 ```bash [deno]
 deno install -A npm:zx
 ```
@@ -82,7 +86,12 @@ import 'zx/globals'
 ### ``$`command` ``
 
 Executes a given command using the `spawn` func
-and returns [`ProcessPromise`](process-promise.md).
+and returns [`ProcessPromise`](process-promise.md). It supports both sync and async modes.
+
+```js
+const list = await $`ls -la`
+const dir = $.sync`pwd`
+```
 
 Everything passed through `${...}` will be automatically escaped and quoted.
 

migration-from-v7.md

@@ -0,0 +1,44 @@
+# Migration from v7 to v8
+
+[v8.0.0 release](https://github.com/google/zx/releases/tag/8.0.0) brought many features, improvements and fixes, but also has introduced a few breaking changes.
+
+1. `$.verbose` is set to `false` by default, but errors are still printed to `stderr`. Set `$.quiet = true` to suppress any output.
+```js
+$.verbose = true // everything works like in v7
+
+$.quiet = true   // to completely turn off logging
+```
+
+2. `ssh` API was dropped. Install [webpod](https://github.com/webpod/webpod) package instead.
+```js
+// import {ssh} from 'zx' ↓
+import {ssh} from 'webpod'
+
+const remote = ssh('user@host')
+await remote`echo foo`
+```
+
+3. zx is not looking for `PowerShell` anymore, on Windows by default. If you still need it, use the `usePowerShell` helper to enable:
+
+```js
+import { usePowerShell, useBash } from 'zx'
+
+usePowerShell() // to enable powershell
+useBash()       // switch to bash, the default
+```
+
+To look for modern [PowerShell v7+](https://github.com/google/zx/pull/790), invoke `usePwsh()` helper instead:
+
+```js
+import { usePwsh } from 'zx'
+
+usePwsh()
+```
+
+4. Process cwd synchronization between `$` invocations is now disabled by default. This functionality is provided via an async hook and can now be controlled directly.
+
+```js
+import { syncProcessCwd } from 'zx'
+
+syncProcessCwd() // restores legacy v7 behavior
+```