Docs v8.1.0 (#808)

Author: antongolub

.vitepress/config.mts

@@ -37,10 +37,13 @@ export default defineConfig({
           text: 'Docs',
           items: [
             {text: 'Getting Started', link: '/getting-started'},
-            {text: 'Process Promise', link: '/process-promise'},
+            {text: 'Setup', link: '/setup'},
             {text: 'API Reference', link: '/api'},
-            {text: 'Configuration', link: '/configuration'},
             {text: 'CLI Usage', link: '/cli'},
+            {text: 'Configuration', link: '/configuration'},
+            {text: 'Process Promise', link: '/process-promise'},
+            {text: 'Contribution Guide', link: '/contribution'},
+            {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,55 @@ 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')
+```
+
+## tmpdir()
+
+Creates a temporary directory.
+
+```js
+t1 = tmpdir()       // /os/based/tmp/zx-1ra1iofojgg/
+t2 = tmpdir('foo')  // /os/based/tmp/zx-1ra1iofojgg/foo/
+```
+
+## tmpfile()
+
+Temp file factory.
+
+```js
+f1 = tmpfile()         // /os/based/tmp/zx-1ra1iofojgg
+f2 = tmpfile('f.txt')  // /os/based/tmp/zx-1ra1iofojgg/foo.txt
+f3 = tmpfile('f.txt', 'string or buffer')
+```
+
+## 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

cli.md

@@ -67,6 +67,46 @@ the import.
 import sh from 'tinysh' // @^1
 ```
 
+## --quiet
+
+Suppress any outputs.
+
+## --verbose
+
+Enable verbose mode.
+
+## --shell
+
+Specify a custom shell binary.
+
+```bash
+zx --shell=/bin/bash script.mjs
+```
+
+## --prefix & --postfix
+
+Attach a command to the beginning or the end of every command.
+
+```bash
+zx --prefix='echo foo;' --postfix='; echo bar' script.mjs
+```
+
+## --cwd
+
+Set the current working directory.
+
+```bash
+zx --cwd=/foo/bar script.mjs
+```
+
+## --version
+
+Print the current version of `zx`.
+
+## --help
+
+Print help.
+
 ## __filename & __dirname
 
 In [ESM](https://nodejs.org/api/esm.html) modules, Node.js does not provide

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
 

contribution.md

@@ -0,0 +1,52 @@
+# Contribution Guide
+
+zx is a fully [open-source project](https://github.com/google/zx), which is developing by the community for the community. 
+We welcome contributions of any kind, including but not limited to:
+* Bug reports
+* Feature requests
+* Code contributions
+* Documentation improvements
+* Discussions
+
+## Community Guidelines
+
+This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
+In short: all contributors are treated with respect and fairness.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## How to Contribute
+Before proposing changes, look for similar ones in the project's [issues](https://github.com/google/zx/issues) and [pull requests](https://github.com/google/zx/pulls). If you can't decide, create a new [discussion](https://github.com/google/zx/discussions) topic, and we will help you figure it out. When ready to move on:
+* Prepare your development environment.
+  * Ensure you have Node.js 20+ installed.
+  * Bash is essential for running zx scripts. Linux and macOS users usually have it installed by default. Consider using [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) or [Git Bash](https://git-scm.com/downloads) if you are on Windows.
+* Fork [the repository](https://github.com/google/zx).
+* Create a new branch.
+* Make your changes.
+  * If you are adding a new feature, please include additional tests. The coverage threshold is 98%.
+  * Create a [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/) compliant messages.
+* Ensure that everything is working:
+  * `npm run fmt` to format your code.
+  * `npm run cov` to run the tests.
+* Push the changes to your fork.
+* Create a pull request.
+  * Describe your changes in detail.
+  * Reference any related issues if applicable.
+
+## Code Reviews
+
+All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.
+
+## License
+
+The project is licensed under the [Apache-2.0](https://github.com/google/zx?tab=Apache-2.0-1-ov-file#readme)

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
+```