bashy

README

bashy — a pure-Go Bash 5.3 drop-in

bashy is a single static binary that runs Bash scripts and interactive sessions. It is written entirely in Go (no CGo, no system Bash required) and is a drop-in replacement for bash 5.3 — same command-line flags, same script semantics, same $BASH_VERSION — that passes GNU Bash's own 5.3 test suite (every runnable fixture; see Status below).

It is built on the qiangli/sh fork of mvdan.cc/sh, which carries the Bash 5.3 interpreter work. bashy is the user-facing shell; sh is the library.

Status: bashy passes 100% of GNU Bash's own 5.3 test suite — every measured fixture (86/86: 0 failing, 0 skipped) on Linux and macOS (see docs/TODO.md). That includes job control, coprocesses, signal traps, and locale-aware (non-UTF-8) globbing — features the early goroutine-based runner couldn't do, now implemented.

Known limitations: arithmetic uses the native int width, so 64-bit values on 32-bit builds (GOARCH=386) truncate (a 64-bit-int migration is tracked); and Windows builds and runs but its full test-suite run is still being verified. As in Bash itself (jobs.c vs nojobs.c), OS-level job control is a Unix feature.

POSIX conformance campaign identity

Bashy's licensed Open Group campaign uses VSC-PCTS2016 version 3.1 with the VSC 5.4.1 framework/documentation, configured in the suite's POSIX08 profile (VSC_POSIX_VERSION=200809) with the XSI/X/Open profile disabled (VSC_XOPEN_VERSION=0). The formal certification target for that suite is the 1003.1-2016 Shell and Utilities Product Standard.

That wording is deliberate. IEEE Std 1003.1-2017 is a later publication in the same POSIX.1-2008 / Issue 7 lineage, but it is not the Product Standard name for which VSC-PCTS2016 is authorized. Do not describe this campaign as a “VSC-PCTS2017” or “1003.1-2017 certification” run.

Running the suite provides conformance evidence; it does not by itself make Bashy POSIX certified. Certification and use of an Open Group mark require a separate submission and approval. Current runs are diagnostic campaigns used to find and fix failures before an uninterrupted formal run. See docs/conformance-statement.md for claim scope and docs/vsc-pcts-run-status.md for the public-safe measured status.

Shell regression gates

Shell development has two complementary regression gates:

1. make test-bash-parallel runs the public GNU Bash 5.3 compatibility corpus locally. Its current denominator is 86 fixtures and the required result is 86/86.
2. On the licensed native VSC host, make test-bash-system ARM=<unique-name> in the sibling vsc-pcts-harness-kit runs all 493 POSIX shell TPs against bin/bash, with Bashy's pure-Go command applets excluded from PATH.

The 493-TP arm is relatively inexpensive and is required for release candidates and changes to parsing, expansion, execution, jobs, signals, traps, builtins, redirections, or locale-sensitive shell behavior. It cannot run in ordinary public CI because VSC-PCTS is licensed. After that isolation gate passes, make test-bash in the harness restores the Bashy Go applets and checks shell integration before the larger command-and-utility campaign.

For concurrent agent work, use the isolated test-lane contract in docs/isolated-test-lanes.md. It maps weave/worktree ownership to distinct OCI containers and results, supports multiple simultaneous instances of the same suite or POSIX profile, documents the swappable Ubuntu base, and gives status/cleanup commands.

Product sequence and Bash++ activation

Bashy ships two binaries carrying three named substrates: Classic → Bash++ → Yoke. Classic is the compatible standalone shell (bash) together with the pure-Go userland; Bash++ is the opt-in language extension and the bridge upward; Yoke is the agentic framework. The bash binary is Classic alone; bashy carries all three.

Invocation	Bash++ default	Agentic default
bash with .sh, .bash, or no extension	off	unavailable
bash with .bpp	on	unavailable
bashy, regardless of extension	on	on

Use --bashpp (canonical) or --bash++ to opt in and --no-bashpp to opt out. BASHY_BASHPP=1|0 supplies the environment default; set -o bashpp and set +o bashpp change the mode for subsequently parsed input. Bashy's agentic surface is independently controlled by --agentic / --no-agentic and BASHY_AGENTIC=1|0.

Precedence is explicit CLI → environment → .bpp extension → binary default. Because extended grammar must be selected before a file is parsed, an in-file set -o bashpp cannot enable new syntax retroactively in an already-parsed file. Use a flag, environment setting, .bpp, or #!/usr/bin/env -S bash --bashpp for initial selection.

Why

• No dependencies. One binary. No bash, no shared libraries, no package manager. Drop it on any host (including minimal containers and Windows) and run your scripts.
• Cross-platform. The same shell semantics on Linux and macOS (verified against Bash's test suite); Windows builds and runs, with full verification in progress.
• Embeddable lineage. The engine underneath (mvdan.cc/sh) is a mature, widely-used Go shell library, so behaviour is well-tested and hackable.

Install

Download a release binary

Grab the archive for your platform from the Releases page and put bashy on your PATH:

Platform	Asset
Linux x86-64	bashy-linux-amd64.tar.gz
Linux arm64	bashy-linux-arm64.tar.gz
macOS Intel	bashy-darwin-amd64.tar.gz
macOS Apple Silicon	bashy-darwin-arm64.tar.gz
Windows x86-64	bashy-windows-amd64.zip
Windows arm64	bashy-windows-arm64.zip

# Linux/macOS example
tar -xzf bashy-linux-amd64.tar.gz
sudo install bashy /usr/local/bin/bashy
bashy --version

With Go

go install github.com/qiangli/bashy@latest

From source

If bashy is already installed on the outpost, the source build can dogfood bashy's own tool surface: no host git, curl, wget, or make required. bashy git gets the sources, scripts/bootstrap-siblings.sh uses bashy git for sibling checkouts, and ./bashy dag build runs the build through bashy go (bashy's self-provisioning Go front end):

bashy git clone https://github.com/qiangli/bashy
cd bashy
./scripts/bootstrap-siblings.sh
./bashy dag build          # -> bin/bash and bin/bashy
./bashy dag install        # optional: install into $DHNT_BIN_DIR (~/.local/bin)

On a host build of bashy with the container engine enabled, the same checkout can also be built inside a container with the host filesystem mounted through bashy podman; use that lane when the outpost should not depend on host build packages beyond the already-installed bashy.

The traditional host-tool path also works:

git clone https://github.com/qiangli/bashy
cd bashy
# Bashy resolves four dependencies as flat siblings. This clones each next
# door at the exact SHA pinned in .sibling-pins:
./scripts/bootstrap-siblings.sh
make build          # -> bin/bashy

A reusable Linux OCI base is also available. It preserves the required native launcher plus .real payload and uses a minimal Ubuntu/glibc runtime; see docs/bashy-oci-base.md for build, smoke, and derived image policy. It is the foundation for a future Bash/POSIX + canonical Go coreutils + O3 + verified-toolchain base, not yet an Ubuntu/Alpine parity claim.

For a fresh checkout that wants to dogfood the DAG runner before this checkout's new bin/bashy exists, use the repo-local bootstrap launcher:

./bashy dag build
./bashy dag install   # installs bash/bashy into $DHNT_BIN_DIR; then `bashy dag ...` works
make dag ARGS=build   # equivalent bootstrap path if you prefer make

Usage

bashy script.sh arg1 arg2      # run a script
bashy -c 'echo "$BASH_VERSION"'# run a command string
bashy                          # interactive shell
echo 'echo hi' | bashy         # read a script from stdin

Supported flags

bashy accepts the common Bash invocation flags:

Flag	Meaning
-c <string>	run <string> as a command
-i	force interactive mode
-l, --login	act as a login shell
--posix	POSIX mode
--norc	do not read ~/.bashyrc
--noprofile	do not read profile files
--rcfile, --init-file <f>	use <f> as the interactive startup file
-o <opt>	enable a set option (e.g. errexit, xtrace)
-O <opt>	enable a shopt option
--pretty-print	pretty-print the parsed input
--version	print version and exit

Shell mode selection

Invoked as bash or bashy, the shell starts in GNU Bash 5.3-compatible mode. Invoked with basename sh, it starts in POSIX sh mode. POSIX mode can also be requested with --posix, -o posix, SHELLOPTS=posix, or by the presence of POSIXLY_CORRECT/POSIX_PEDANTIC (including empty values). Command-line -o/+o posix is last-wins unless one of the environment or sh startup conditions forces POSIX mode, matching GNU Bash 5.3.

The complete contract, including strict sh semantics and certification wiring, is documented in Shell mode selection.

Startup files: interactive shells read ~/.bashyrc (or --rcfile); login shells read /etc/profile and ~/.bashy_profile; $BASH_ENV is honoured for non-interactive shells.

Compatibility notes

bashy is a pure-Go runner: subshells are goroutines rather than fork(), and process substitutions use real named pipes. Job control (jobs/fg/bg/kill %n/suspend with stopped-state tracking), coprocesses, and signal traps are implemented and pass Bash's test suite on Unix. Mirroring Bash's own design (jobs.c on Unix, nojobs.c elsewhere), the OS-level job-control machinery is Unix-only; on other platforms it degrades exactly as a no-job-control Bash does.

Two known gaps: arithmetic currently uses the native int width (64-bit on 64-bit platforms), so very large values on 32-bit builds truncate — a tracked int64 migration; and the Windows test-suite run is still being verified. Everything else — parameter expansion, arrays and associative arrays, namerefs, [[ ]], arithmetic, here documents, brace/tilde/glob expansion (locale-aware, including non-UTF-8 charsets such as Big5/Shift-JIS), traps, printf, read, prompt escapes — matches Bash 5.3 and is verified against Bash's own test suite.

Development

See CLAUDE.md for the development workflow and docs/ for the compliance roadmap and per-fixture analyses. The compliance suite is driven by make test-bash (requires a local external/bash-5.3 symlink into a Bash source tree — see CLAUDE.md).

License

BSD 3-Clause (inherited from mvdan.cc/sh). See LICENSE.