Skip to content

shell: add the : builtin (POSIX null command) - #46375

Open
robobun wants to merge 1 commit into
mainfrom
robobun/679f9cf6/shell-colon-builtin
Open

robobun wants to merge 1 commit into
mainfrom
robobun/679f9cf6/shell-colon-builtin

Conversation

@robobun

@robobun robobun commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

Related to #45074

Problem

  • In Bun Shell, : and false || : print bun: command not found: : and exit 1. bash exits 0. A package.json script that is exactly : fails under bun run --shell=bun, the Windows default.
  • Cause: the builtin table shell_builtins! (src/runtime/shell/Builtin.rs:171) has no row for :.

Fix

  • Add the row Colon => (true_::True, ":", b"") and list : in docs/runtime/shell.mdx. : runs the code of true.
  • Words expand and redirects open before a builtin starts, so : > file empties file.
  • Verified: test/js/bun/shell/bunshell.test.ts (new : block), exec.test.ts, test/cli/run/run-shell.test.ts. The merge base fails these 13 tests.
  • Self-reviewed: 5 concerns raised, 4 addressed here. Not done: a lexer error for ${X:?} (see Downsides), and the order note on shell: stop running builtins and their pool work when a script is stopped #46168.

Background

Downsides

  • : "${X:?}" && cmd now runs cmd when X is unset, and : ${X:=v} assigns nothing in silence: Bun Shell passes both forms as text, and only the missing : stopped or flagged those lines. None of 332,630 sampled package.json scripts has such a line (Notes). Real expansion of the forms is a separate change.
  • An executable named : on PATH no longer runs. bash never runs it.
  • Cost: +5 instructions for a command with a one-character name, 0 for other names. .text grows by 256 bytes.
Notes

Before and after (bun exec '<script>', Linux x64)

Script main this PR bash 5.2
: exit 1, bun: command not found: : exit 0 exit 0
false || : and false ||: exit 1, same message exit 0 exit 0
: > out.txt exit 1, no file exit 0, empty file exit 0, empty file
: $(touch g.txt) exit 1, g.txt exists exit 0, g.txt exists exit 0, g.txt exists
: < missing.txt exit 1, command not found exit 1, bun: No such file or directory: missing.txt exit 1
N=$(false || :) && echo ok prints the message and ok prints ok prints ok
"sample": ":" with bun run --shell=bun sample error: script "sample" exited with code 1 exit 0

Only a builtin can run the word. No program named : is on PATH on Linux, and Windows does not allow : in a file name.

Other shapes

  • An alias from : to Kind::True in from_argv0_raw: a redirect error would then name true. With the row, : > $EMPTY prints bun: ambiguous redirect: at `:` .
  • A rule in the parser: it would skip word expansion and redirects.
  • A new colon.rs: it would be a copy of true_.rs. The unit: group of the macro emits no BuiltinState impl for the type, so one type can back two rows. feat: add POSIX null command : as a builtin denoland/deno_task_shell#175 also reuses the command behind true.
  • : is not in posix_disabled, because no system binary exists to run in its place.
  • Every builtin is one row of the table, and the row is the whole source change on main at 9634520.

The ${X:?} guard (X unset, release builds)

Script merge base this PR bash 5.2
: "${X:?}" && echo RAN exit 1, command not found: : prints RAN, exit 0 exit 127
true "${X:?}" && echo RAN prints RAN prints RAN exit 127
: "${X:?}"; echo NEXT the message, then NEXT, exit 0 NEXT, exit 0 exit 127
: ${X:=d}; echo "[$X]" the message, then [] [] [d]
  • Bun Shell does not implement ${X:?word}, ${X:=word} or ${X:-word}. The lexer keeps them as text. The row changes only the lines where the missing : was the thing that failed.
  • A lexer error for ${NAME:? and ${NAME:= would stop these lines before they run. It would also reject text that runs today: sh -c ": \"${X:?need X}\" && echo RAN" passes the form to sh, and sh reports X: need X.
  • An earlier draft of such an error is commit 1200785 on the branch robobun/0377cbbb/shell-param-expansion. It was not proposed, because no maintainer asked for it. Related open work: shell: expand ${NAME} the same way as $NAME #45032 (${NAME}) and shell: expand $? and $$ #45490 ($? and $$).
  • Reach of these lines, from a second sample (the latest package.json of 67,208 npm packages, 332,630 scripts, 2026-10-22): ${NAME:? is in 0 scripts, ${NAME? in 0, ${NAME:= in 14 and ${NAME= in 2. None of those 16 scripts runs :, and none of the 112 scripts that run : holds a ${ form. For comparison, ${NAME:- is in 508 scripts.
  • On the merge base a : line fails with X set and with X unset, so the row takes no working guard away.
  • Other script shells, X unset: deno task (2.9.6) prints RAN for : "${X:?}" && echo RAN and [] for : ${X:=d}; echo "[$X]". The shell of Yarn 4 (@yarnpkg/shell 4.1.3) refuses both lines with a syntax error, also when X is set.
  • A review of that lexer error found against it: it also refuses a guard whose X is set and a branch that never runs. The fix for the forms is real expansion, where ${X:?} fails the command only when X is unset and ${X:=d} assigns.

Order against open PRs

Behavior that does not change

  • X=1 :; echo "[$X]" prints [], as X=1 true does and as bash does outside POSIX mode. dash and bash --posix print [1], because : is a special builtin there.
  • A redirect that fails stops the command before the builtin starts, as for true.

Reach (measured 2026-10-19: the 50,000 most downloaded npm packages and a random sample)

  • 90 of the 112 scripts are exactly :. They cannot pass under Bun Shell today.
  • 17 are cmd || : guards.

Precedent

Cost measurement

  • Binaries: bun run build:release of the merge base 9634520 and of this PR, on linux-x64.
  • Counter: perf_event_open for instructions:u, the event that perf stat -e instructions:u reads. perf and valgrind are not installed on the build machine.
  • Setup: ASLR off (setarch -R), both binaries at paths of the same length, PATH set to one empty directory. Each script is one line repeated 10,000 times. 9 interleaved runs for each binary. The table shows medians. The spread between runs is under 450 instructions. Some runs of the not-found rows are 37,000 or more higher, for both binaries.
Script line merge base this PR delta for each command
true 43,685,415 43,685,383 -32 0
false 43,905,186 43,905,179 -7 0
echo 51,097,819 51,097,829 +10 0
cd . 72,572,255 72,572,265 +10 0
nosuchcmd_zz (not found) 385,342,464 385,342,569 +105 +0.01
x (not found) 380,297,386 380,347,416 +50,030 +5.00
: 380,297,449 (not found) 43,215,100
  • The compiler inlines the lookup into Cmd::transition_to_exec as a jump table on the length of the name. The merge base has entries for the lengths 2 to 8. This PR adds the entry for the length 1, which compares one byte with :. That entry is the +5.
  • A one-character name is never another builtin. Such a command is a program on PATH or it is not found. The not-found path costs about 37,900 instructions.
  • llvm-size of the stripped binary: .text is 81,932,069 bytes at the merge base and 81,932,325 bytes with this PR. No other section changes size. The file is 107,521,760 bytes in both builds.

Tests

  • Merge base, release build: 13 tests fail (10 in bunshell.test.ts, 1 in exec.test.ts, 2 in run-shell.test.ts). Every other test in the three files passes.
  • This PR: the three files pass with the debug ASAN build (bun bd test) and with the release build.
  • Not run: Windows. I have no Windows machine for this change.

`:` is one more row in the `shell_builtins!` table. It runs the code of
`true`: it exits 0 and writes nothing. The shell expands the words and
opens the redirects before a builtin starts, so `: $(cmd)` runs `cmd`
and `: > file` empties `file`.

Before, `:` was not a command. `false || :` printed
`bun: command not found: :` and exited 1.
@coderabbitai

coderabbitai Bot commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 1 minute.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Repository: oven-sh/bun/.coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: d2244afb-2a69-41cf-a340-da1d9ead9aa8
📥 Commits

Reviewing files that changed from the base of the PR and between 9634520 and 373dcc9.

📒 Files selected for processing: 5
  • docs/runtime/shell.mdx
  • src/runtime/shell/Builtin.rs
  • test/cli/run/run-shell.test.ts
  • test/js/bun/shell/bunshell.test.ts
  • test/js/bun/shell/exec.test.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@robobun

robobun commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 5:05 PM PT - Oct 21st, 2026

❌ @robobun, your commit 373dcc9 has some failures in Build #130261 (All Failures)


🧪   To try this PR locally:

bunx bun-pr 46375

That installs a local version of the PR into your bun-46375 executable, so you can run:

bun-46375 --bun

@robobun

robobun commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Status

Reproduced on bun 1.4.3-canary.1+367d939d9 and on main at 9634520 (Linux x64):

$ bun exec ':'; echo "exit=$?"
bun: command not found: :
exit=1
$ bun exec 'false || :'; echo "exit=$?"
bun: command not found: :
exit=1
$ bun exec ': > out.txt'; echo "exit=$?"; ls out.txt
bun: command not found: :
exit=1
ls: cannot access 'out.txt': No such file or directory

A package.json with "sample": ":" fails the same way under bun run --shell=bun sample (error: script "sample" exited with code 1). bash 5.2 and dash exit 0 for each of these lines.

With this PR each line exits 0 and prints nothing, and : > out.txt creates an empty out.txt.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Beyond the inline findings, I also checked two things in src/runtime/shell/Builtin.rs: the unit: group of shell_builtins! emits no BuiltinState impl for its rows, so reusing true_::True for both True and Colon does not produce a conflicting trait impl; and nothing outside the macro in src/runtime/shell matches on the builtin Kind enum by variant name (the only consumer is DISABLED_ON_POSIX in shell_body.rs), so no sibling site needs a Kind::Colon arm.

Extended reasoning...

The diff adds one row to the shell_builtins! table in src/runtime/shell/Builtin.rs mapping : to the existing true implementation, a docs bullet in docs/runtime/shell.mdx, and tests across the $ template API, bun exec, and bun run --shell=bun entry points. It touches no auth, crypto, or injection surface; the new builtin reaches the same word-expansion and redirect code as true. Three confirmed findings are posted inline, including a user-visible behavior shift for scripts that relied on : "${X:?}" failing, which the author left to a maintainer to decide, so this is not an approve.

Findings marked 🟡 are optional suggestions and need no follow-up push.

unit: {
True => (true_::True, "true", b""),
False => (false_::False, "false", b""),
Colon => (true_::True, ":", b""),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Scripts that guard on a required variable with : "${X:?}" && cmd now run cmd even when X is unset, so a deploy or publish step can proceed without its token. Bun Shell does not implement ${NAME:?word} and passes it to the command as literal text; on the base branch the missing : builtin made the whole line exit 1, which kept the guard failing closed. With the row at src/runtime/shell/Builtin.rs:175, : succeeds and && continues. Fix: before or with this row, make the lexer or expander reject ${NAME:?...} (and the sibling :=, :-, :+ forms) with a non-zero exit and an error naming the form, so a required-variable guard can never silently pass.

Why this was flagged

A package.json script or $... template containing : "${TOKEN:?missing TOKEN}" && npm publish, run under bun run --shell=bun (the Windows default) or Bun.$. Bun Shell has no ${NAME:?} support and leaves the text as an ordinary word (the PR description's own table shows true "${X:?}" && echo RAN prints RAN today). After src/runtime/shell/Builtin.rs:175 resolves : to true_::True, Cmd::transition_to_exec at src/runtime/shell/states/Cmd.rs:452 runs the builtin, it exits 0, and the && right side runs with TOKEN unset. On the base branch the same line hits the bun: command not found: : path at src/runtime/shell/states/Cmd.rs:510 and exits 1, so the guarded command never ran. No safeguard exists: from_argv0 has no notion of unsupported parameter expansions, and the only thing that stopped the line was the absent builtin. bash exits 127 with the missing TOKEN message.

Verification: A script that uses the POSIX : "${VAR:?msg}" && cmd guard, run under Bun Shell with VAR unset. src/runtime/shell/Builtin.rs line 175 Colon => (true_::True, ":", b"") makes from_argv0 return Kind::Colon, ignoring all arguments and exiting 0. On base the guard line always fails; after this change it always passes, so the :? guard silently fails open when the variable is missing.

Comment on lines +1526 to +1530
TestBuilder.command`: < missing.txt`
.ensureTempDir()
.exitCode(1)
.stderr_contains("missing.txt")
.runAsTest("fails when its redirect fails");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 (optional) Reviewers get a test that certifies a malformed error line and would still pass if the redirect error prefix changed or disappeared. The : < missing.txt case at test/js/bun/shell/bunshell.test.ts:1529 asserts only stderr_contains("missing.txt"), so the actual output bun: No such file or directory: missing.txt with no trailing newline (src/runtime/shell/Builtin.rs:570) passes unseen. Fix: assert the whole message, newline included, using a stderr callback with a regex that tolerates the Windows absolute path as test/js/bun/shell/bunshell.test.ts:612 already does for cat.

Why this was flagged

The test at test/js/bun/shell/bunshell.test.ts:1526-1530 is the only test in the PR that exercises the builtin stdin-redirect failure path for :. It asserts exit code 1 exactly but stderr only via stderr_contains("missing.txt") (checked with toContain at test_builder.ts:223). The real output comes from src/runtime/shell/Builtin.rs:566-574 and is bun: No such file or directory: missing.txt with no \n; the loose assertion cannot detect that, nor would it detect a changed or missing bun: prefix. The repository review rules require exact messages (toBe over toContain) and warn that a test captured from buggy output certifies the bug; bunshell.test.ts:610-612 already shows the convention for the OS-dependent path: a regex anchored with ^ and \n$ that allows an optional absolute-path prefix. Remedy: replace stderr_contains with .stderr(s => expect(s).toMatch(/^bun: No such file or directory: (.*[\\/])?missing\.txt\n$/)) once the newline is added at Builtin.rs:570.

Verification: Whenever the stdin-redirect error text for : regresses in prefix or formatting, this test still passes. test/js/bun/shell/bunshell.test.ts:1526-1530 asserts .exitCode(1) and only .stderr_contains("missing.txt"). The real output from src/runtime/shell/Builtin.rs:566-574 is bun: No such file or directory: missing.txt with no newline, which the test cannot see. The missing newline is pre-existing (Builtin.rs:570).

Comment on lines +1532 to +1535
TestBuilder.command`: > $EMPTY`
.exitCode(1)
.stderr("bun: ambiguous redirect: at `:`\n")
.runAsTest("is named in a redirect error");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 (optional) On a CI runner that exports a variable named EMPTY, the : > $EMPTY test writes a file named by that value into the test process cwd and then fails on exit code, because the case at test/js/bun/shell/bunshell.test.ts:1532 calls no ensureTempDir and depends on EMPTY being unset or empty. The base suite has the same shape at bunshell.test.ts:1937 for echo, so the new test doubles an environment-sensitive pattern instead of isolating it. Fix: set the variable explicitly with .env({ ...bunEnv, EMPTY: "" }) or use EMPTY= : > $EMPTY, and add .ensureTempDir() so a stray write can never land outside the temp directory.

Why this was flagged

If any CI or developer environment exports EMPTY to a non-empty string, the command at test/js/bun/shell/bunshell.test.ts:1532 expands $EMPTY to that value, Builtin::init_redirections at src/runtime/shell/Builtin.rs:532 sees a non-empty redirection_file, opens and truncates that path relative to the shell cwd, and : exits 0; the assertions at bunshell.test.ts:1533-1534 (exit 1, bun: ambiguous redirect: at \:`\n) then fail. Because no ensureTempDir is called, run() at test/js/bun/shell/test_builder.ts:244 does not set cwd, so the truncated file is created in the test runner's working directory and is left behind. The dismissal pointed to the identical pre-existing pattern at bunshell.test.ts:1937, which is accurate, but the PR adds a second copy rather than isolating the input the way bunshell.test.ts:3740 does with an explicit EMPTY: "" env. Remedy: pin the variable in the test (.env({ ...bunEnv, EMPTY: "" })or aEMPTY=prefix) and add.ensureTempDir()` so the assertion cannot depend on the host environment or write outside the temp directory.

Verification: Trigger: the test runner's environment exports a non-empty variable named EMPTY. The new case at bunshell.test.ts:1532-1535 sets no env, so $EMPTY expands from the inherited process.env. src/runtime/shell/Builtin.rs:532-538 emits "ambiguous redirect" only when redirection_file.is_empty(), so the assertions at 1533-1534 fail. The base has the identical shape at bunshell.test.ts:1937-1940.

@robobun

robobun commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator Author

The Downsides here name : "${VAR:?}" && cmd and : ${VAR:=default}. #46691 expands these forms: ${VAR:?} fails its command, and ${VAR:=default} assigns.

A trial merge of the two branches has no conflict, in either order.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant