Commit 3e5bcb0

@@ -1,9 +1,8 @@
 name: Deploy docs
-
 on:
-  push:
-    branches: ['gh-pages']
   workflow_dispatch:
+  release:
+    types: [created]
 
 permissions:
   contents: read
@@ -24,17 +23,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          ref: gh-pages
+          ref: main
       - name: Setup Pages
         uses: actions/configure-pages@v3
       - name: Install deps
         run: npm ci
-      - name: Built docs
-        run: npm run docs:built
+      - name: Build docs
+        run: npm run docs:build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          path: 'docs'
+          path: 'docs/build'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2

@@ -0,0 +1,27 @@
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #f11a7b 10%,
+    #feffac
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    rgba(241, 26, 123, 0.33) 50%,
+    rgba(254, 255, 172, 0.33) 50%
+  );
+  --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(72px);
+  }
+}

@@ -0,0 +1,10 @@
+import DefaultTheme from 'vitepress/theme'
+import MyLayout from './MyLayout.vue'
+import './custom.css'
+
+export default {
+  ...DefaultTheme,
+  // override the Layout with a wrapper component that
+  // injects the slots
+  Layout: MyLayout,
+}

@@ -0,0 +1,14 @@
+<script setup>
+import DefaultTheme from 'vitepress/theme'
+import MyOxygen from './MyOxygen.vue'
+
+const { Layout } = DefaultTheme
+</script>
+
+<template>
+  <Layout>
+    <template #aside-ads-after>
+      <MyOxygen />
+    </template>
+  </Layout>
+</template>

@@ -0,0 +1,44 @@
+<template>
+  <div class="Oxygen">
+    <a href="https://webpod.dev/?from=zx-site">
+      <!--<img src="https://webpod.dev/img/banner.png" alt="Webpod - deploy JavaScript apps">-->
+      <img
+        src="https://webpod.dev/img/logo.svg"
+        alt="Webpod - deploy JavaScript apps"
+      />
+      <p>Webpod – deploy JavaScript apps to own cloud or private server</p>
+    </a>
+  </div>
+</template>
+
+<style scoped>
+.Oxygen {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: 24px;
+  border-radius: 12px;
+  min-height: 256px;
+  text-align: center;
+  line-height: 18px;
+  font-size: 12px;
+  font-weight: 500;
+  background-color: var(--vp-carbon-ads-bg-color);
+}
+
+.Oxygen :deep(img) {
+  margin: 0 auto;
+}
+
+.Oxygen :deep(p) {
+  display: block;
+  margin: 0 auto;
+  color: var(--vp-carbon-ads-text-color);
+  transition: color 0.25s;
+}
+
+.Oxygen :deep(p:hover) {
+  color: var(--vp-carbon-ads-hover-text-color);
+}
+</style>
+<script setup></script>

@@ -0,0 +1,131 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  base: '/zx/',
+  outDir: 'build',
+  cleanUrls: true,
+  title: 'google/zx',
+  titleTemplate: ':title | google/zx',
+  description: 'A tool for writing better scripts',
+  head: [
+    [
+      'link',
+      {
+        rel: 'apple-touch-icon',
+        sizes: '180x180',
+        href: '/zx/img/favicons/apple-touch-icon.png',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        sizes: '32x32',
+        href: '/zx/img/favicons/favicon-32x32.png',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        sizes: '16x16',
+        href: '/zx/img/favicons/favicon-16x16.png',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'mask-icon',
+        href: '/zx/img/favicons/safari-pinned-tab.svg',
+        color: '#3a0839',
+      },
+    ],
+    ['link', { rel: 'shortcut icon', href: '/zx/img/favicons/favicon.ico' }],
+    ['meta', { name: 'og:image', content: '/zx/img/og-image.png' }],
+    ['meta', { name: 'twitter:image', content: '/zx/img/og-image.png' }],
+  ],
+  themeConfig: {
+    logo: '/img/logo.svg',
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Docs', link: '/getting-started' },
+      {
+        text: 'v8',
+        items: [
+          { text: 'v8', link: '/migration-from-v7' },
+          { text: 'v7', link: '/v7/api' },
+        ],
+      },
+    ],
+
+    sidebar: {
+      '/': [
+        {
+          text: 'Docs',
+          items: [
+            { text: 'Getting Started', link: '/getting-started' },
+            { text: 'Setup', link: '/setup' },
+            { text: 'API Reference', link: '/api' },
+            { 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' },
+          ],
+        },
+        {
+          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' },
+          ],
+        },
+      ],
+
+      '/v7/': [
+        {
+          text: 'Docs (v7)',
+          items: [
+            { text: 'Getting Started', link: '/v7/getting-started' },
+            { text: 'Process Promise', link: '/v7/process-promise' },
+            { text: 'API Reference', link: '/v7/api' },
+            { text: 'Configuration', link: '/v7/configuration' },
+            { text: 'CLI Usage', link: '/v7/cli' },
+          ],
+        },
+        {
+          text: 'FAQ',
+          link: '/v7/faq',
+          items: [
+            { text: 'Quotes', link: '/v7/quotes' },
+            { text: 'TypeScript', link: '/v7/typescript' },
+            { text: 'Markdown Scripts', link: '/v7/markdown-scripts' },
+            { text: 'Known Issues', link: '/v7/known-issues' },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/google/zx' }],
+
+    editLink: {
+      pattern: 'https://github.com/google/zx/blob/main/docs/:path',
+    },
+
+    footer: {
+      message:
+        'Disclaimer: This is not an officially supported Google product.',
+    },
+
+    search: {
+      provider: 'local',
+    },
+  },
+})

@@ -0,0 +1,31 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
+ "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
+ width="700.000000pt" height="700.000000pt" viewBox="0 0 700.000000 700.000000"
+ preserveAspectRatio="xMidYMid meet">
+<metadata>
+Created by potrace 1.14, written by Peter Selinger 2001-2017
+</metadata>
+<g transform="translate(0.000000,700.000000) scale(0.100000,-0.100000)"
+fill="#000000" stroke="none">
+<path d="M1089 6462 c-1 -77 -1 -1346 0 -1362 2 -17 23 -42 195 -223 66 -71
+137 -146 156 -166 19 -21 93 -100 165 -177 71 -76 164 -175 205 -219 93 -98
+110 -116 185 -197 80 -86 331 -353 425 -453 41 -43 81 -86 88 -93 11 -13 7
+-21 -26 -56 -64 -67 -121 -126 -233 -247 -59 -63 -120 -128 -135 -145 -16 -16
+-88 -93 -160 -170 -72 -76 -148 -157 -169 -179 -20 -22 -65 -69 -99 -105 -33
+-36 -117 -126 -186 -200 -69 -73 -141 -150 -160 -170 -19 -20 -87 -92 -150
+-160 -63 -68 -136 -146 -162 -173 -43 -45 -48 -55 -49 -96 0 -25 0 -345 -1
+-711 l0 -665 2516 -3 2516 -2 0 707 -1 708 -77 81 c-76 79 -306 324 -353 375
+-13 15 -79 84 -145 155 -67 71 -136 145 -154 164 -18 19 -85 91 -150 160 -133
+141 -176 187 -263 280 -33 36 -116 124 -184 196 -181 191 -223 238 -220 246 1
+3 54 61 117 128 63 68 126 134 139 149 13 14 81 87 151 161 70 74 142 151 160
+170 18 19 83 89 145 155 62 66 130 138 150 160 67 71 279 296 423 450 l141
+150 1 712 0 712 -2400 0 -2400 0 -1 -47z m2843 -1396 c-9 -11 -45 -50 -79 -86
+-34 -36 -76 -81 -93 -100 -18 -19 -86 -92 -153 -163 l-120 -127 -46 49 c-25
+28 -68 74 -95 103 -45 48 -110 118 -263 281 -29 30 -53 57 -53 59 0 2 207 4
+460 4 l459 0 -17 -20z m-389 -2598 c27 -29 106 -114 176 -188 272 -288 331
+-352 331 -360 0 -5 -1116 -7 -1129 -1 -2 0 26 31 61 69 150 156 218 228 235
+248 47 55 267 284 272 284 3 0 28 -24 54 -52z"/>
+</g>
+</svg>

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+    <defs>
+        <linearGradient id="a" x1="-45.695%" x2="100%" y1="50%" y2="50%">
+            <stop offset="0%" stop-color="#F11A7B"/>
+            <stop offset="100%" stop-color="#FEFFAC"/>
+        </linearGradient>
+    </defs>
+    <path fill="url(#a)" fill-rule="nonzero"
+          d="M219.764 186v52h-184v-52l56.399-60.132L39.763 70V18h175.6v52l-52.4 55.868 56.4 60.132h.4Zm-92.201-97.875 17-18.125h-34l17 18.125Zm0 75.485-21 22.39h42l-21-22.39Z"/>
+</svg>

@@ -0,0 +1,206 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# 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
+const resp = await fetch('https://medv.io')
+```
+
+## question()
+
+A wrapper around the [readline](https://nodejs.org/api/readline.html) package.
+
+```js
+const 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
+const 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
+const 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
+
+const 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
+const p = await retry(10, () => $`curl https://medv.io`)
+
+// With a specified delay between attempts.
+const p = await retry(20, '1s', () => $`curl https://medv.io`)
+
+// With an exponential backoff.
+const 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
+const packages = await glob(['package.json', 'packages/*/package.json'])
+```
+
+## which()
+
+The [which](https://github.com/npm/node-which) package.
+
+```js
+const 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
+const {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)
+```

@@ -0,0 +1,91 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# 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
+```
+
+## No 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
+```
+
+## 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
+```
+
+## Scripts from stdin
+
+The `zx` supports executing scripts from stdin.
+
+```js
+zx << 'EOF'
+await $`pwd`
+EOF
+```
+
+## --eval
+
+Evaluate the following argument as a script.
+
+```bash
+cat package.json | zx --eval 'const v = JSON.parse(await stdin()).version; echo(v)'
+```
+
+## --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
+```
+
+## __filename & __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
+const {version} = require('./package.json')
+```

@@ -0,0 +1,75 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# 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)
+  }
+}
+```

@@ -0,0 +1,79 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# FAQ
+
+## Passing env variables
+
+```js
+process.env.FOO = 'bar'
+await $`echo $FOO`
+```
+
+## Passing array of values
+
+When passing an array of values as an argument to `$`, items of the array will
+be escaped
+individually and concatenated via space.
+
+Example:
+
+```js
+const files = [...]
+await $`tar cz ${files}`
+```
+
+## Importing into other scripts
+
+It is possible to make use of `$` and other functions via explicit imports:
+
+```js
+#!/usr/bin/env node
+import {$} from 'zx'
+
+await $`date`
+```
+
+## Attaching a profile
+
+By default `child_process` does not include aliases and bash functions.
+But you are still able to do it by hand. Just attach necessary directives
+to the `$.prefix`.
+
+```js
+$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
+await $`nvm -v`
+```
+
+## Using GitHub Actions
+
+The default GitHub Action runner comes with `npx` installed.
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build
+        env:
+          FORCE_COLOR: 3
+        run: |
+          npx zx <<'EOF'
+          await $`...`
+          EOF
+```
+
+## Canary / Beta / RC builds
+
+Impatient early adopters can try the experimental zx versions.
+But keep in mind: these builds are ⚠️️__beta__ in every sense.
+
+```bash
+npm i zx@dev
+npx zx@dev --install --quiet <<< 'import _ from "lodash" /* 4.17.15 */; console.log(_.VERSION)'
+```

@@ -0,0 +1,153 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# Getting Started
+
+## Overview
+
+```js
+#!/usr/bin/env zx
+
+await $`cat package.json | grep name`
+
+const branch = await $`git branch --show-current`
+await $`dep deploy --branch=${branch}`
+
+await Promise.all([
+  $`sleep 1; echo 1`,
+  $`sleep 2; echo 2`,
+  $`sleep 3; echo 3`,
+])
+
+const name = 'foo bar'
+await $`mkdir /tmp/${name}`
+```
+
+Bash is great, but when it comes to writing more complex scripts,
+many people prefer a more convenient programming language.
+JavaScript is a perfect choice, but the Node.js standard library
+requires additional hassle before using. The `zx` package provides
+useful wrappers around `child_process`, escapes arguments and
+gives sensible defaults.
+
+## Install
+
+::: code-group
+
+```bash [node]
+npm install zx
+```
+
+```bash [deno]
+deno install -A npm:zx
+```
+
+```bash [brew]
+brew install zx
+```
+
+:::
+
+## Usage
+
+Write your scripts in a file with an `.mjs` extension in order to
+use `await` at the top level. If you prefer the `.js` extension,
+wrap your scripts in something like `void async function () {...}()`.
+
+Add the following shebang to the beginning of your `zx` scripts:
+
+```bash
+#!/usr/bin/env zx
+```
+
+Now you will be able to run your script like so:
+
+```bash
+chmod +x ./script.mjs
+./script.mjs
+```
+
+Or via the [CLI](cli.md):
+
+```bash
+zx ./script.mjs
+```
+
+All functions (`$`, `cd`, `fetch`, etc) are available straight away
+without any imports.
+
+Or import globals explicitly (for better autocomplete in VS Code).
+
+```js
+import 'zx/globals'
+```
+
+### ``$`command` ``
+
+Executes a given command using the `spawn` func
+and returns [`ProcessPromise`](process-promise.md).
+
+Everything passed through `${...}` will be automatically escaped and quoted.
+
+```js
+const name = 'foo & bar'
+await $`mkdir ${name}`
+```
+
+**There is no need to add extra quotes.** Read more about it in
+[quotes](quotes.md).
+
+You can pass an array of arguments if needed:
+
+```js
+const flags = [
+  '--oneline',
+  '--decorate',
+  '--color',
+]
+await $`git log ${flags}`
+```
+
+If the executed program returns a non-zero exit code,
+[`ProcessOutput`](#processoutput) will be thrown.
+
+```js
+try {
+  await $`exit 1`
+} catch (p) {
+  console.log(`Exit code: ${p.exitCode}`)
+  console.log(`Error: ${p.stderr}`)
+}
+```
+
+### `ProcessOutput`
+
+```ts
+class ProcessOutput {
+  readonly stdout: string
+  readonly stderr: string
+  readonly signal: string
+  readonly exitCode: number
+
+  toString(): string // Combined stdout & stderr.
+}
+```
+
+The output of the process is captured as-is. Usually, programs print a new
+line `\n` at the end.
+If `ProcessOutput` is used as an argument to some other `$` process,
+**zx** will use stdout and trim the new line.
+
+```js
+const date = await $`date`
+await $`echo Current date is ${date}.`
+```
+
+## License
+
+[Apache-2.0](https://github.com/google/zx/blob/main/LICENSE)
+
+Disclaimer: _This is not an officially supported Google product._

@@ -0,0 +1,33 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# Known Issues
+
+## Output gets truncated
+
+This is a known issue with `console.log()` (see [nodejs/node#6379](https://github.com/nodejs/node/issues/6379)).
+It's caused by different behaviour of `console.log()` writing to the terminal vs
+to a file. If a process calls `process.exit()`, buffered output will be truncated.
+To prevent this, the process should use `process.exitCode = 1` and wait for the
+process to exit itself. Or use something like [exit](https://www.npmjs.com/package/exit) package.
+
+Workaround is to write to a temp file:
+```js
+const tmp = await $`mktemp` // Creates a temp file.
+const {stdout} = await $`cmd > ${tmp}; cat ${tmp}`
+```
+
+## Colors in subprocess
+
+You may see what tools invoked with `await $` don't show colors, compared to
+what you see in a terminal. This is because, the subprocess does not think it's
+a TTY and the subprocess turns off colors. Usually there is a way force
+the subprocess to add colors.
+
+```js
+process.env.FORCE_COLOR='1'
+await $`cmd`
+```

@@ -0,0 +1,48 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# Markdown Scripts
+
+It's possible to write scripts using markdown. Only code blocks will be executed
+by zx.
+
+> You can run this markdown file:
+>
+> ```
+> zx docs/markdown.md
+> ```
+
+```js
+await $`whoami`
+await $`echo ${__dirname}`
+```
+
+The `__filename` will be pointed to **markdown.md**:
+
+```js
+console.log(chalk.yellowBright(__filename))
+```
+
+We can use imports here as well:
+
+```js
+await import('chalk')
+```
+
+A bash code (with `bash` or `sh` language tags) also will be executed:
+
+```bash
+VAR=$(date)
+echo "$VAR" | wc -c
+```
+
+Other code blocks are ignored:
+
+```css
+body .hero {
+  margin: 42px;
+}
+```

@@ -0,0 +1,157 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# Process Promise
+
+The `$` returns a `ProcessPromise` instance.
+
+```js
+const p = $`command`
+
+await p
+```
+
+## `stdin`
+
+Returns a writable stream of the stdin process. Accessing
+this getter will trigger execution of a subprocess with [`stdio('pipe')`](#stdio).
+
+Do not forget to end the stream.
+
+```js
+const p = $`while read; do echo $REPLY; done`
+p.stdin.write('Hello, World!\n')
+p.stdin.end()
+```
+
+By default, each process is created with stdin in _inherit_ mode.
+
+## `stdout`/`stderr`
+
+Returns a readable streams of stdout/stderr process.
+
+```js
+const p = $`npm init`
+for await (const chunk of p.stdout) {
+  echo(chunk)
+}
+```
+
+## `exitCode`
+
+Returns a promise which resolves to the exit code of the process.
+
+```js
+if (await $`[[ -d path ]]`.exitCode == 0) {
+...
+}
+```
+
+## `pipe()`
+
+Redirects the stdout of the process.
+
+```js
+await $`echo "Hello, stdout!"`
+  .pipe(fs.createWriteStream('/tmp/output.txt'))
+
+await $`cat /tmp/output.txt`
+```
+
+Pipes can be used to show a real-time output of the process:
+
+```js
+await $`echo 1; sleep 1; echo 2; sleep 1; echo 3;`
+  .pipe(process.stdout)
+```
+
+The `pipe()` method can combine `$` processes. Same as `|` in bash:
+
+```js
+const greeting = await $`printf "hello"`
+  .pipe($`awk '{printf $1", world!"}'`)
+  .pipe($`tr '[a-z]' '[A-Z]'`)
+
+echo(greeting)
+```
+
+Use combinations of `pipe()` and [`nothrow()`](#nothrow):
+
+```js
+await $`find ./examples -type f -print0`
+  .pipe($`xargs -0 grep ${'missing' + 'part'}`.nothrow())
+  .pipe($`wc -l`)
+```
+
+## `kill()`
+
+Kills the process and all children.
+
+By default, signal `SIGTERM` is sent. You can specify a signal via an argument.
+
+```js
+const p = $`sleep 999`
+setTimeout(() => p.kill('SIGINT'), 100)
+await p
+```
+
+## `stdio()`
+
+Specifies a stdio for the process.
+
+Default is `.stdio('inherit', 'pipe', 'pipe')`.
+
+```js
+const p = $`read`.stdio('pipe')
+```
+
+## `nothrow()`
+
+Changes behavior of `$` to not throw an exception on non-zero exit codes.
+
+```js
+await $`grep something from-file`.nothrow()
+
+// Inside a pipe():
+
+await $`find ./examples -type f -print0`
+  .pipe($`xargs -0 grep something`.nothrow())
+  .pipe($`wc -l`)
+```
+
+If only the `exitCode` is needed, you can use [`exitCode`](#exitcode) directly:
+
+```js
+if (await $`[[ -d path ]]`.exitCode == 0) {
+...
+}
+
+// Equivalent of:
+
+if ((await $`[[ -d path ]]`.nothrow()).exitCode == 0) {
+...
+}
+```
+
+## `quiet()`
+
+Changes behavior of `$` to disable verbose output.
+
+```js
+// Command and output will not be displayed.
+await $`grep something from-file`.quiet()
+```
+
+## `timeout()`
+
+Kills the process after a specified timeout.
+
+```js
+await $`sleep 999`.timeout('5s')
+
+// Or with a specific signal.
+await $`sleep 999`.timeout('5s', 'SIGKILL')
+```

@@ -0,0 +1,103 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# Quotes
+
+Bash supports various ways to quote arguments: single quotes, double quotes, and a bash-specific method using C-style
+quotes `$'...'`. Zx prefers the latter approach.
+
+```js
+const name = 'foo & bar'
+await $`mkdir ${name}`
+```
+
+Zx automatically escapes and quotes anything within `${...}`, so there's no need for additional quotes.
+
+The following examples produce the same, correct result:
+
+```js
+await $`mkdir ${'path/to-dir/' + name}`
+```
+
+```js
+await $`mkdir path/to-dir/${name}`
+```
+
+## Array of arguments
+
+Zx can also accept an array of arguments within `${...}`. Each array item will be quoted separately and then joined by a
+space.
+
+```js
+const flags = [
+  '--oneline',
+  '--decorate',
+  '--color',
+]
+await $`git log ${flags}`
+```
+
+## Glob patterns
+
+Because Zx escapes everything inside `${...}`, you can't use glob syntax directly. Instead, Zx provides 
+a [`glob`](api.md#glob) function.
+
+The following example won't work:
+
+```js
+const files = './**/*.md' // [!code error] // Incorrect
+await $`ls ${files}`
+```
+
+The correct approach:
+
+```js
+const files = await glob('./**/*.md')
+await $`ls ${files}`
+```
+
+## Home dir `~`
+
+Zx won't expand the home directory symbol `~` if it's within `${...}`. Use `os.homedir()` for that purpose.
+
+```js
+const dir = `~/Downloads` // [!code error] // Incorrect
+await $`ls ${dir}`
+```
+
+```js
+await $`ls ${os.homedir()}/Downloads` // Correct
+```
+
+```js
+await $`ls ~/Downloads` // Correct, ~ is outside of ${...}
+```
+
+## Assembling commands
+
+If you're trying to dynamically assemble commands in Zx, you might run into limitations. For instance, the following
+approach won't work:
+
+```js
+const cmd = 'rm'
+if (force) cmd += ' -f'
+if (recursive) cmd += ' -r'
+cmd += ' ' + file
+
+await $`${cmd}` // [!code error] // Incorrect
+```
+
+Zx will escape the entire string, making the command invalid. Instead, assemble an array of arguments and pass it to Zx
+like this:
+
+```js
+const args = []
+if (force) args.push('-f')
+if (recursive) args.push('-r')
+args.push(file)
+
+await $`rm ${args}` // [!code hl]
+```

@@ -0,0 +1,34 @@
+::: warning
+This is documentation for zx v7, which is no longer actively maintained.
+
+For up-to-date documentation, see the [latest version](/api) (v8).
+:::
+
+# TypeScript
+
+Configure your project to use [ES modules](https://nodejs.org/api/packages.html#packages_type):
+
+- Set [`"type": "module"`](https://nodejs.org/api/packages.html#packages_type)
+in **package.json**
+- Set [`"module": "ESNext"`](https://www.typescriptlang.org/tsconfig/#module)
+in **tsconfig.json**.
+
+It is possible to make use of `$` and other functions via explicit imports:
+
+```ts
+import { $ } from 'zx'
+```
+
+Or import globals explicitly:
+
+```ts
+import 'zx/globals'
+```
+
+Wrap your code in an async function and call it immediately:
+
+```ts
+void async function () {
+  await $`ls -la`
+}()
+```

@@ -0,0 +1,2 @@
+/cache/
+/build/

@@ -0,0 +1,364 @@
+# 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!"`
+```
+
+Moreover, presets are chainable:
+
+```js
+const $1 = $({ nothrow: true })
+assert.equal((await $1`exit 1`).exitCode, 1)
+
+const $2 = $1({ sync: true }) // Both {nothrow: true, sync: true} are applied
+assert.equal($2`exit 2`.exitCode, 2)
+
+const $3 = $({ sync: true })({ nothrow: true })
+assert.equal($3`exit 3`.exitCode, 3)
+```
+
+### $({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.
+
+```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`)
+```
+
+> ⚠️ `cd` invokes `process.chdir()` internally, so it does affect the global context. To keep `process.cwd()` in sync with separate `$` calls enable [syncProcessCwd()](#syncprocesscwd) hook.
+
+## fetch()
+
+A wrapper around the [node-fetch-native](https://www.npmjs.com/package/node-fetch-native)
+package.
+
+```js
+const resp = await fetch('https://medv.io')
+```
+
+## question()
+
+A wrapper around the [readline](https://nodejs.org/api/readline.html) package.
+
+```js
+const 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
+const 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
+const content = JSON.parse(await stdin())
+```
+
+## within()
+
+Creates a new async context.
+
+```js
+await $`pwd` // => /home/path
+$.foo = 'bar'
+
+within(async () => {
+  $.cwd = '/tmp'
+  $.foo = 'baz'
+
+  setTimeout(async () => {
+    await $`pwd` // => /tmp
+    $.foo // baz
+  }, 1000)
+})
+
+await $`pwd` // => /home/path
+$.foo // still 'bar'
+```
+
+```js
+await $`node --version` // => v20.2.0
+
+const 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
+```
+
+## syncProcessCwd()
+
+Keeps the `process.cwd()` in sync with the internal `$` current working directory if it is changed via [cd()](#cd).
+
+```ts
+import {syncProcessCwd} from 'zx'
+
+syncProcessCwd()
+syncProcessCwd(false) // pass false to disable the hook
+```
+
+> This feature is disabled by default because of performance overhead.
+
+## retry()
+
+Retries a callback for a few times. Will return after the first
+successful attempt, or will throw after specifies attempts count.
+
+```js
+const p = await retry(10, () => $`curl https://medv.io`)
+
+// With a specified delay between attempts.
+const p = await retry(20, '1s', () => $`curl https://medv.io`)
+
+// With an exponential backoff.
+const 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
+const packages = await glob(['package.json', 'packages/*/package.json'])
+```
+
+## which()
+
+The [which](https://github.com/npm/node-which) package.
+
+```js
+const node = await which('node')
+```
+
+If nothrow option is used, returns null if not found.
+
+```js
+const pathOrNull = await which('node', { nothrow: true })
+```
+
+## 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
+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
+const {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)
+```

@@ -0,0 +1,125 @@
+# 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
+```
+
+## No 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
+```
+
+## 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
+```
+
+## Scripts from stdin
+
+The `zx` supports executing scripts from stdin.
+
+```js
+zx << 'EOF'
+await $`pwd`
+EOF
+```
+
+## --eval
+
+Evaluate the following argument as a script.
+
+```bash
+cat package.json | zx --eval 'const v = JSON.parse(await stdin()).version; echo(v)'
+```
+
+## --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
+```
+
+## --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
+`__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
+const {version} = require('./package.json')
+```

@@ -1,93 +0,0 @@
-# Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of
-experience, education, socio-economic status, nationality, personal appearance,
-race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-*   Using welcoming and inclusive language
-*   Being respectful of differing viewpoints and experiences
-*   Gracefully accepting constructive criticism
-*   Focusing on what is best for the community
-*   Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-*   The use of sexualized language or imagery and unwelcome sexual attention or
-    advances
-*   Trolling, insulting/derogatory comments, and personal or political attacks
-*   Public or private harassment
-*   Publishing others' private information, such as a physical or electronic
-    address, without explicit permission
-*   Other conduct which could reasonably be considered inappropriate in a
-    professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, or to ban temporarily or permanently any
-contributor for other behaviors that they deem inappropriate, threatening,
-offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-This Code of Conduct also applies outside the project spaces when the Project
-Steward has a reasonable belief that an individual's behavior may have a
-negative impact on the project or its community.
-
-## Conflict Resolution
-
-We do not believe that all conflict is bad; healthy debate and disagreement
-often yield positive results. However, it is never okay to be disrespectful or
-to engage in behavior that violates the project’s code of conduct.
-
-If you see someone violating the code of conduct, you are encouraged to address
-the behavior directly with those involved. Many issues can be resolved quickly
-and easily, and this gives people more control over the outcome of their
-dispute. If you are unable to resolve the matter for any reason, or if the
-behavior is threatening or harassing, report it. We are dedicated to providing
-an environment where participants feel welcome and safe.
-
-Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the
-Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to
-receive and address reported violations of the code of conduct. They will then
-work with a committee consisting of representatives from the Open Source
-Programs Office and the Google Open Source Strategy team. If for any reason you
-are uncomfortable reaching out to the Project Steward, please email
-opensource@google.com.
-
-We will investigate every complaint, but you may not receive a direct response.
-We will use our discretion in determining when and how to follow up on reported
-incidents, which may range from not taking action to permanent expulsion from
-the project and project-sponsored spaces. We will notify the accused of the
-report and provide them an opportunity to discuss it before any action is taken.
-The identity of the reporter will be omitted from the details of the report
-supplied to the accused. In potentially harmful situations, such as ongoing
-harassment or threats to anyone's safety, we may take action without notice.
-
-## Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
-available at
-https://www.contributor-covenant.org/version/1/4/code-of-conduct.html