Skip to content

Commit

Permalink
Split documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
antonmedv committed Sep 5, 2023
1 parent 062cfd3 commit bbe6044
Show file tree
Hide file tree
Showing 9 changed files with 517 additions and 488 deletions.
15 changes: 15 additions & 0 deletions .vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,19 @@ export default defineConfig({
items: [
{text: 'Getting Started', link: '/getting-started'},
{text: 'Process Promise', link: '/process-promise'},
{text: 'API Reference', link: '/api'},
{text: 'Configuration', link: '/configuration'},
{text: 'CLI Usage', link: '/cli'},
],
},
{
text: 'FAQ',
link: '/faq',
items: [
{text: 'Quotes', link: '/quotes'},
{text: 'TypeScript', link: '/typescript'},
{text: 'Markdown Scripts', link: '/markdown-scripts'},
{text: 'Known Issues', link: '/known-issues'},
],
},
],
Expand All @@ -45,6 +56,10 @@ export default defineConfig({
{icon: 'github', link: 'https://github.com/google/zx'},
],

editLink: {
pattern: 'https://github.com/google/zx/blob/gh-pages/:path',
},

footer: {
message: 'Disclaimer: This is not an officially supported Google product.',
},
Expand Down
200 changes: 200 additions & 0 deletions api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# API Reference

## cd()

Changes the current working directory.

```js
cd('/tmp')
await $`pwd` // => /tmp
```

Like `echo`, in addition to `string` arguments, `cd` accepts and trims
trailing newlines from `ProcessOutput` enabling common idioms like:

```js
cd(await $`mktemp -d`)
```

## fetch()

A wrapper around the [node-fetch](https://www.npmjs.com/package/node-fetch)
package.

```js
let resp = await fetch('https://medv.io')
```

## question()

A wrapper around the [readline](https://nodejs.org/api/readline.html) package.

```js
let bear = await question('What kind of bear is best? ')
```

## sleep()

A wrapper around the `setTimeout` function.

```js
await sleep(1000)
```

## echo()

A `console.log()` alternative which can take [ProcessOutput](#processoutput).

```js
let branch = await $`git branch --show-current`

echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)
```

## stdin()

Returns the stdin as a string.

```js
let content = JSON.parse(await stdin())
```

## within()

Creates a new async context.

```js
await $`pwd` // => /home/path

within(async () => {
cd('/tmp')

setTimeout(async () => {
await $`pwd` // => /tmp
}, 1000)
})

await $`pwd` // => /home/path
```

```js
await $`node --version` // => v20.2.0

let version = await within(async () => {
$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; nvm use 16;'

return $`node --version`
})

echo(version) // => v16.20.0
```

## retry()

Retries a callback for a few times. Will return after the first
successful attempt, or will throw after specifies attempts count.

```js
let p = await retry(10, () => $`curl https://medv.io`)

// With a specified delay between attempts.
let p = await retry(20, '1s', () => $`curl https://medv.io`)

// With an exponential backoff.
let p = await retry(30, expBackoff(), () => $`curl https://medv.io`)
```

## spinner()

Starts a simple CLI spinner.

```js
await spinner(() => $`long-running command`)

// With a message.
await spinner('working...', () => $`sleep 99`)
```

## glob()

The [globby](https://github.com/sindresorhus/globby) package.

```js
let packages = await glob(['package.json', 'packages/*/package.json'])
```

## which()

The [which](https://github.com/npm/node-which) package.

```js
let node = await which('node')
```

## argv

The [minimist](https://www.npmjs.com/package/minimist) package.

A minimist-parsed version of the `process.argv` as `argv`.

```js
if (argv.someFlag) {
echo('yes')
}
```

Use minimist options to customize the parsing:

```js
const myCustomArgv = minimist(process.argv.slice(2), {
boolean: [
'force',
'help',
],
alias: {
h: 'help',
},
})
```

## chalk

The [chalk](https://www.npmjs.com/package/chalk) package.

```js
console.log(chalk.blue('Hello world!'))
```

## fs

The [fs-extra](https://www.npmjs.com/package/fs-extra) package.

```js
let {version} = await fs.readJson('./package.json')
```

## os

The [os](https://nodejs.org/api/os.html) package.

```js
await $`cd ${os.homedir()} && mkdir example`
```

## path

The [path](https://nodejs.org/api/path.html) package.

```js
await $`mkdir ${path.join(basedir, 'output')}`
```

## yaml

The [yaml](https://www.npmjs.com/package/yaml) package.

```js
console.log(YAML.parse('foo: bar').foo)
```
96 changes: 96 additions & 0 deletions cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# CLI Usage

Zx provides a CLI for running scripts. It is installed with the package and can be used as `zx` executable.

```sh
zx script.mjs
```

## Scripts without extensions

If script does not have a file extension (like `.git/hooks/pre-commit`), zx
assumes that it is
an [ESM](https://nodejs.org/api/modules.html#modules_module_createrequire_filename)
module.

```bash
zx docs/markdown.md
```

## Executing remote scripts

If the argument to the `zx` executable starts with `https://`, the file will be
downloaded and executed.

```bash
zx https://medv.io/game-of-life.js
```

## Executing scripts from stdin

The `zx` supports executing scripts from stdin.

```js
zx << 'EOF'
await $`pwd`
EOF
```

## Executing scripts via --eval

Evaluate the following argument as a script.

```bash
cat package.json | zx --eval 'let v = JSON.parse(await stdin()).version; echo(v)'
```

## Installing dependencies via --install

```js
// script.mjs:
import sh from 'tinysh'

sh.say('Hello, world!')
```

Add `--install` flag to the `zx` command to install missing dependencies
automatically.

```bash
zx --install script.mjs
```

You can also specify needed version by adding comment with `@` after
the import.

```js
import sh from 'tinysh' // @^1
```

## Executing commands on remote hosts

The `zx` uses [webpod](https://github.com/webpod/webpod) to execute commands on
remote hosts.

```js
import {ssh} from 'zx'

await ssh('user@host')`echo Hello, world!`
```

## `__filename` and `__dirname`

In [ESM](https://nodejs.org/api/esm.html) modules, Node.js does not provide
`__filename` and `__dirname` globals. As such globals are really handy in scripts,
zx provides these for use in `.mjs` files (when using the `zx` executable).

## require()

In [ESM](https://nodejs.org/api/modules.html#modules_module_createrequire_filename)
modules, the `require()` function is not defined.
The `zx` provides `require()` function, so it can be used with imports in `.mjs`
files (when using `zx` executable).

```js
let {version} = require('./package.json')
```
69 changes: 69 additions & 0 deletions configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Configuration

## $.shell

Specifies what shell is used. Default is `which bash`.

```js
$.shell = '/usr/bin/bash'
```

Or use a CLI argument: `--shell=/bin/bash`

## $.spawn

Specifies a `spawn` api. Defaults to `require('child_process').spawn`.

## $.prefix

Specifies the command that will be prefixed to all commands run.

Default is `set -euo pipefail;`.

Or use a CLI argument: `--prefix='set -e;'`

## $.quote

Specifies a function for escaping special characters during
command substitution.

## $.verbose

Specifies verbosity. Default is `true`.

In verbose mode, `zx` prints all executed commands alongside with their
outputs.

Or use the CLI argument `--quiet` to set `$.verbose = false`.

## $.env

Specifies an environment variables map.

Defaults to `process.env`.

## $.cwd

Specifies a current working directory of all processes created with the `$`.

The [cd()](#cd) func changes only `process.cwd()` and if no `$.cwd` specified,
all `$` processes use `process.cwd()` by default (same as `spawn` behavior).

## $.log

Specifies a [logging function](src/core.ts).

```ts
import {LogEntry, log} from 'zx/core'

$.log = (entry: LogEntry) => {
switch (entry.kind) {
case 'cmd':
// for example, apply custom data masker for cmd printing
process.stderr.write(masker(entry.cmd))
break
default:
log(entry)
}
}
```
Loading

0 comments on commit bbe6044

Please sign in to comment.