v0.9.0

Every warning the explanations give is now a problem with a code, a command name that does not run what it suggests gets a hint, code that never runs is faded, and the panel shows how bash reads the line, as the Bash manual does. Scripts can be explained for bash 5.3.

Details and examples: docs/changes/0.9.0.md.

New

• Every warning and caveat the explanations point out (x = 1, rm -rf $DIR/*, local x=$(cmd)…) is also a problem with a code, in the Problems panel, --check, SARIF and the GitHub Action, also in the shell code of other files. Turn them off with bashExplainer.diagnostics.pitfalls.
• New warnings and caveats, among them: curl … | bash, a variable read while it is unset under set -u, a shebang whose options bash refuses (#!/bin/bash -e -u), find . -exec rm {} ;, a trap on INT that does not exit, an assignment to a read-only variable, and cmd || echo "msg" that turns a failure into success.
• A command name that does not run what it suggests gets a hint after it: a function or an alias that hides a builtin or a program, a builtin turned off by enable -n, sudo cd. Turn the hints off with bashExplainer.hints.names. In the panel, every command name has a badge: keyword, builtin, function, alias or program.
• Code that never runs is faded in the editor: a branch whose condition the script has already decided (if false; then …), the skipped side of && or ||, and what follows exit or return. In POSIX mode, a line where bash stops the script is a warning. Turn the fading off with bashExplainer.hints.deadCode.
• The new setting bashExplainer.bashVersion (--bash-version, the Action's bash-version) explains scripts for bash 5.2 (the default) or 5.3: ${ cmd; }, ${| cmd; }, and what bash 5.3 changes in builtins, variables, printf and [ ]. Compatibility: with the default 5.2, a bash 5.3 construct (${ …; }, ${| …; }, shopt -s array_expand_once) is now a warning, and --check exits 1; set bashExplainer.bashVersion to 5.3 to explain it as bash 5.3 runs it.
• The panel has a Reading view: who reads each part of the line, from bash's own reading to each command and each language inside a word, built up in eight steps.
• Meaning shows the value an expansion has where the script sets it for sure (msg="hello world"; echo $msg), and the worked examples use it. A brace sequence names its start, end and increment, and $1 in a string another shell runs says which word it starts as.
• A note that rests on bash's behaviour rather than the Bash manual says so with a chip, with a command to try in your terminal; turn the chips off with bashExplainer.notes.basis. A new note says that $BASH_SUBSHELL does not count the subshell of a pipeline stage.
• The new setting bashExplainer.panel.colors colours the panel like your editor theme. In a remote window (WSL, SSH, a container), Bash Explainer now runs on your local machine, where the themes are.
• Rows in the panel grow and shrink as you fold them, and the row you fold stays where it is on the screen. Turn the motion off with bashExplainer.panel.animations.
• The web page opens and saves files (Ctrl+O, a drop, Ctrl+S), shows a word's card on hover as VS Code does, and sets the file kind of a pasted script from its content. It opens with its logo and a line of shell read as the explainer reads it.
• In bats files, each test is explained as bats runs it (in a process of its own, with set -e, after setup), with the tag comments, functions marked # @test, and the helpers of bats-support, bats-assert and bats-file.
• Worked examples of pipelines start from made-up lines in the real layout of ps aux, ls -l, df -h and others, name the command their input comes from, and mark what the next command reads.

Changed

• Notes say how much they matter: ⚠ Pitfall, ⓘ Caveat or ⓘ Portability, in the editor's warning or info colour. Some squiggles change colour: an unquoted path given to rm is now a warning, and a Dockerfile pipe without pipefail is now information.
• The hover explains the part under the mouse; the whole line opens with Ctrl+K Ctrl+E or the hover's Whole line link. The Language Server's hover starts with the part too.
• Compatibility: the inline summary at the end of the cursor line was removed, and bashExplainer.inline.* no longer has an effect. Use the hover, Ctrl+K Ctrl+E and the name hints instead.
• Compatibility: bashExplainer.highlight.enabled is now true by default, also in the Language Server (before, false). Syntax colouring follows the explanations (aliases, read-only variables, words read as data), and leaves Python files and Dockerfiles to their own language servers.
• Compatibility: --check prints the new pitfalls but exits as before: their warnings fail it only with the new --strict (the Action's strict: 'true'), the Action's warnings output still counts only what fails the step, and its new pitfalls output counts the pitfalls. In the JSON output, an alias's token kind is now alias (it was function).
• Meaning and Reading show lists as the manual reads them: the commands joined by ; and & make one list. Reading also names and groups each construct as the Bash manual does and cites its section (time and ! start one pipeline), with a row for every reserved word and operator. Every variable of bash's says what it is; before, 85 had no explanation.
• The fixes that notes suggest are written for your line, not as a pattern: local x; x=$(cmd), re='\bfoo'; [[ $x =~ $re ]], for f in "$@", "$DIR"/*.
• Some explanations read more clearly: IFS=$'\n\t' names its characters one by one, a brace expansion's words are chips, a special builtin's badge says so, and the shebang says it works only when the file is run as a program.
• A new logo, a speech bubble of [ ] around >_, on the extension, the panel, the web page and the README. The panel's header is a toolbar of icon buttons, as in VS Code's own views, and the web page has the same icons.
• On the web page, the address bar no longer shows the script (share links still work), changing the file kind loads its sample (and asks first when the editor holds your own script), the Problems list starts folded on a phone, and the release page's menu no longer has the Version switch.

Fixed

• Words are expanded as bash does in more places: with the shell options and the IFS in effect (** without globstar), in case patterns, a tilde after :, sequences past the limits of the bash release, line continuations. In scripts for dash, POSIX sh and busybox ash, {a,b} is plain text, as those shells print it; dash also prints $'…' as text, and in sh its value is not known, and zsh scripts are no longer said to split an unquoted variable.
• Tests, redirections and builtins are explained as bash runs them: [ 08 -eq 8 ] is true, cat <<A <<B reads only B, exec >log 2>&1 applies to the shell, exit 1 2 goes on, and builtin cd is the builtin itself. Every option of bash's builtins, and every shopt option, is explained.
• Meaning gives no value, and decides no condition, where bash may skip a command or the script does what the model does not follow (shopt -s compat31, set -k, a redirection that fails, [ -v "$1" ]). Before, it could show a wrong value or say that code never runs.
• Fewer wrong pitfalls: echo === is not taken for x = 1, rm -rf $DIR/* is no warning when the script set DIR, and an alias in a file with no shebang (it may be sourced) or a variable that may come from the environment gets a caveat, not a warning. Each unquoted variable gets its own note, and pitfalls are found under sudo, xargs and a quoted command name too.
• Options and operands are read as each tool reads them: docker run -it is -i -t, tar vf, ps u1, git log --format %H (a value only after =), sed -e … -E, sudo -c. A word past the operands (diff a b c) is an extra operand the command refuses, and find reads its words after quote removal and refuses a path after its expression.
• Worked examples follow the line and print as the tools do: date -d 2024-01-02 +%A, TZ=… date, sort -h, printf '%s\n' {a,b}, git log --graph, sed -n with q or n, and a quoted command name (\sort).
• Shell code in other files: a YAML block (run: |) is read without its indentation, each workflow step, Dockerfile RUN and Makefile recipe line is a shell of its own, and notes name the right line. Before, an indented EOF did not end a here-document, and set -u in one step counted in the next.
• The panel and the web page work with the keyboard and a screen reader: Meaning folds with buttons, a problem opens with Enter, and F6 goes between the editor and the explanation.
• In the panel, a long label no longer squeezes its explanation, a click on a row of another line only folds it, and the hover no longer repeats a problem VS Code shows above it. A control character in a value is a box with its name (LF, TAB). The quick reference lists every command; before, it stopped after 300.
• Other languages' semantic colours are no longer changed by ours (a TypeScript parameter was drawn in keyword blue). The web page keeps the phone layout at every zoom, and its tab icon is legible in a dark browser theme.
• The Marketplace, Open VSX and npm pages show the images and links of the version they describe. Before, they showed the newest images from main, and one was missing.
• A long pipeline is explained at once; before, 20 stages took about 30 seconds. Lines being typed (echo > >g, cat <<) and words such as toString no longer make the explanation fail.

All changes