From 3c62580529f57127b665d34eb23e98113b19d5bf Mon Sep 17 00:00:00 2001
From: Jarred Sumner <709451+Jarred-Sumner@users.noreply.github.com>
Date: Sat, 2 Mar 2024 01:24:40 -0800
Subject: [PATCH] Add a couple guides

---
 docs/guides/runtime/shell.md                  | 36 +++++++++++++++++++
 .../util/which-path-to-executable-bin.md      | 15 ++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/guides/runtime/shell.md
 create mode 100644 docs/guides/util/which-path-to-executable-bin.md

diff --git a/docs/guides/runtime/shell.md b/docs/guides/runtime/shell.md
new file mode 100644
index 0000000000..8679b7577e
--- /dev/null
+++ b/docs/guides/runtime/shell.md
@@ -0,0 +1,36 @@
+---
+name: Run a Shell Command
+---
+
+Bun Shell is a cross-platform bash-like shell built in to Bun. It provides a simple way to run shell commands in JavaScript and TypeScript.
+
+To get started, import the `$` function from the `bun` package and use it to run shell commands.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+await $`echo Hello, world!`; // => "Hello, world!"
+```
+
+The `$` function is a tagged template literal that runs the command and returns a promise that resolves with the command's output.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+const output = await $`ls -l`.text();
+console.log(output);
+```
+
+To get each line of the output as an array, use the `lines` method.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+for await (const line of $`ls -l`.lines()) {
+  console.log(line);
+}
+```
+
+---
+
+See [Docs > API > Shell](/api/shell) for complete documentation.
diff --git a/docs/guides/util/which-path-to-executable-bin.md b/docs/guides/util/which-path-to-executable-bin.md
new file mode 100644
index 0000000000..9323b8d635
--- /dev/null
+++ b/docs/guides/util/which-path-to-executable-bin.md
@@ -0,0 +1,15 @@
+---
+name: Get the path to an executable bin file
+---
+
+`Bun.which` is a utility function to find the absolute path of an executable file. It is similar to the `which` command in Unix-like systems.
+
+```ts#foo.ts
+Bun.which("sh"); // => "/bin/sh"
+Bun.which("notfound"); // => null
+Bun.which("bun"); // => "/home/user/.bun/bin/bun"
+```
+
+---
+
+See [Docs > API > Utils](/api/utils#bun-which) for complete documentation.