Glob Syntax

Purpose and Scope

Turborepo uses file glob patterns whenever a configuration needs to describe a set of files rather than one fixed file. The reference page defines this as the file glob specification used by the turbo command, and frames globs as the mechanism for including or excluding files in different contexts. For a monorepo author, that means glob syntax is not an isolated reference detail: it directly influences what a task considers to be an output, what Turborepo should ignore, and how precisely a task definition describes the files that matter to cache restoration and invalidation.

Sources: apps/docs/content/docs/reference/globs.mdx

The most common reader problem is deciding how broad or narrow a pattern should be. A broad recursive pattern is convenient when a build directory contains many generated subdirectories, while a narrow extension pattern is safer when only a particular file type should be included or excluded. Turborepo’s documentation distinguishes these cases with examples for directory names, directory prefixes, file extensions, recursive matching, and negation. Treat glob strings as part of the task contract: they document which files a task owns, and they help future maintainers reason about why a cache hit can restore particular artifacts.

Sources: apps/docs/content/docs/reference/globs.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

Relevant Source Files

• apps/docs/content/docs/reference/globs.mdx — Defines the public file glob specification, including the pattern table and examples for directory, recursive, extension, negation, and parent-directory matching.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx — Shows a practical turbo.json task configuration in CI where build outputs use recursive and negated glob patterns for Next.js output directories.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx — Provides deployment context for Turborepo on Vercel, where task configuration and remote cache behavior are part of the monorepo workflow.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Explains Remote Caching as a distributed layer that prevents repeated work across local machines and CI, giving context for why accurate outputs matter.
• apps/docs/content/blog/joining-vercel.mdx — Gives historical context for Turborepo’s Vercel-backed remote caching and open-source CLI surface.
• apps/docs/content/blog/2-10.mdx — Describes newer workflow behavior such as deferred input hashing, which reinforces that file selection and hashing are central to reliable task execution.

Glob Pattern Semantics

The reference syntax starts with two simple wildcards. A single asterisk matches all files in the current directory level. A double asterisk recursively matches files and subdirectories. This difference is important when a task writes files only to one known directory layer versus when it may create nested directories. If a pattern is too shallow, Turborepo may not describe the full artifact tree that a task produced. If it is too broad, the configuration may claim ownership over files that are incidental, temporary, or better left outside the task output contract.

Sources: apps/docs/content/docs/reference/globs.mdx

Directory patterns have deliberately different meanings depending on spelling. A pattern with a trailing slash matches that directory and its contents. A bare directory name matches either a file with that name or a directory with that name and its contents. A prefix pattern matches files and directories whose names begin with the prefix, and when the match is a directory, the directory contents are included. These distinctions let a configuration author choose whether the intent is an exact directory, an exact file-or-directory name, or a family of similarly named paths.

Sources: apps/docs/content/docs/reference/globs.mdx

Extension and negation patterns cover two frequent task-definition needs. An extension pattern such as a JavaScript extension match describes files of one type in a directory. A negated pattern excludes matches from the set. The reference calls out that negation applies to the whole glob and automatically applies recursive contents to the end of the defined glob. In practice, this means a negated directory pattern excludes the directory tree, not merely a directory entry. Negation is therefore a high-impact choice and should usually be placed near the positive pattern it is refining.

Sources: apps/docs/content/docs/reference/globs.mdx

Compact Reference

The reference examples illustrate how the same base name can produce different behavior. A recursive directory pattern includes every file below that directory. A trailing-slash directory pattern includes the directory and its contents. A bare directory pattern can also match a file with the same name. A nested recursive pattern scopes recursion under a deeper path. A parent-directory pattern can move up one level and then match another directory. These examples are valuable because many mistakes in Turborepo configuration come from assuming that visually similar strings are interchangeable when they are not.

Sources: apps/docs/content/docs/reference/globs.mdx

Configuration Flow and Outputs

Glob syntax becomes concrete inside task configuration. The GitHub Actions guide shows a root package script that runs build and test tasks through Turborepo, and a turbo configuration where the build task declares its outputs. The documented output list includes a recursive pattern for a Next.js output directory, then negates cache and development subdirectories, and includes another output directory. This pattern set expresses a useful rule: cache the build artifacts that future runs need, but avoid storing framework-internal cache or development-only state as part of the task result.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/reference/globs.mdx

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**", "other-output-dirs/**"],
      "dependsOn": ["^build"]
    }
  }
}

Read this example from left to right. The first output pattern says that the task produces a recursive tree under the framework output directory. The following exclusions remove two subtrees from that output set. The final pattern adds another recursive output directory. Because task outputs are part of what Turborepo can restore from cache, this is more than syntax decoration. It is a statement about which files are reusable build products. When a CI workflow runs the package manager’s build command, the same task contract applies on the runner as it does locally.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

Remote Cache and CI Implications

Remote Caching raises the stakes for good glob choices because artifacts can be shared across machines. The free Vercel Remote Cache announcement describes remote caching as a distributed caching layer that helps developers and CI avoid doing the same work twice. If task outputs are described accurately, a restored cache result can provide the files a later command expects. If outputs include too much, the cache may contain unnecessary or environment-specific data. If outputs include too little, a cache hit may still leave the workspace missing generated files that downstream steps expected to find.

Sources: apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/reference/globs.mdx

The CI guide demonstrates this workflow in a GitHub Actions pipeline: check out the repository, install dependencies, run build, and run test. Remote cache variables are documented as optional environment settings for the job. Glob patterns are not configured in the workflow file itself; they live in the Turborepo task configuration that the workflow invokes. This separation is intentional. The repository owns the task contract, while CI simply executes the same scripts. As a result, changes to output globs should be reviewed like changes to build scripts, because they affect both developer machines and automation.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Vercel’s Turborepo integration adds another deployment-oriented context. The Vercel guide says that Vercel automatically understands a Turborepo monorepo and pre-configures projects to use Vercel Remote Cache. That convenience does not remove the need for accurate task configuration. Instead, it makes repository configuration the source of truth across environments. When a project deploys from a monorepo, the glob patterns that define reusable outputs help the cache layer distinguish meaningful build results from files that should remain local to a particular run.

Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Practical Authoring Guidance

Start by naming the artifact root that the underlying tool writes, then decide whether recursion is required. Build tools commonly write nested directory trees, so recursive patterns are often appropriate for outputs. Linting or type-checking tasks may not produce stable outputs at all, so their configuration may not need output globs. When adding exclusions, put them immediately after the inclusion they refine and keep the reason obvious. Excluding framework caches, development folders, or temporary data keeps the task output focused on artifacts that are safe to reuse and useful to restore.

Sources: apps/docs/content/docs/reference/globs.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

Be careful with bare names and prefixes. A bare directory-like string can match a file or a directory, while a prefix string can match multiple similarly named entries. Those features are useful when the shape is intentional, but they are risky when the repository contains adjacent folders with overlapping names. Prefer the most specific pattern that matches the files a task truly owns. When you need to include a generated tree, use a recursive directory pattern. When you need a single level of files, use a single-level wildcard or an extension match rather than reaching for recursion by default.

Sources: apps/docs/content/docs/reference/globs.mdx

Version and Workflow Signals

The Turborepo release notes for version 2.10 mention deferred input hashing, affected and filter composition, and local cache eviction as workflow improvements. Although that release note is not a glob reference, it reinforces a broader design point: Turborepo’s performance model depends on selecting, hashing, running, and caching work with clear file boundaries. Glob patterns are one of the user-facing ways to draw those boundaries in configuration. When task definitions evolve, revisit glob patterns alongside inputs, outputs, dependencies, and cache settings so the configuration continues to reflect actual repository behavior.

Sources: apps/docs/content/blog/2-10.mdx, apps/docs/content/docs/reference/globs.mdx

Historical and product context points in the blog posts also explain why these details matter to the project. Turborepo’s CLI is open source, and Vercel-backed Remote Caching has been a major part of the workflow story since the project joined Vercel. The glob reference is therefore best read as part of the public API reference, not merely as documentation for a string format. Configuration patterns travel with the repository and are interpreted by the command line in local development, CI, and deployment environments.

Sources: apps/docs/content/blog/joining-vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/reference/globs.mdx

Next Steps

After learning the pattern syntax, review the turbo configuration reference to see every field where file selection affects command behavior. Then inspect your own task outputs and remove stale or overly broad patterns. In CI, confirm that build and test scripts call the same Turborepo tasks developers run locally, so the repository configuration remains the single source of truth. For deployment workflows, read the Vercel and GitHub Actions guides to understand how remote caching connects to those task definitions rather than replacing them.

Sources: apps/docs/content/docs/reference/globs.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx