Bash Explainer

A Visual Studio Code extension that explains shell scripts line by line — like regex101, but for bash.

Hover a line and see what every command, option, redirection and ${…} does, with worked examples you can edit. Useful for reading unfamiliar scripts, learning the shell, and teaching it.

No setup, and offline by design: no network, no AI, no telemetry. In English and Japanese.

Quick start

1. Install Bash Explainer from the Visual Studio Marketplace.
2. Open a shell script (.sh, .bash, …).
3. Hover any line — or put the cursor on it and press Ctrl+K Ctrl+E (Cmd+K Cmd+E on macOS).

For a side pane that follows the cursor, click Open in panel at the bottom of the hover.

To try it without installing anything, open the web version, paste a script and move the cursor: the same explanations, in the browser.

What it shows

Ways to show explanations

Turn them on or off by clicking Bash Explainer in the status bar.

Hover

Hover a line to see its breakdown, right where you are reading.

Panel

The panel follows the cursor line by line. Point at a part of the tree to highlight it in the editor.

Inline

A one-line summary at the end of the cursor line.

Installation

• Marketplace: shun-fujioka.bash-explainer
• In VS Code: open the Extensions view (Ctrl+Shift+X / Cmd+Shift+X) and search for Bash Explainer, or run ext install shun-fujioka.bash-explainer from Quick Open (Ctrl+P / Cmd+P).
• Command line: code --install-extension shun-fujioka.bash-explainer
• VSCodium and other editors using Open VSX: open-vsx.org/extension/shun-fujioka/bash-explainer
• No installation: the web version runs in the browser.

Requires VS Code 1.85 or later. There are no native dependencies (the parser is WebAssembly), so it runs wherever VS Code runs.

The panel

The panel works like regex101:

• Edit the examples. Change the input of a worked example — grep and [[ =~ ]] test strings, sed, awk, jq, perl, sort, cut, xargs, whole pipelines — and the output updates as you type.
• See what matched. Matches are highlighted in the input, each capture group in its own colour, the same colour as the group in the explanation; a table shows what \1, \2, … captured.
• Switch the shell or yq for the current file from the header, and see the explanation and warnings change.
• Fold the explanation tree, copy it as Markdown for a review or a document, and open the searchable quick reference of expansions, redirections, tests, variables and commands.

What is explained

Worked examples

Many constructs come with a made-up input and the output it produces. The built-in runners are checked against the real tools (GNU sed and coreutils, gawk, jq, perl, bash, git, yq) in the tests.

Examples appear right under the part they illustrate (see bashExplainer.examples.placement).

Scripts for other shells

Explanations follow bash. When a script is written for another shell, Bash Explainer also points out what that shell does not have, and what behaves differently there:

#!/bin/sh
[[ -n $name ]] && echo -e "hi\t$name"
# ⚠ `[[ ]]` is not POSIX sh (it fails in dash). Instead, use `[ ]`.
# ⚠ `echo -e` is not POSIX sh (it fails in dash). Instead, use `printf` …

• Shells: POSIX sh (naming what fails in dash and busybox ash), dash, ash, yash, ksh, mksh, zsh. What works where was measured with each shell.
• Which shell: from the shebang (#!/bin/sh, #!/usr/bin/env dash, …), a # shellcheck shell= line or the file name — or set bashExplainer.shell.

Shell code in other files

Each snippet is checked for the shell that runs it (/bin/sh for Dockerfiles and Makefiles unless SHELL says otherwise). Choose which kinds of files with bashExplainer.embedded.files.

yq

Three different tools are called yq, each with its own syntax: mikefarah/yq v4, kislyuk/yq (a jq wrapper) and the older mikefarah/yq v3. Bash Explainer tells which one a command is for — from its options, subcommands and functions, and from how yq is installed in the same file — and says so on the line:

yq: explained as mikefarah/yq v4 (v4.22.1 or later). Because: -o json is a mikefarah/yq v4 option; pick is a mikefarah/yq function (jq has none) Works with: mikefarah/yq v4 (v4.22.1 or later) ✓ / kislyuk/yq ✗ (no -o json, pick) / mikefarah/yq v3 ✗ (no jq-style expressions, -o json)

The first release with each feature was measured on every 4.x minor release. When nothing tells, mikefarah/yq v4 is assumed; set bashExplainer.yq.flavor to fix the choice.

Problems panel and quick fixes

Warnings also appear in the Problems panel, so you see them without hovering. Where a rewrite keeps the meaning, a quick fix is offered:

Fixes are offered only when the script's shell lacks the construct, and only when the meaning is kept: [[ $f == *.txt ]] is a pattern match, so it gets no fix. Each rewrite is checked to behave in dash as the original does in bash. To silence a warning, add # bash-explainer disable=<code> on the line before it (or after the code on the same line), # bash-explainer disable-file=<code> anywhere for the whole file, or list the code in bashExplainer.diagnostics.ignore; all matches every warning. Turn the Problems panel entries off with bashExplainer.diagnostics.enabled.

Commands

Settings

Your own commands

In-house tools are shown as external commands until you describe them:

"bashExplainer.customCommands": {
  "deploy": {
    "summary": "Deploy a service to production",
    "options": {
      "-n|--dry-run": "only show what would happen",
      "-e": { "description": "target environment", "takesValue": true }
    },
    "arguments": ["service name"]
  }
}

Limitations

• Explanations are rule-based. Commands that are not in the dictionary are shown as an external command without option details.
• A few constructs are mis-parsed by the underlying grammar, e.g. [[ -f a && $x =~ re ]] (mixing && with =~), and zsh-only syntax such as *(.).

Privacy

Bash Explainer works entirely offline by design:

• No network access. The extension contains no code that opens network connections, and the panel's Content Security Policy blocks external requests.
• No AI. Scripts are parsed with tree-sitter-bash and explained from built-in dictionaries, so the same line always gets the same explanation.
• No telemetry. The extension collects nothing.
• No external processes. Examples are computed by built-in code; your tools are never run.

A CI check fails the build if network or process APIs appear in the packaged extension (latest runs). Integration tests also run the packaged extension in VS Code — on Linux with no network at all — and fail if it opens a connection or starts a process. You can also verify this yourself: the .vsix is a zip archive, and the extension works with networking disabled.

The web version works the same way. GitHub Pages serves the page, but your script is parsed and explained in the browser and sent nowhere; the page's Content Security Policy allows no requests to other sites, and a link to a script carries it after #, which browsers do not send. The same CI check covers the page, and a test opens it in Chromium, blocking every request to other sites, and keeps using it offline.

This describes the extension and its web version, not VS Code, other extensions or your browser. It is provided as is, without warranty (see LICENSE); please evaluate it against your own requirements before using it with sensitive data.

Release notes

See CHANGELOG.md.

Contributing

Issues and pull requests are welcome at github.com/sf624/bash-explainer.

npm install
npm run build      # bundle into dist/ (also copies the wasm files)
npm test           # type check + unit tests
npm run package    # build a .vsix
npm run test:integration   # run the extension in VS Code (downloaded into .vscode-test/)

• Press F5 in VS Code to launch an Extension Development Host with test/fixtures/sample.sh open.
• npm run build:web builds the web version into site/; python3 -m http.server -d site serves it at http://localhost:8000/.
• npx tsx test/dump.ts <file> [en|ja] [line] prints the explanation of every line of a file.
• Tests that compare with real tools use the shells on PATH or in $BASH_EXPLAINER_SHELLS, and the yq releases in $BASH_EXPLAINER_YQ; missing ones are skipped. The web page test needs Chromium (npx playwright-core install --with-deps chromium-headless-shell).
• To add a command, add an entry to src/dict/commands.ts: cmd(japanese, english, [options…], { positional: […] }).
• To release, bump version in package.json, add a section to CHANGELOG.md, and push a tag v<version>. The Release workflow tests and packages it, waits for approval in the release environment, then publishes to the VS Code Marketplace and Open VSX and creates a GitHub Release; see docs/publishing.md for the one-time setup.

License

MIT. Third-party components are listed in THIRD_PARTY_NOTICES.md.