diff --git a/docs/pages/docs/features/filtering.mdx b/docs/pages/docs/features/filtering.mdx new file mode 100644 index 0000000000000..a514a7529bc64 --- /dev/null +++ b/docs/pages/docs/features/filtering.mdx @@ -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 +``` + + diff --git a/docs/pages/docs/features/meta.json b/docs/pages/docs/features/meta.json index 2ab9ca7f6119d..0a12c1d07d671 100644 --- a/docs/pages/docs/features/meta.json +++ b/docs/pages/docs/features/meta.json @@ -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 + } } diff --git a/docs/pages/docs/features/scopes.mdx b/docs/pages/docs/features/scopes.mdx index e3cd8221f5eb6..c4f86e1169119 100644 --- a/docs/pages/docs/features/scopes.mdx +++ b/docs/pages/docs/features/scopes.mdx @@ -6,6 +6,10 @@ description: Even faster Turborepo builds with scoped tasks. import Callout from "../../../components/callout"; import HeartIcon from "@heroicons/react/solid/HeartIcon"; + + `--scope` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering) instead. + + # 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). diff --git a/docs/pages/docs/reference/command-line-reference.mdx b/docs/pages/docs/reference/command-line-reference.mdx index d9ac26094c76f..e8089cb5d3241 100644 --- a/docs/pages/docs/reference/command-line-reference.mdx +++ b/docs/pages/docs/reference/command-line-reference.mdx @@ -118,6 +118,10 @@ turbo run build --cwd=./somewhere/else #### `--deps` + + `--deps` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#include-dependents-of-matched-packages) instead. + + 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` + + `--include-dependencies` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#include-dependencies-of-matched-packages) instead. + + 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` + + `--scope` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#filter-by-package) instead. + + `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` + + `--since` is deprecated in `1.2.x`. Please use [`--filter`](/docs/features/filtering#filter-by-changed-packages) instead. + + Filter execution based on which packages have changed since a merge-base. ```