この README は
mainブランチの開発版について書いています。公開済みの版より先の機能を含むことがあります。公開済みの版は Marketplace と Open VSX のページで見られます。README を含むソースは、最新リリースのタグにあります。
シェルスクリプトを1行ずつ解説します。シェルスクリプト版の regex101 を目指しています。
行のどこにでもマウスを乗せると、その部分（コマンド・オプション・リダイレクト・${…}）が何をしているかを、書き換えて試せる具体例つきで解説します。知らないスクリプトを読むときにも、シェルを学ぶときにも、教えるときにも役立ちます。
設定不要で、設計上オフラインで動きます。 通信も AI もテレメトリも使いません。日本語と英語に対応しています。
クイックスタート · ブラウザで試す · ユーザーガイド · コマンドライン（英語） · 変更履歴（英語） · English
Bash Explainer は VS Code の拡張機能としてだけでなく、同じ解説と警告をほかの形でも使えます。インストールせずに試せるブラウザ版、コマンドラインツール、他のエディタ向けの Language Server、PR でスクリプトを検査する GitHub Action です。
| 場所 | 使い方 |
|---|---|
| VS Code | Marketplace から Bash Explainer をインストールし、シェルスクリプトを開いて単語にマウスを乗せます。詳しくは クイックスタート と VS Code で使う を参照してください。 |
| VSCodium など Open VSX を使うエディタ | open-vsx.org/extension/shun-fujioka/bash-explainer |
| vscode.dev と github.dev | 同じ拡張が VS Code for the Web でも動きます（GitHub のリポジトリで . を押す）。 |
| ブラウザ（インストールなし） | ブラウザ版 にスクリプトを貼り付けるかファイルを開いて（Ctrl+O、またはエディタにドロップ）、カーソルを動かします。単語にマウスを乗せると、VS Code と同じカードを表示します。詳しくは Web 版 を参照してください。main からビルドした 開発版 もあります（リリース版と異なる場合があります）。 |
| ターミナル | npx bash-explainer deploy.sh:12、または npm install --global bash-explainer。詳しくは cli/README.md を参照してください。 |
| Neovim、Helix、Emacs など LSP に対応したエディタ | bash-explainer --lsp が Language Server として、同じホバー、警告、クイックフィックスを提供します。設定例は In your editor を参照してください。 |
| CI | GitHub Actions で uses: sf624/bash-explainer@v0 とすると、警告が PR の差分に表示されます。他の CI では npx bash-explainer --check を使います。詳しくは In CI を参照してください。 |
| 書いたもの | Bash Explainer の解説 |
|---|---|
tar -czf backup.tgz -C src . |
-c・-z・-f・-C src がそれぞれ何をするか |
cmd 2>&1 > out.log |
標準出力と標準エラー出力の行き先。この書き方ではエラーがファイルに入らないこと |
echo "${file%.*}" |
file=report.tar.gz → report.tar |
sed -E 's/^([a-z]+)=(.*)$/\2=\1/' |
正規表現の部品ごとの意味と、入力例 a=x → 出力 x=a |
#!/bin/sh の中の [[ -f $f ]] |
ⓧ dash では [[ ]] が動かないこと。[ -f "$f" ] へのクイックフィックス付き |
Dockerfile の RUN apt-get update && … |
Dockerfile・Makefile・CI の YAML・Jenkinsfile・package.json・Python・bats のテストの中のシェルも同じように解説 |
| 例 | |
|---|---|
| コマンドとオプション | 約330のコマンド・組み込みコマンド（grep、sed、awk、find、curl、tar、git、docker、apt-get、gpg、systemctl、kubectl、helm、terraform、aws、go など）。まとめたオプション（-rn）、値付きのオプション（-o pipefail、--include=*.sh）、サブコマンド（git commit）、他のコマンドから実行されるコマンド（sudo、xargs、find -exec） |
| 演算子とリダイレクト | |、&&、||、;、&、>、>>、2>&1、&>、ヒアドキュメント、ヒアストリング。リダイレクトの順序の影響も |
| 展開 | ${var:-default}、${file%.sh}、${#array[@]}、$?、$@、$(…)、<(…)、$((…)) を部品に分けて解説 |
| 引数の中の言語 | 正規表現（オプションに応じて BRE・ERE・PCRE）、sed スクリプト、awk プログラム、jq・yq のフィルタ、perl のワンライナー、printf・date の書式、find の条件式、chmod のモード、sort -k・cut -f・tr の指定、getopts・getopt のオプション文字列、git log --pretty・--date |
| 制御構文 | if、for、while、case、関数。ブロック内の行では「for ループ › if 文」のように位置も表示 |
| 定番の書き方と落とし穴 | IFS= read -r、スクリプトのディレクトリを得る書き方、strict mode、trap … EXIT、command -v … >/dev/null 2>&1 など。x = 1、空の DIR での rm -rf $DIR/…、クォートしていない変数、for f in $(ls)、-r のない read、local x=$(cmd)、sudo cmd > /etc/… で何が起きるか |
具体例、他のファイル（Dockerfile・Makefile・CI の YAML・package.json・Markdown・Python・Jenkinsfile・bats のテスト）の中のシェル、yq という名前の3つのツールは、ユーザーガイド で説明しています。sh・dash・zsh などについては bash 以外のシェル向けのスクリプト を参照してください。
- Visual Studio Marketplace から Bash Explainer をインストールします。
- シェルスクリプト（
.sh、.bashなど）を開きます。 - 知りたい単語にマウスを乗せます。行全体の解説は、カーソルを置いて
Ctrl+K Ctrl+E（macOS はCmd+K Cmd+E）を押すか、ホバーの 行全体 をクリックします。
カーソルに追従するサイドペインで見たいときは、ホバーの下の パネルで詳しく見る をクリックします。
ほかのインストール方法（拡張機能ビュー、code --install-extension、Open VSX、vscode.dev）、パネル、コマンド名のヒント、コマンドは VS Code で使う、すべての設定は 設定 を参照してください。
警告は VS Code の「問題」パネルにも表示されるので、マウスを乗せなくても気づけます。コマンドラインツール（--check）、Language Server、GitHub Action からも同じ警告が出ます。意味を変えずに書き換えられる場合は、クイックフィックスも出します（sh のスクリプトの [[ -f $f ]] は [ -f "$f" ] に、read line は read -r line に）。問題には、VS Code と同じく ⓧ エラー・⚠ 警告・ⓘ 情報 の3つのレベルがあります。各レベルの意味、警告を出さない方法、--check と GitHub Action が失敗する場合は 警告とクイックフィックス を参照してください。
Bash Explainer は、設計上すべてオフラインで動きます。通信も、AI も、テレメトリも、外部プロセスも使いません。スクリプトは組み込みのコードで解説するので、同じ行には毎回同じ解説が出ます。Web 版も、スクリプトをブラウザの中で解説し、どこにも送りません。変更のたびにテストで確かめています。詳しくは プライバシー を参照してください。
- ユーザーガイド: VS Code で使う、設定、解説できるもの、bash 以外のシェル向けのスクリプト、警告とクイックフィックス、Web 版、制限事項、プライバシー。
- コマンドラインツール、Language Server、GitHub Action（英語）。
- リリースノート: CHANGELOG.md（英語）。
- 開発: CONTRIBUTING.md（英語）。不具合報告やプルリクエストは github.com/sf624/bash-explainer へどうぞ。
MIT。同梱しているサードパーティのソフトウェアは THIRD_PARTY_NOTICES.md を参照してください。