-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
9 changed files
with
517 additions
and
488 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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') | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) | ||
} | ||
} | ||
``` |
Oops, something went wrong.