A GNU Bash-compatible shell implementation written in Rust.
Rubash is an in-progress GNU Bash-compatible shell. It reimplements Bash lexical analysis, parsing, expansion, execution, and builtin behavior in Rust. The project is past the early skeleton stage; current work focuses on closing GNU Bash compatibility gaps, expanding upstream test coverage, and supporting Windows-native shell use cases such as Winuxsh.
Current positioning: Rubash is suitable for compatibility development, testing, research, and validating the Rubash execution engine/API. It is not yet declared production-ready as a login shell or critical script runtime.
The current source package version is 0.3.0. As of 2026-08-22, the latest
real-output Bash ledger is 13/83 PASS and 70 DIFF. This compares each
test's stdout, stderr, and exit status; it must not be conflated with the
87/87 upstream run-* runner result, which compares against the older
.right expectation files. See
docs/compatibility-attribution-20260822.md
for attribution and raw artifacts.
Rubash's GNU Bash syntax and runtime support have progressed far enough to run complex Bash programs. A clean external bashdb checkout now completes the core debugger loop under target/debug/rubash.exe.
Verified bashdb core commands include:
list: show the target script source.step: enter shell function bodies.next: advance to the next source line.where: print the call stack.continue: resume the debugged script.quit: exit the debugger.
This proves coverage for a substantial set of Bash semantics that bashdb depends on: source/., eval, indexed and associative arrays, DEBUG/RETURN/EXIT traps, BASH_SOURCE, BASH_COMMAND, function stacks, functrace/extdebug, path expansion, redirects, /dev/stdin, tty, dynamic fds, parameter expansion, and arithmetic commands.
The boundary is important: the bashdb core workflow is usable, but the complete bashdb command surface is not yet fully certified. The goal is to make as much of bashdb as possible work under Rubash and use bashdb as a real Bash application stress test for finding more compatibility bugs.
- Lexer: Bash-style quoting, escaping, comments, variables, command substitution, arithmetic expansion, here-doc/here-string tokens, and common redirects.
- Parser: Simple commands, pipelines, AND/OR lists, functions, brace/subshell groups,
if,for, arithmeticfor,while,until,case,select,[[ ... ]],coproc, andtimeprefixes. - Executor: External commands, pipelines, redirects, temporary assignments, function calls,
source/.,eval, shebangless script fallback, and Windows/Git Bash path bridging. - Expansion system: Variables, positional parameters, indexed and associative arrays, command substitution, arithmetic expansion, brace expansion, tilde expansion, pathname globbing, common
${parameter...}operators, and case/replacement transforms. - Array semantics: Indexed and associative arrays, compound assignment, element assignment/append, negative indexes, slices,
${arr[@]}/${arr[*]}, and commondeclare/local/export/readonlyinteractions. - Builtins: Common Bash builtins are implemented or wired in, including
alias/unalias,builtin,cd,command,declare/typeset/local,echo,enable,eval,exec,exit,export/readonly,getopts,hash,help,jobs,kill,let,mapfile/readarray,printf,pushd/popd/dirs,pwd,read,return,set,shift,shopt,source/.,test/[,times,trap,type,ulimit,umask,unset, andwait. - Known limitations: Full job control, interactive readline/history, and process-group/terminal control remain host-sensitive. Bash parser and alias reread edge cases, full bashdb command coverage, and residual upstream compatibility cases are still under active compatibility work.
git clone https://github.com/unixwin/rubash.git
cd rubash
cargo build
target/debug/rubash --versioncargo install rubashtarget/debug/rubash path/to/script.sh
target/debug/rubash -c 'echo hello from rubash'bashdb is an external Bash script debugger. Rubash does not embed or vendor bashdb. The verified clean fixture is:
target/bashdb-clean/bashdb-generatedCore smoke test:
export TERM=xterm DARK_BG=0
printf 'list\nstep\nnext\nwhere\ncontinue\nwhere\nquit\n' | \
target/debug/rubash.exe target/bashdb-clean/bashdb-generated --no-highlight target/bashdb-probe-target.shA passing run exits 0, has empty stderr, shows target source for list, enters a function with step, shows the call stack with where, and continues through 42 / done.
The next goal is broad bashdb command coverage under Rubash. When another bashdb command fails, treat it first as a Rubash Bash-compatibility gap to root-cause rather than patching bashdb. See docs/bashdb-debugging-rubash.md for fixture setup, launcher/libdir terminology, and fresh-checkout usage.
Focused tests commonly used for this area:
cargo test --test cli_tests bashdb_compat -- --nocapture
cargo test --test cli_tests source_expands -- --nocapture
cargo test --test cli_tests script_bash_source -- --nocaptureThe full compatibility suite is still expanding. For compatibility work, prefer focused tests and bounded upstream GNU Bash slices instead of unbounded full-suite runs.
docs/bashdb-debugging-rubash.md: bashdb fixture, launcher/libdir explanation, smoke test, and fresh-checkout usage.docs/gnu-bash-compatibility-implementation-plan.md: GNU Bash compatibility implementation plan.docs/issue-suite-diff-analysis.md: upstream test diff analysis.docs/bash-compat-issues.md: compatibility issue list.docs/bash-source-map.md: Bash source and semantic mapping.
- Fix Rubash subsystems by Bash root cause, not by individual expected-output lines.
- Keep bashdb external and clean. Temporary instrumentation is acceptable only for diagnosis and must be reverted.
- bashdb is a high-level script behavior debugger, not a Rust source debugger. Use Rust tooling, logs, instrumentation, and focused tests for
src/**/*.rsinternals. - Full bashdb usability is a development target. Every failing bashdb command is an opportunity to expose and fix a Rubash compatibility gap.
Rubash is licensed under GPL-3.0-or-later. See LICENSE.
Issues, compatibility repros, focused regression tests, and implementation patches are welcome. Read AGENTS.md before compatibility work.
- GitHub Issues: https://github.com/unixwin/rubash/issues
- Discussions: https://github.com/unixwin/rubash/discussions
- GNU Bash team - original Bash implementation
- Trepan-Debuggers/bashdb - external Bash debugger and compatibility stress source
- Rust community - language and tooling
Last updated: 2026-08-22