+1
日增长
9,199
stars
464
forks
57
watchers
414
prs
1,004
issues
55
releases
README
sh
A shell parser, formatter, and interpreter.
Supports [POSIX Shell], [Bash], [Zsh], and [mksh]. Requires Go 1.26 or later.
Quick start
To parse shell scripts into a syntax tree, inspect them,
and format them like shfmt does,
see the syntax package.
For one-call helpers with shell semantics,
see the shell package:
split a command line into arguments and quote them back like shlex,
expand $VAR and ~ in strings, and glob with or match case-style patterns.
To run shell scripts without a system shell, including on Windows,
see the interp package;
its handlers allow configuring what scripts can execute and access.
shfmt
go install mvdan.cc/sh/v3/cmd/shfmt@latest
shfmt formats shell programs. See canonical.sh for a
quick look at its default style. For example:
shfmt -l -w script.sh
For more information, see its manpage, which can be
viewed directly as Markdown or rendered with [scdoc].
Packages are available on [Alpine], [Arch], [Debian], [Docker], [Fedora], [FreeBSD],
[Homebrew], [MacPorts], [NixOS], [OpenSUSE], [PyPI], [Scoop], [Snapcraft], [Void] and [webi].
Sponsoring
If this project saves you or your company time, consider
sponsoring me on GitHub.
Monthly tiers include benefits like your logo on a README,
prioritized issues, or direct support in your company's chat app.
One-time tiers offer a call about one of my projects
or a Go consulting or mentorship session.
Contributing
Bug reports and feature requests should be filed as detailed issues,
ideally with an example which reproduces the bug or shows what feature you're after.
Unless you're an active user or contributor to the project, drive-by AI patches
are not helpful. File detailed issues instead.
Caveats
When indexing Bash associative arrays, always use quotes. The static parser
will otherwise have to assume that the index is an arithmetic expression.
sh
$ echo '${array[spaced string]}' | shfmt
:1:16: not a valid arithmetic operator: string
$ echo '${array[weird!key]}' | shfmt
:1:8: reached ! without matching [ with ]
$ echo '${array[dash-string]}' | shfmt
${array[dash - string]}
This does not apply to Zsh, which only decides at run time whether a
subscript is a key or arithmetic, so the parser keeps subscripts as written.
$(( and (( ambiguity is not supported. Backtracking would complicate the
parser and make streaming support via io.Reader impossible. The POSIX spec
recommends to [space the operands][posix-ambiguity] if $( ( is meant.
sh
$ echo '$((foo); (bar))' | shfmt
1:1: reached ) without matching $(( with ))
Unlike Bash, arithmetic expressions are parsed before their words are
expanded, so $((1 ? 1 : $(cmd))) never runs cmd, with a='1 + 2'
$(($a 2)) is 6 rather than 5, and $((1 $op 2)) is a syntax error.
export, let, and declare are parsed as keywords.
This allows statically building their syntax tree,
as opposed to keeping the arguments as a slice of words.
It is also required to support declare foo=(bar).
The entire liTop issues
#93interp: consider adding some coreutils as builtins27 comments · 2017-04-25#80proposal: add option to wrap lines to fit in N columns on a best-effort basis20 comments · 2017-04-12#498v4: syntax: keep alignment of command-continuing backslashes14 comments · 2020-02-10#772interp: unexpected array variable and subshell interaction12 comments · 2021-12-08#658v4: remove syntax.KeepPadding and shfmt -kp12 comments · 2021-01-25#544v4: consider redesigning SpaceRedirects (-sr) into an option to space all operators and delimiters10 comments · 2020-04-18#1151feat: shfmt detects shell type from inline '# shellcheck shell=...'9 comments · 2025-04-09#558syntax: ambiguity when parsing globs in indexed array elements9 comments · 2020-05-03
Discussions
#1424Color?1 comments · 2026-09-25#1344aligning FORCE_COLOR with other CLI tools1 comments · 2026-06-09#1286Changed formatting of array index calculation in 3.13.0: intended or not?2 comments · 2026-03-11#1191Open PR for a `sh` Spack package0 comments · 2025-08-31#1181EditorConfig -- seems to not be used2 comments · 2025-07-31#1166Release schedule2 comments · 2025-06-09#1163What is recommended to break this long line?0 comments · 2025-05-28#1155Skipping formatting per-line0 comments · 2025-04-16
Latest release
v3.14.1 v3.14.1 2026-09-06- syntax - Fix the indentation of heredocs nested inside command substitutions - 1403 - Keep literal tabs in <<- heredoc bodies rather than replacing them with spaces - Don't indent heredocs without dashes nested in <<- ones, whose output no longer parsed - Zsh: don't drop the prefix in short forms like $"$foo" and $+"$foo" - 1405 - interp - Fix the build on 32-bit FreeBSD and NetBSD - expand - Don't let escaped characters such as \ act as glob metacharacters - pattern - Treat unclosed extended operator groups like @(a as literals, avoiding a panic Consider becoming