rubash
The embeddable GNU Bash 5.3-compatible engine: lexer, parser, expansion, execution and builtins all in-process, targeting byte-level compatibility with GNU Bash 5.3.0, native on Windows. rubash itself is not a shell product — it is the engine; the interactive product (niubash) is built on top of it.
Why rubash
Want to give an editor, test framework or agent host "a library that runs real bash scripts"? Until now there were two roads: link a ported bash with a POSIX emulation layer (an MIT project cannot swallow GPL plus msys-2.0.dll), or use a toy shell subset. rubash is the third road: an MIT-licensed, zero-emulation-layer engine whose semantic alignment is measured byte-for-byte against 83 GNU upstream corpora — installed as a dependency in your project, not as an emulation layer in your users' systems.
中文原文 · Chinese original（4 张卡片全文）
- Rubash 本身不是 shell 产品——从零用 Rust 写的 GNU Bash 语义引擎：词法、解析、展开、执行、内建全部进程内、headless；交互式 shell 建在引擎之上：niubash 内嵌 rubash 承担全部 bash 语义。
- 为什么不是移植 bash——Git Bash/MSYS2 装的是骑在 msys-2.0.dll 上的移植 bash；rubash 没有这一层：一个自包含二进制直接说 Win32；GPL 代码零拷贝是成文红线。
- 兼容是台账，不是口号——83 套上游语料 true-baseline 双向测量：83/83 通过、82 套逐字节一致；modernish 166/166、bash-completion 452/452、oh-my-bash 252/252——全部钉成 CI 回归夹具。
- 语义模型平台中立——三层模型刻意与平台无关；Linux 原生构建并运行（WSL 内实测 19/24 套逐字节一致且在收敛），macOS CI 编译绿；Android 双目标进 CI 交叉检查。
Core features
62 real builtins with full GNU Bash 5.3 coverage; the zero-fork three-tier execution; 12 inlined file commands plus pipeline-inline arms; a selectable platform identity (MSYS-compatible persona vs honest native); an engineering surface for agents and debugging (function-level profiler, DAP-first debugger design); and a hard cross-platform CI gate. Full list (Chinese):
中文原文 · Chinese original（六条特性全文）
- 62 个真内建，全覆盖 GNU Bash 5.3——61 个内建全覆盖、无缺失，唯一扩展是 env；三层分发由仓内文档同步测试守护——改白名单不更新文档，cargo test 直接失败。
- 零 fork 的三层执行——（ list ）与 $( ) 从不产生进程；真句柄 fd 表以 DuplicateHandle 共享同一内核文件对象；真进程只在真进程边界。
- 12 个内联文件命令 + 管道内联臂——pwd、printf、mkdir、touch、chmod、cp、rm、rmdir、cat、sed、mkfifo、tty 引擎内联执行，echo | cat 这类管道一整个零 fork。
- 可选择的平台身份——Windows 默认 MSYS2 兼容 persona，RUBASH_IDENTITY=native 切到诚实原生身份；persona 在 --help、--identity 与 README 处处披露，永不静默。
- 为 agent 与调试准备的工程面——脚本级函数级 profiler（确定性插桩）已合并；DAP-first 调试器设计定稿；引擎跑得动 bashdb 核心调试循环。
- 跨平台 CI 硬门——ubuntu / macOS / Windows x64 三个真 runner，四目标交叉检查；单测 698 通过 / 0 失败；跨平台缺口有公开台账。
Install & quick start
Embed as a dependency (the engine is a library; the org's three crates on crates.io — rubash, niubash, niubash-runtime — are all at 1.4.0):
cargo add rubashBuild the reference CLI from source:
git clone https://github.com/unixwin/rubash.git && cd rubash && cargo buildRun a script (the reference CLI's usage — the entry shape of the compatibility harness):
target/debug/rubash path/to/script.sh
For a first encounter, run the compatibility suite directly:
MSYS_NO_PATHCONV=1 wsl bash scripts/true-baseline.sh — the engine's catchphrase is
"measured"; the benchmark scripts are part of the product.
Deep dive: embedding, execution model and the compatibility ledger
中文原文 · Chinese original（嵌入 / 执行模型 / 兼容台账 三节全文）
嵌入方式与 1.5.0 蓝图：今天的 1.4.0 已经把引擎当依赖用——niubash 是第一个完整消费者，driver 级 API 已在生产。1.5.0 蓝图（RFC 已合并，PR rubash#814）：四层 workspace 拆分（rubash-core / rubash-driver / rubash-interactive / rubash facade）、Session 级稳定嵌入 API、846 处 env-IPC 形态逐族替换为 typed bridges。验收标准：外部编辑器能嵌入引擎而不需要知道 Windows 的存在。
三层执行模型：POSIX fork() 在 Win32 没有等价物；rubash 复刻 fork 的语义而非机制——进程内子壳复制变量与 fd 表、真句柄 fd 表实现 POSIX dup 语义、真进程只在真进程边界出现。细读见 执行模型：零 fork 三层；性能见 性能特征与 基准页。
兼容台账与 vendored 源码方法论：语义判定的一手依据是仓内 vendored 的 GNU bash-5.3 源码（third_party/bash）：每个行为主张必须给 file:line 坐标；GPL 代码零拷贝红线成文于 docs/PROVENANCE.md；发布包不携带 third_party。台账见 兼容总览；超出 GNU 套件的部分同样钉成 CI 夹具。
Measured numbers
Every row is a real-machine, reproducible measurement; "N× faster" figures for array writes are against the previous engine, with the gap to GNU listed separately — wins and losses both shown.
| Metric | rubash | Framing / contrast | Source |
|---|---|---|---|
| GNU Bash upstream corpora | 83/83 suites pass, 82 byte-identical | The only residual = GNU's own coproc race | rubash README:17 · full rerun 2026-10-12 |
| nvm.sh parsing (heavy lexer) | gap to GNU 720x → 8x (heavy-lexer bytes −40%) | Engineering-progress framing: gap closing, not "8x faster" | rubash PR #486 (issue #281) |
| Associative-array element write, K=5000 | O(n²)→O(1), single write 45× faster | Gap to GNU 445x → 9.9x | rubash PR #650 (issue #618) |
| Indexed-array overwrite, K=5000 | 177× faster | Gap to GNU 674x → 3.8x; also fixes the O(n²) tokenizer (10001 segments 563ms→17.8ms) | rubash PR #652 (issue #616) |
| Single-spawn cost | rubash 1.183 ms | GNU 1.121 ms — even (the Win32 CreateProcess floor, shown honestly) | unix-spawn-cost-20261012.md (min-of-3) |
Release feed
| Version | Date | Summary |
|---|---|---|
Unreleased (in development) | — | Function-level profiler (#815), scalar-assignment fast-path slicing (#609), set -E ERR-trap nesting semantics and active-console read three-way alignment (#720/#806), multiple hot-path de-allocation optimizations. |
1.4.0 | 2026-10-10 | Login-shell startup chain, real readline REPL, GNU cp port, stty builtin; suite deltas 3427 → 2072 lines (−40%); crates.io packaging slimmed (15.6 MB → 8.9 MB). |
0.3.0 | 2026-08-22 | Compatibility attribution ledger published (true deltas / host fixtures / legacy runner expectations); compound-statement prefix-alias fix; process-substitution regression coverage expanded; tag-triggered automatic Release. |
Latest entries from changelogs.json (the rubash repo's CHANGELOG.md); the full feed lives on the changelog.
Related links
On this site
- niubash product page — rubash's first complete host (the reference integration)
- Execution model: three tiers, zero forks · Compatibility: 83/83 · Performance profile
- Benchmarks (8/8 workloads all faster than Git Bash, same session) · Changelog
Off site
FAQ
What is the relation between rubash and niubash?
rubash is the language engine of niubash — it is what executes the bash syntax. It also stands alone: published on crates.io (1.4.0, cargo add rubash) as an embeddable GNU Bash 5.3-compatible engine.
How do I embed rubash in my own program?
cargo add rubash and use it as a library. The stable embedding API and the four-tier workspace split (core/driver/interactive/facade) target 1.5.0 — the design doc is merged (rubash#814), moving 846 env-IPC sites to typed bridges.
How many builtins does rubash cover?
All 61 builtins of GNU Bash 5.3 plus the env extension (62); 12 high-frequency file commands execute inline with a pipeline inline arm — an echo | cat pipeline creates zero processes end to end.
What does "83/83 GNU suites" mean?
All 83 upstream GNU Bash test suites pass on real hardware Windows, with 82 suites byte-identical to GNU Bash 5.3 output; the single residual line (nameref) is proven byte-by-byte to be GNU's own coproc reap race. Compatibility is measured, not claimed: a nightly patrol additionally sweeps 2,686 real-world ecosystem repos / 9,701 assets.
How is the performance?
One-shot execution (niu -c true) is 19.8 ms after dedicated optimization; niu-git starts in ~14 ms (Git Bash: 45–103 ms); command-substitution and subshell workloads run 13–62x faster than GNU bash. Every number ships with its measurement method and reproducible artifacts — see Benchmarks (/benchmarks/).