From 7161dedd5a3acc993681d5da251eb694b07d8eff Mon Sep 17 00:00:00 2001
From: Dylan Conway <35280289+dylan-conway@users.noreply.github.com>
Date: Tue, 7 Jan 2025 20:23:25 -0800
Subject: [PATCH] Update `--filter` docs (#16225)

---
 docs/cli/filter.md   | 67 +++++++++++++++++++++++++++++++++-----------
 docs/cli/install.md  | 14 +++++++++
 docs/cli/outdated.md |  2 ++
 docs/cli/run.md      |  4 +--
 4 files changed, 68 insertions(+), 19 deletions(-)

diff --git a/docs/cli/filter.md b/docs/cli/filter.md
index b4ee0dcf3f..38a497548b 100644
--- a/docs/cli/filter.md
+++ b/docs/cli/filter.md
@@ -1,4 +1,51 @@
-Use the `--filter` flag to execute lifecycle scripts in multiple packages at once:
+The `--filter` (or `-F`) flag is used for selecting packages by pattern in a monorepo. Patterns can be used to match package names or package paths, with full glob syntax support.
+
+Currently `--filter` is supported by `bun install` and `bun outdated`, and can also be used to run scripts for multiple packages at once.
+
+## Matching
+
+### Package Name `--filter <pattern>`
+
+Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkg-a`, `pkg-b` and `other`, you can match all packages with `*`, only `pkg-a` and `pkg-b` with `pkg*`, and a specific package by providing the full name of the package.
+
+### Package Path `--filter ./<glob>`
+
+Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `packages/foo`, use `--filter ./packages/foo`.
+
+## `bun install` and `bun outdated`
+
+Both `bun install` and `bun outdated` support the `--filter` flag.
+
+`bun install` by default will install dependencies for all packages in the monorepo. To install dependencies for specific packages, use `--filter`.
+
+Given a monorepo with workspaces `pkg-a`, `pkg-b`, and `pkg-c` under `./packages`:
+
+```bash
+# Install dependencies for all workspaces except `pkg-c`
+$ bun install --filter '!pkg-c'
+
+# Install dependencies for packages in `./packages` (`pkg-a`, `pkg-b`, `pkg-c`)
+$ bun install --filter './packages/*'
+
+# Save as above, but exclude the root package.json
+$ bun install --filter --filter '!./' --filter './packages/*'
+```
+
+Similarly, `bun outdated` will display outdated dependencies for all packages in the monorepo, and `--filter` can be used to restrict the command to a subset of the packages:
+
+```bash
+# Display outdated dependencies for workspaces starting with `pkg-`
+$ bun outdated --filter 'pkg-*'
+
+# Display outdated dependencies for only the root package.json
+$ bun outdated --filter './'
+```
+
+For more infomation on both these commands, see [`bun install`](https://bun.sh/docs/cli/install) and [`bun outdated`](https://bun.sh/docs/cli/outdated).
+
+## Running scripts with `--filter`
+
+Use the `--filter` flag to execute scripts in multiple packages at once:
 
 ```bash
 bun --filter <pattern> <script>
@@ -24,19 +71,7 @@ bun --filter '*' dev
 Both commands will be run in parallel, and you will see a nice terminal UI showing their respective outputs:
 ![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)
 
-## Matching
-
-`--filter` accepts a pattern to match specific packages, either by name or by path. Patterns have full support for glob syntax.
-
-### Package Name `--filter <pattern>`
-
-Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkga`, `pkgb` and `other`, you can match all packages with `*`, only `pkga` and `pkgb` with `pkg*`, and a specific package by providing the full name of the package.
-
-### Package Path `--filter ./<glob>`
-
-Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `pkgs/foo`, use `--filter ./pkgs/foo`.
-
-## Workspaces
+### Running scripts in workspaces
 
 Filters respect your [workspace configuration](https://bun.sh/docs/install/workspaces): If you have a `package.json` file that specifies which packages are part of the workspace,
 `--filter` will be restricted to only these packages. Also, in a workspace you can use `--filter` to run scripts in packages that are located anywhere in the workspace:
@@ -50,8 +85,6 @@ Filters respect your [workspace configuration](https://bun.sh/docs/install/works
 bun run --filter foo myscript
 ```
 
-## Dependency Order
+### Dependency Order
 
 Bun will respect package dependency order when running scripts. Say you have a package `foo` that depends on another package `bar` in your workspace, and both packages have a `build` script. When you run `bun --filter '*' build`, you will notice that `foo` will only start running once `bar` is done.
-
-### Cyclic Dependencies
diff --git a/docs/cli/install.md b/docs/cli/install.md
index 25d46c98a1..060031a35b 100644
--- a/docs/cli/install.md
+++ b/docs/cli/install.md
@@ -81,6 +81,20 @@ Bun supports `"workspaces"` in package.json. For complete documentation refer to
 }
 ```
 
+## Installing dependencies for specific packages
+
+In a monorepo, you can install the dependencies for a subset of packages using the `--filter` flag.
+
+```bash
+# Install dependencies for all workspaces except `pkg-c`
+$ bun install --filter '!pkg-c'
+
+# Install dependencies for only `pkg-a` in `./packages/pkg-a`
+$ bun install --filter './packages/pkg-a'
+```
+
+For more information on filtering with `bun install`, refer to [Package Manager > Filtering](https://bun.sh/docs/cli/install#bun-install-and-bun-outdated)
+
 ## Overrides and resolutions
 
 Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](https://bun.sh/docs/install/overrides) for complete documentation.
diff --git a/docs/cli/outdated.md b/docs/cli/outdated.md
index ec47fd3e4e..0379ab8500 100644
--- a/docs/cli/outdated.md
+++ b/docs/cli/outdated.md
@@ -59,3 +59,5 @@ If you want to do the same, but exclude the `./apps/api` workspace:
 ```sh
 $ bun outdated --filter './apps/*' --filter '!./apps/api'
 ```
+
+Refer to [Package Manager > Filtering](https://bun.sh/docs/cli/filter#bun-install-and-bun-outdated) for more information on `--filter`.
diff --git a/docs/cli/run.md b/docs/cli/run.md
index 35d9a5919b..b1a7891140 100644
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -153,7 +153,7 @@ $ bun run --bun vite
 
 ### Filtering
 
-in monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
+In monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
 
 Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
 For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
@@ -164,7 +164,7 @@ bun run --filter 'ba*' <script>
 
 will execute `<script>` in both `bar` and `baz`, but not in `foo`.
 
-Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter).
+Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter#running-scripts-with-filter).
 
 ## `bun run -` to pipe code from stdin