vercel · jaredpalmer · Apr 7, 2022 · Mar 21, 2022 · Mar 21, 2022 · Mar 22, 2022
@@ -0,0 +1,121 @@
+---
+title: Filtering Packages
+description: Only build the packages you care about
+---
+
+import Callout from "../../../components/callout";
+import HeartIcon from "@heroicons/react/solid/HeartIcon";
+
+# Filtering Packages
+
+Filtering packages allows you to target your tasks to only the packages you care about.
+Turborepo supports a `pnpm`-like `--filter` flag that allows you to select the packages
+that will act as "entry points" into your monorepo's package/task graph.
+You can filter packages by name, directory, include dependents/dependencies, and by changes
+in git history.
+
+`turbo` will run each task against each matched package, ensuring that any dependencies
+are run first, according to the `pipeline` specification in [`turbo.json`](/docs/reference/configuration#pipeline).
+
+## Filter Syntax
+
+Filters specify combinations of package(s)/apps, directories, and git commits to act as entrypoints
+for execution.
+
+Multiple filters can be combined to select distinct sets of targets. Additionally, filters
+can also exclude targets. A target that matches any filter and is not explicitly excluded will
+be in the final entrypoint selection.
+
+Turborepo's filter syntax is based on pnpm's filter syntax, so it should feel familiar to pnpm users.
+
+### Filter by package
+
+Supports exact matches (`--filter=my-pkg`), and globs (`--filter=*my-pkg*`) are supported.
+Scoped packages (`@foo/bar`) can be abbreviated to just the package name (`bar`) as long as the package name
+is unique within the monorepo (e.g. `@foo/bar` exists, but `@baz/bar` does not).
+
+```sh
+# Build 'my-pkg', letting turbo infer task dependencies from the pipeline defined in turbo.json
+turbo run build --filter=my-pkg
+# Build '@foo/bar', letting turbo infer task dependencies from the pipeline defined in turbo.json
+turbo run build --filter=@foo/bar
+# Build all packages that start with 'admin-', letting turbo infer task dependencies from the pipeline defined in turbo.json
+turbo run build --filter=admin-*
+```
+
+### Include dependents of matched packages
+
+Prepend `...` to the filter. If `my-app` depends on `my-lib`, `...my-lib` will select `my-app` and `my-lib`.
+Optionally including a `^` (`...^my-lib`) will select all of `my-lib`'s dependents, but not `my-lib` itself. In this case, just `my-app` will be
+selected.
+
+```sh
+# Test 'my-lib' and everything that depends on 'my-lib'
+turbo run test --filter=...my-lib
+# Test everything that depends on 'my-lib', but not 'my-lib' itself
+turbo run test --filter=...^my-lib
+```
+
+### Include dependencies of matched packages
+
+Append `...` to the end of the filter. If `my-app` depends on `my-lib`, `my-app...` will select `my-app` and `my-lib`.
+Optionally including a `^` (`my-app^...`) will select all of `my-app`'s dependencies, but not `my-app` itself. In this case, just `my-lib` will be selected.
+
+```sh
+# Build 'my-app' and its dependencies
+turbo run build --filter=my-app...
+# Build 'my-app's dependencies, but not 'my-app' itself
+turbo run build --filter=my-app^...
+```
+
+### Filter by directory or directory tree
+
+Supports exact matches (`--filter=./apps/docs`) and globs (`--filter=./apps/*`).
+When combined with other components, must be enclosed in `{}` (`--filter=...{./libs/*}`).
+
+```sh
+# Build all of the packages in the 'apps' directory
+turbo run build --filter=./apps/*
+# Build all of the packages in the 'libs' directory, and all the packages that depends on them
+turbo run build --filter=...{./libs/*}
+```
+
+### Filter by changed packages
+
+Use the set of files changed since a specified commit to calculate packages. Enclose references in
+`[]`. For example, `--filter=[HEAD^1]` will select all packages that have changed in the most recent
+commit.
+
+You can use [`--ignore`](/docs/reference/command-line-reference#--ignore) to specify changed files to be ignored in the calculation of which packages have changed.
+
+You can additionally prepend the commit reference with `...` to match the dependencies of other components
+against the changed packages. For instance, to select `foo` if any of `foo`'s dependencies have changed in the last commit,
+you can pass `--filter=foo...[HEAD^1]`. Note that this feature is different from `pnpm`'s syntax.
+
+```sh
+# Test everything that changed in the last commit
+turbo run test --filter=[HEAD^1]
+# Build everything that depends on changes in branch 'my-feature'
+turbo run build --filter=...[origin/my-feature]
+# Build '@foo/bar' if it or any of its dependencies changed in the last commit
+turbo run build --filter=@foo/bar...[HEAD^1]
+# Test each package in the '@scope' scope that is in the 'packages' directory, if it has changed in the last commit
+turbo run test --filter=@scope/*{./packages/*}[HEAD^1]
+```
+
+### Excluding packages
+
+Prepend `!` to the filter. Matched packages from the entire filter will be excluded from the set of targets.
+For example, match everything except `@foo/bar`: `--filter=!@foo/bar`. Note that you may need to escape `!` as appropriate for your shell (e.g. `\!`).
+
+```sh
+# Build everything except '@foo/bar'
+turbo run build --filter=!@foo/bar
+# Build all of the packages in the 'apps' directory, except the 'admin' package
+turbo run build --filter=./apps/* --filter=!admin
+```
+
+<Callout type="idea" icon={<HeartIcon className="mt-1 h-5 w-5 text-gray-400" aria-hidden="true" />}>
+Turborepo's Filter API design and docs were/are inspired by 
+[pnpm](https://pnpm.io/filtering)
+</Callout>
@@ -1,6 +1,9 @@
 {
   "pipelines": "Pipelines",
-  "scopes": "Scoped Tasks",
+  "filtering": "Filtering Packages",
   "caching": "Caching",
-  "remote-caching": "Remote Caching (Beta)"
+  "remote-caching": "Remote Caching (Beta)",
+  "scopes": {
+    "hidden": true
+  }
 }
@@ -6,6 +6,10 @@ description: Even faster Turborepo builds with scoped tasks.
 import Callout from "../../../components/callout";
 import HeartIcon from "@heroicons/react/solid/HeartIcon";
 
+<Callout type="error">
+  `--scope` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering) instead.
+</Callout>
+
 # Scoped Tasks
 
 Scoping task execution can speed up the process especially if there are distinct clusters of packages that are not related to each other within your repository. Turborepo has a `scope` option that allows the task running to proceed up to the packages found that matches the `scope` argument. It's useful to think of `scope` as an "entry point" into your monorepo's package/task graph. This is a string matcher based on the name of the packages (not the package path).

@@ -118,6 +118,10 @@ turbo run build --cwd=./somewhere/else
 
 #### `--deps`
 
+<Callout type="error">
+  `--deps` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#include-dependents-of-matched-packages) instead.
+</Callout>
+
 Defaults to `true`. Include dependent packages/apps consumers in the execution.
 
 ```sh
@@ -146,6 +150,25 @@ Task details include:
 - `dependencies`: Tasks that must run before this task
 - `dependents`: Tasks that must be run after this task
 
+#### `--filter`
+
+`type: string[]`
+
+Specify combinations of package(s)/apps, directories, and git commits to act as entrypoints
+for execution.
+
+Multiple filters can be combined to select distinct sets of targets. Additionally, filters
+can also exclude targets. A target that matches any filter and is not explicitly excluded will
+be in the final entrypoint selection.
+
+For more detailed information about the `--filter` flag and filtering, refer to the [dedicated page in our documentation](/docs/features/filtering-packages)
+
+```sh
+turbo run build --filter=my-pkg
+turbo run test --filter=...^@scope/my-lib
+turbo run build --filter=./apps/* --filter=!./apps/admin
+```
+
 #### `--graph`
 
 `type: string`
@@ -221,6 +244,10 @@ Just a quick overview.
 
 #### `--include-dependencies`
 
+<Callout type="error">
+  `--include-dependencies` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#include-dependencies-of-matched-packages) instead.
+</Callout>
+
 Default `false`. When `true`, `turbo` will add any packages that the packages in the current execution scope _depend_ on (i.e. those declared in `dependencies` or `devDependencies`).
 
 This is useful when using `--scope` in CI as it guarantees that every dependency needed for the execution scope is actually executed.
@@ -286,6 +313,10 @@ turbo run dev --parallel --no-cache
 
 #### `--scope`
 
+<Callout type="error">
+  `--scope` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#filter-by-package) instead.
+</Callout>
+
 `type: string[]`
 
 Specify/filter package(s)/apps to act as entry points for execution. Globs against `package.json` `name` field (and not the file system.)
@@ -307,6 +338,10 @@ turbo run build --serial
 
 #### `--since`
 
+<Callout type="error">
+  `--since` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#filter-by-changed-packages) instead.
+</Callout>
+
 Filter execution based on which packages have changed since a merge-base.
 
 ```