Skip to content

Commit

Permalink
docs: Add doc for running by task ID. (#9412)
Browse files Browse the repository at this point in the history
# DO MOT MERGE CONDITION

2.3 release

### Description

Documenting #9344.

### Testing Instructions

👀
  • Loading branch information
anthonyshew authored Nov 14, 2024
1 parent 649a096 commit dbaf5fb
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 2 deletions.
19 changes: 17 additions & 2 deletions docs/repo-docs/crafting-your-repository/running-tasks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ description: Learn how to run tasks in your repository through the `turbo` CLI.
import { Callout } from '#/components/callout';
import { PackageManagerTabs, Tab } from '#/components/tabs';
import { LinkToDocumentation } from '#/components/link-to-documentation';
import { InVersion } from '#/components/in-version';

Turborepo optimizes the developer workflows in your repository by automatically parallelizing and caching tasks. Once a task is [registered in `turbo.json`](/repo/docs/crafting-your-repository/configuring-tasks), you have a powerful new toolset for running the scripts in your repository:

Expand Down Expand Up @@ -114,18 +115,32 @@ If you want to ensure that one task blocks the execution of another, express tha

## Using filters

While [caching](/repo/docs/crafting-your-repository/running-tasks) ensures you stay fast by never doing the same work twice, you can also filter tasks to run only a subset of [the Task Graph](/repo/docs/core-concepts/package-and-task-graph#task-graph), according to your needs.
While [caching](/repo/docs/crafting-your-repository/running-tasks) ensures you stay fast by never doing the same work twice, you can also filter tasks to run only a subset of [the Task Graph](/repo/docs/core-concepts/package-and-task-graph#task-graph).

There are many advanced use cases for filtering in [the `--filter` API reference](/repo/docs/reference/run#--filter-string) but the most common use cases are discussed below.

### Filtering by package name
### Filtering by package

Filtering by package is a simple way to only run tasks for the packages you're currently working on.

```bash title="Terminal"
turbo build --filter=@acme/web
```

<InVersion version="2.2.4">

You can also filter to a specific task for the package directly in your CLI command without needing to use `--filter`:

```bash title="Terminal"
# Run the `build` task for the `web` package
turbo run web#build

# Run the `build` task for the `web` package, and the `lint` task for the `docs` package
turbo run web#build docs#lint
```

</InVersion>

### Filtering by directory

Your repository might have a directory structure where related packages are grouped together. In this case, you can capture the glob for that directory to focus `turbo` on those packages.
Expand Down
13 changes: 13 additions & 0 deletions docs/repo-docs/reference/run.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,19 @@ Filters can be combined to create combinations of packages, directories, and git
For in-depth discussion and practical use cases of filtering, visit [the Running Tasks page](/repo/docs/crafting-your-repository/running-tasks).
#### Using a task identifier
You can also run a specific task for a specific package in the format of `package-name#task-name`.
```bash title="Terminal"
turbo run web#lint
```
<Callout type="good-to-know">
This will also run the task's dependencies. To run a task without its
dependencies, use [the `--only` flag](#--only).
</Callout>
#### Advanced filtering examples
You can combine multiple filters to further refine your targets. Multiple filters are combined as a union, with negated filters removing packages from the result of the union.
Expand Down

0 comments on commit dbaf5fb

Please # to comment.