shell: expand $? and $$

docs/runtime/shell.mdx

@@ -297,6 +297,21 @@ Use the `$(...)` syntax instead.
 
 ---
 
+## Exit code and process ID (`$?` and `$$`)
+
+`$?` is the exit code of the last statement. After `a && b` or `a || b`, it is the exit code of the operand that ran last. `$$` is the ID of the Bun process that runs the shell.
+
+```js
+import { $ } from "bun";
+
+await $`false; echo $?`; // 1\n
+await $`echo $$`; // the value of process.pid
+```
+
+Both expand inside double quotes. Single quotes or a backslash keep the characters: `'$?'`, `\$?`.
+
+---
+
 ## Environment variables
 
 Set environment variables like in bash:

src/runtime/shell/interpreter.rs

@@ -564,6 +564,7 @@ impl Interpreter {
                 shell_env: EnvMap::init(),
                 cmd_local_env: EnvMap::init(),
                 export_env,
+                last_exit_code: 0,
                 __prev_cwd: cwd_arr.clone(),
                 __cwd: cwd_arr,
                 cwd_fd,
@@ -1801,6 +1802,8 @@ pub(crate) struct ShellExecEnv {
     pub(crate) shell_env: EnvMap,
     pub(crate) cmd_local_env: EnvMap,
     pub(crate) export_env: EnvMap,
+    /// What `$?` expands to. `dupe_for_subshell` copies it: a `$(...)` or a `(...)` does not write it back.
+    pub(crate) last_exit_code: ExitCode,
     pub(crate) __prev_cwd: Vec<u8>,
     pub(crate) __cwd: Vec<u8>,
     pub(crate) cwd_fd: Fd,
@@ -1962,6 +1965,7 @@ impl ShellExecEnv {
             shell_env: self.shell_env.clone(),
             cmd_local_env: EnvMap::init(),
             export_env: self.export_env.clone(),
+            last_exit_code: self.last_exit_code,
             __prev_cwd: self.__prev_cwd.clone(),
             __cwd: self.__cwd.clone(),
             cwd_fd: dupedfd,

src/runtime/shell/mod.rs

@@ -146,7 +146,7 @@ pub(crate) use bun_shell_parser::{escape_8bit, needs_escape_utf8_ascii_latin1};
 pub(crate) mod ast {
     pub(crate) use bun_shell_parser::parse::SmolList;
     use bun_shell_parser::parse::ast as p;
-    pub(crate) use p::{BinaryOp, CondExprOp, IoKind, RedirectFlags};
+    pub(crate) use p::{BinaryOp, CondExprOp, IoKind, RedirectFlags, SpecialParam};
 
     pub(crate) type Script = p::Script<'static>;
     pub(crate) type Stmt = p::Stmt<'static>;

src/runtime/shell/shell_body.rs

@@ -130,6 +130,7 @@ pub(crate) mod test {
         CloseParen,
         Var(&'a [u8]),
         VarArgv(u8),
+        SpecialParam(ast::SpecialParam),
         Text(&'a [u8]),
         SingleQuotedText(&'a [u8]),
         DoubleQuotedText(&'a [u8]),
@@ -145,6 +146,7 @@ pub(crate) mod test {
             match the_token {
                 Token::Var(txt) => TestToken::Var(&buf[txt.start as usize..txt.end as usize]),
                 Token::VarArgv(int) => TestToken::VarArgv(int),
+                Token::SpecialParam(param) => TestToken::SpecialParam(param),
                 Token::Text(txt) => TestToken::Text(&buf[txt.start as usize..txt.end as usize]),
                 Token::SingleQuotedText(txt) => {
                     TestToken::SingleQuotedText(&buf[txt.start as usize..txt.end as usize])
@@ -217,6 +219,9 @@ pub(crate) mod test {
                     w.write_char('}')
                 }
                 T::VarArgv(n) => write!(w, "{{\"VarArgv\":{}}}", n),
+                T::SpecialParam(param) => {
+                    write!(w, "{{\"SpecialParam\":\"{}\"}}", param.as_str())
+                }
                 T::Text(s) => {
                     w.write_str("{\"Text\":")?;
                     encode_json_string(w, s)?;

src/runtime/shell/states/Binary.rs

@@ -81,6 +81,7 @@ impl Binary {
         {
             let me = interp.as_binary_mut(this);
             me.currently_executing = None;
+            me.base.shell_mut().last_exit_code = exit_code;
             if me.left.is_none() && !stop {
                 me.left = Some(exit_code);
             } else {

src/runtime/shell/states/Expansion.rs

@@ -502,6 +502,16 @@ impl Expansion {
                 // SAFETY: `command_ctx` is the live VM ctx; `vm_args_utf8` borrows it.
                 Interpreter::append_var_argv(out, *int, event_loop, command_ctx, vm_args_utf8);
             }
+            ast::SimpleAtom::SpecialParam(param) => {
+                use std::io::Write as _;
+                let value = match param {
+                    ast::SpecialParam::ExitCode => u32::from(shell.last_exit_code),
+                    // A `(...)` and a `$(...)` run in the same process.
+                    ast::SpecialParam::Pid => std::process::id(),
+                };
+                // A write to a `Vec` does not fail.
+                let _ = write!(out, "{value}");
+            }
             ast::SimpleAtom::Asterisk => {
                 meta_offsets.push(out.len() as u32);
                 out.push(b'*');

src/runtime/shell/states/Stmt.rs

@@ -78,6 +78,7 @@ impl Stmt {
         {
             let me = interp.as_stmt_mut(this);
             me.last_exit_code = Some(exit_code);
+            me.base.shell_mut().last_exit_code = exit_code;
             me.idx += 1;
             me.currently_executing = None;
         }

src/shell_parser/json_fmt.rs

@@ -264,6 +264,9 @@ fn write_simple_atom(w: &mut impl Write, s: &SimpleAtom<'_>) -> fmt::Result {
         SimpleAtom::VarArgv(n) => {
             write!(w, "{{\"VarArgv\":{}", n)?;
         }
+        SimpleAtom::SpecialParam(param) => {
+            write!(w, "{{\"special_param\":\"{}\"", param.as_str())?;
+        }
         SimpleAtom::Text(t) => {
             w.write_str("{\"Text\":")?;
             encode_json_string(w, t)?;

src/shell_parser/parse.rs

@@ -667,10 +667,29 @@ pub mod ast {
         }
     }
 
+    /// A parameter that the shell sets: `$?` or `$$`.
+    #[derive(Clone, Copy, PartialEq, Eq)]
+    pub enum SpecialParam {
+        /// `$?`: the exit code of the statement, or the `&&` or `||` operand, that ran last.
+        ExitCode,
+        /// `$$`: the process ID of the shell.
+        Pid,
+    }
+
+    impl SpecialParam {
+        pub const fn as_str(self) -> &'static str {
+            match self {
+                SpecialParam::ExitCode => "$?",
+                SpecialParam::Pid => "$$",
+            }
+        }
+    }
+
     #[derive(Clone)]
     pub enum SimpleAtom<'arena> {
         Var(&'arena [u8]),
         VarArgv(u8),
+        SpecialParam(SpecialParam),
         Text(&'arena [u8]),
         /// An empty string from a quoted context (e.g. "", '', or ${''}). Preserved as an
         /// explicit empty argument during expansion, unlike unquoted empty text which is dropped.
@@ -1630,6 +1649,16 @@ impl<'bump> Parser<'bump> {
                             }
                         }
                     }
+                    Token::SpecialParam(param) => {
+                        let _ = self.expect(TokenTag::SpecialParam);
+                        atoms.push(ast::SimpleAtom::SpecialParam(param));
+                        if next_delimits {
+                            let _ = self.r#match(TokenTag::Delimit);
+                            if should_break {
+                                break;
+                            }
+                        }
+                    }
                     Token::OpenParen | Token::CloseParen => {
                         self.add_error(format_args!(
                             "Unexpected token: `{}`",
@@ -1978,6 +2007,7 @@ pub enum TokenTag {
     CloseParen,
     Var,
     VarArgv,
+    SpecialParam,
     Text,
     SingleQuotedText,
     DoubleQuotedText,
@@ -2029,6 +2059,7 @@ pub enum Token {
 
     Var(TextRange),
     VarArgv(u8),
+    SpecialParam(ast::SpecialParam),
     Text(TextRange),
     /// Quotation information is lost from the lexer -> parser stage and it is
     /// helpful to disambiguate from regular text and quoted text
@@ -2087,6 +2118,7 @@ impl Token {
             Token::CloseParen => b"`)",
             Token::Var(r) => &strpool[r.start as usize..r.end as usize],
             Token::VarArgv(n) => VARARGV_STRINGS[n as usize],
+            Token::SpecialParam(param) => param.as_str().as_bytes(),
             Token::Text(r) => &strpool[r.start as usize..r.end as usize],
             Token::SingleQuotedText(r) => &strpool[r.start as usize..r.end as usize],
             Token::DoubleQuotedText(r) => &strpool[r.start as usize..r.end as usize],
@@ -2654,10 +2686,7 @@ impl<'bump, const ENCODING: StringEncoding> Lexer<'bump, ENCODING> {
                             let var_tok = self.eat_var()?;
 
                             match var_tok.len() {
-                                0 => {
-                                    self.append_char_to_str_pool(u32::from(b'$'))?;
-                                    self.break_word(AddDelimiter::No)?;
-                                }
+                                0 => self.eat_special_param()?,
                                 1 => 'blk: {
                                     let c = self.strpool[var_tok.start as usize];
                                     if c >= b'0' && c <= b'9' {
@@ -2967,6 +2996,7 @@ impl<'bump, const ENCODING: StringEncoding> Lexer<'bump, ENCODING> {
             && match self.tokens[self.tokens.len() - 1].tag() {
                 TokenTag::Var
                 | TokenTag::VarArgv
+                | TokenTag::SpecialParam
                 | TokenTag::Text
                 | TokenTag::SingleQuotedText
                 | TokenTag::DoubleQuotedText
@@ -3391,6 +3421,27 @@ impl<'bump, const ENCODING: StringEncoding> Lexer<'bump, ENCODING> {
         true
     }
 
+    /// After a `$` with no name: lexes `$?` and `$$`. Before any other character the `$` is text.
+    #[cold]
+    fn eat_special_param(&mut self) -> Result<(), LexerError> {
+        let mut chars = self.chars;
+        let next = chars.eat().filter(|c| !c.escaped).map(|c| c.char);
+        let param = if next == Some(u32::from(b'?')) {
+            ast::SpecialParam::ExitCode
+        } else if next == Some(u32::from(b'$'))
+            // `$$(cmd)` stays a `$` followed by `$(cmd)`.
+            && chars.peek().is_none_or(|c| c.escaped || c.char != u32::from(b'('))
+        {
+            ast::SpecialParam::Pid
+        } else {
+            self.append_char_to_str_pool(u32::from(b'$'))?;
+            return self.break_word(AddDelimiter::No);
+        };
+        self.chars = chars;
+        self.tokens.push(Token::SpecialParam(param));
+        Ok(())
+    }
+
     fn eat_var(&mut self) -> Result<TextRange, LexerError> {
         let start = self.j;
         let mut i: usize = 0;

test/cli/run/run-shell.test.ts

@@ -21,6 +21,36 @@ describe.concurrent("run-shell", () => {
     expect(stdout).toEqual("wah\n");
   });
 
+  test("a shell script expands $? and $$", async () => {
+    using dir = tempDir("run-shell-special-params", {
+      "status.sh": 'false\necho $? "$?"\necho $$\n',
+    });
+    await using proc = Bun.spawn({
+      cmd: [bunExe(), join(String(dir), "status.sh")],
+      cwd: String(dir),
+      env: bunEnv,
+      stderr: "pipe",
+      stdout: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
+    expect({ stdout, stderr, exitCode }).toEqual({ stdout: `1 1\n${proc.pid}\n`, stderr: "", exitCode: 0 });
+  });
+
+  test("bun run --shell=bun expands $? in a package.json script", async () => {
+    using dir = tempDir("run-shell-special-params", {
+      "package.json": JSON.stringify({ name: "special-params", scripts: { status: "false; echo $?" } }),
+    });
+    await using proc = Bun.spawn({
+      cmd: [bunExe(), "run", "--shell=bun", "--silent", "status"],
+      cwd: String(dir),
+      env: bunEnv,
+      stderr: "pipe",
+      stdout: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
+    expect({ stdout, stderr, exitCode }).toEqual({ stdout: "1\n", stderr: "", exitCode: 0 });
+  });
+
   test("invalid syntax reports the error correctly", async () => {
     const dir = tmpdirSync("bun-shell-test-error");
     mkdirSync(dir, { recursive: true });

test/js/bun/shell/bunshell.test.ts

@@ -1233,6 +1233,60 @@ booga"
       expect(str).toEqual("bar baz\n");
     });
 
+    describe("$?", () => {
+      TestBuilder.command`echo $?`.stdout("0\n").runAsTest("is 0 at the start");
+      TestBuilder.command`false; echo $?`.stdout("1\n").runAsTest("after a builtin");
+      TestBuilder.command`false; echo "$?" a$?b`.stdout("1 a1b\n").runAsTest("in double quotes and in a word");
+      TestBuilder.command`${BUN} -e "process.exit(42)"; echo $?`.stdout("42\n").runAsTest("after a command");
+      TestBuilder.command`false; true; echo $?`.stdout("0\n").runAsTest("is the status of the last statement");
+      TestBuilder.command`false || echo $?`.stdout("1\n").runAsTest("right of ||");
+      TestBuilder.command`true && false; echo $?`.stdout("1\n").runAsTest("after &&");
+      TestBuilder.command`true | false; echo $?; false | true; echo $?`.stdout("1\n0\n").runAsTest("after a pipeline");
+      TestBuilder.command`if false; then echo no; else echo $?; fi`.stdout("1\n").runAsTest("in an else branch");
+      TestBuilder.command`false; if false; then echo no; fi; echo $?`
+        .stdout("0\n")
+        .runAsTest("after an if that takes no branch");
+      TestBuilder.command`(false); echo $?; false; (echo $?)`.stdout("1\n1\n").runAsTest("out of and into a subshell");
+      TestBuilder.command`false; echo $(echo $?)`.stdout("1\n").runAsTest("into a command substitution");
+      // dash prints 1 here and bash prints 0.
+      TestBuilder.command`false; echo $(true)$?`
+        .stdout("1\n")
+        .runAsTest("a $(...) in the same command does not set it");
+      TestBuilder.command`false; STATUS=$?; true; echo $STATUS`.stdout("1\n").runAsTest("as an assignment value");
+      TestBuilder.command`false; [[ $? == 1 ]] && echo yes`.stdout("yes\n").runAsTest("in [[ ]]");
+      TestBuilder.command`false; echo hi > out_$?.txt`
+        .ensureTempDir()
+        .fileEquals("out_1.txt", "hi\n")
+        .runAsTest("in a redirect target");
+      TestBuilder.command`${{ raw: "false; echo é $?" }}`
+        .stdout("é 1\n")
+        .runAsTest("in a script with a non-ASCII character");
+      TestBuilder.command`false; echo '$?' \$? $\?`.stdout("$? $? $?\n").runAsTest("quoted or escaped stays text");
+      TestBuilder.command`false; echo $${"?"} ${"$?"}`.stdout("$? $?\n").runAsTest("an interpolated value stays text");
+
+      // `$?` does not see the status of an assignment from `$(...)` today. #45074 and #37839 change this row to 1.
+      TestBuilder.command`X=$(false); echo $?`.stdout("0\n").runAsTest("after an assignment from a $(...) that fails");
+      TestBuilder.command`shell_test_no_such_command; echo $?`
+        .stdout("1\n")
+        .stderr("bun: command not found: shell_test_no_such_command\n")
+        .runAsTest("after a command that is not found");
+    });
+
+    describe("$$", () => {
+      TestBuilder.command`echo $$ "$$" $$x`
+        .stdout(`${process.pid} ${process.pid} ${process.pid}x\n`)
+        .runAsTest("is the process ID of bun");
+      TestBuilder.command`echo $(echo $$); (echo $$)`
+        .stdout(`${process.pid}\n${process.pid}\n`)
+        .runAsTest("is the same in $(...) and (...)");
+      TestBuilder.command`${{ raw: "echo é $$" }}`
+        .stdout(`é ${process.pid}\n`)
+        .runAsTest("in a script with a non-ASCII character");
+      TestBuilder.command`echo $$(echo hi)`.stdout("$hi\n").runAsTest("$$( is still a $ and a $(...)");
+      TestBuilder.command`echo '$$' \$\$ $\$`.stdout("$$ $$ $$\n").runAsTest("quoted or escaped stays text");
+      TestBuilder.command`echo $${"$"} ${"$$"}`.stdout("$$ $$\n").runAsTest("an interpolated value stays text");
+    });
+
     test("shell var", async () => {
       const { stdout } = await $`FOO=bar BAR=baz && BAZ=1 ${BUN} -e "console.log(JSON.stringify(process.env))"`;
       const str = stdout.toString();

test/js/bun/shell/exec.test.ts

@@ -42,6 +42,22 @@ describe("bun exec", () => {
     )
     .runAsTest("write a lot of data");
 
+  TestBuilder.command`${BUN} exec ${'false; echo $? "$?"'}`
+    .env(bunEnv)
+    .stdout("1 1\n")
+    .runAsTest("$? is the last exit code");
+
+  test("$$ is the process ID of bun exec", async () => {
+    await using proc = Bun.spawn({
+      cmd: [BUN, "exec", 'echo $$ "$$"'],
+      env: bunEnv,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
+    expect({ stdout, stderr, exitCode }).toEqual({ stdout: `${proc.pid} ${proc.pid}\n`, stderr: "", exitCode: 0 });
+  });
+
   describe("--help works", () => {
     // prettier-ignore
     const programs = [