Graph Expressions

Filter units and stacks based on their dependency relationships using graph traversal operators. This allows you to find components that depend on a target, or components that a target depends on.

Graph-based expressions use the ellipsis (...) operator to indicate graph traversal direction and the caret (^) operator to exclude the target from results.

Include Dependencies

Use ... after a target expression to include the target and all of its dependencies:

# Find 'service' and everything it depends on
terragrunt find --filter 'service...'

• Directory.

  • Directoryservice <— Matched (target)

    • terragrunt.hcl (depends on: db, cache, vpc)
  • Directorydb <— Matched (dependency of service)

    • terragrunt.hcl (depends on: vpc)
  • Directorycache <— Matched (dependency of service)

    • terragrunt.hcl (depends on: vpc)
  • Directoryvpc <— Matched (dependency of service, db, cache)

    • terragrunt.hcl

Include Dependents

Use ... before a target expression to include the target and all components that depend on it:

# Find 'vpc' and everything that depends on it
terragrunt find --filter '...vpc'

• Directory.

  • Directoryvpc <— Matched (target)

    • terragrunt.hcl
  • Directorydb <— Matched (depends on vpc)

    • terragrunt.hcl (depends on: vpc)
  • Directorycache <— Matched (depends on vpc)

    • terragrunt.hcl (depends on: vpc)
  • Directoryservice <— Matched (depends on vpc via db and cache)

    • terragrunt.hcl (depends on: db, cache)

Include Both Directions

Use ... before and after a target expression to include a target, all its dependencies, and all its dependents:

# Find 'db' and its complete dependency graph
terragrunt find --filter '...db...'

• Directory.

  • Directoryvpc <— Matched (dependency of db)

    • terragrunt.hcl
  • Directorydb <— Matched (target)

    • terragrunt.hcl (depends on: vpc)
  • Directoryservice <— Matched (depends on db)

    • terragrunt.hcl (depends on: db, cache)

Exclude Target

Use ^ before a target expression to exclude the target from results. This is useful when you want only the dependencies or dependents, but not the target itself:

# Find all dependents of 'vpc' but exclude 'vpc' itself
terragrunt find --filter '...^vpc'

• Directory.

  • Directoryvpc <— Not matched by ’…^vpc’ (would be matched if …vpc was used)

    • terragrunt.hcl
  • Directorydb <— Matched by ’…^vpc’ (dependent on vpc)

    • terragrunt.hcl
  • Directorycache <— Matched by ’…^vpc’ (dependent on vpc)

    • terragrunt.hcl
  • Directoryservice <— Excluded by ’…^vpc’ (dependent on vpc)

    • terragrunt.hcl

Depth-Limited Traversal

You can limit how many levels of dependencies or dependents to traverse by adding a numeric depth before or after the ellipsis (...) operator. This is useful when you only want immediate or nearby relationships rather than the full transitive closure.

# Find 'service' and only its direct dependencies (1 level deep)
terragrunt find --filter 'service...1'

# Find 'vpc' and only components that directly depend on it (1 level)
terragrunt find --filter '1...vpc'

# Find 'db' with 2 levels of dependencies and 1 level of dependents
terragrunt find --filter '1...db...2'

Given this dependency graph where service depends on db and cache, which both depend on vpc:

• Directory.

  • Directoryvpc

    • terragrunt.hcl
  • Directorydb

    • terragrunt.hcl (depends on: vpc)
  • Directorycache

    • terragrunt.hcl (depends on: vpc)
  • Directoryservice

    • terragrunt.hcl (depends on: db, cache)

Using service...1 (dependencies with depth 1):

• Directory.

  • Directoryvpc <— Not matched (2 hops away, beyond depth limit)

    • terragrunt.hcl
  • Directorydb <— Matched (1 hop from service)

    • terragrunt.hcl (depends on: vpc)
  • Directorycache <— Matched (1 hop from service)

    • terragrunt.hcl (depends on: vpc)
  • Directoryservice <— Matched (target)

    • terragrunt.hcl (depends on: db, cache)

Multiple Targets and Depth

When a filter matches multiple targets, the depth limit applies independently to each target. If a component is reachable from multiple targets at different distances, it will be included if it is within the depth limit of any target.

For example, if target A can reach component X in 3 hops and target B can reach X in 1 hop, with a depth limit of 2, X will be included because it is within 2 hops of target B.

Tip

Graph expressions require dependency/dependent information to work correctly.

When using graph expressions, Terragrunt automatically discovers dependency relationships between components to enable graph traversal. This may add some overhead compared to simple name or path filters, as Terragrunt will need to recursively parse and evaluate HCL files to determine whether there are more dependencies or dependents to include.

Note that this overhead is especially noticeable in dependent graph expressions, as Terragrunt will need to recursively parse all units that could possibly depend on the target. Use this expression judiciously.