Skipping Tasks

Build caching can dramatically speed up your tasks - but you can do even better by using npx turbo-ignore. If your workspace is unaffected by your code changes, you can completely skip executing a task altogether.

Let's say you want to skip the unit tests for your web workspace when there aren't any changes to your web application (or its package dependencies). If you are already using Remote Caching (opens in a new tab), you will probably get a cache hit, but you would still spend time provisioning the CI container, installing npm dependencies, and other things that can take a while.

Ideally, we would do a quick check to see if any of that work needs to happen in the first place.

After we've checked out the repo, but before any other work, we can take a few seconds to check that our web tests have changed since the parent commit.

npx turbo-ignore web --task=test

This command will:

1. Filter for the web workspace.
2. Create the dry output for your test task compared to your parent commit.
3. Parse the output to determine which packages have changed.
4. Exit with a 1 code if changes are detected. Otherwise, exits with a 0.

While you may have been able to hit a >>> FULL TURBO cache for this task, we just saved time with all of the other setup tasks required to run your CI.

Using turbo-ignore

To skip unaffected work, first ensure that your git history is available on the machine. Then, run npx turbo-ignore.

turbo-ignore uses a combination of the --filter and --dry=json flags to find changes from the parent commit to the current commit to identify affected packages. By default, turbo-ignore finds the difference for the build task in the current working directory, but you can customize this behavior with flags.

Here's an example of the command that will be built and run:

npx turbo run build --filter=@example/web...3c8387ffd98b751305fe3f0284befdd00cbd4610 --dry=json

Note that a dry run does not execute the build task. Instead, it checks your packages to see if your code changes will affect your build (or other task) in only a few seconds.

If turbo-ignore finds that the task can be skipped, it will exit the process with a 0 code. If changes have been found, the process will exit with 1.

Customizing behavior

To specify a workspace, you can add it to your command like:

npx turbo-ignore web

where web is your workspace's name running the default build task.

If you'd like to change the task, use the --task flag to specify the task for the command that turbo-ignore will invoke.

Using turbo-ignore on Vercel

To use npx turbo-ignore on Vercel, you can use the Ignored Build Step (opens in a new tab) feature. Vercel will automatically infer the correct arguments to successfully run turbo-ignore.

Customizing behavior

On Vercel, you can specify the --fallback flag to give Vercel a git ref to compare against when the default comparison is not available. By default, Vercel compares to the most recently deployed SHA so this is useful for use cases like avoiding a deploy for the first commit to a branch.