Overview

The --filter flag provides a sophisticated querying syntax for targeting specific units and stacks in Terragrunt commands. This unified approach offers powerful filtering capabilities using a flexible query language.

Filter Syntax Overview

The filter syntax allows you to target units and stacks using several different approaches. Usage of the filter flag in a command can look like this:

$ terragrunt find --filter './prod/** | name=web'
prod/services/web

Where the result of find above might have been:

$ terragrunt find
prod/services/web
prod/services/api
prod/data/db
dev/services/web
dev/services/api
dev/data/db

For the following file tree:

• Directoryprod

  • Directoryservices

    • Directoryweb <— Matched by the filter

      • terragrunt.hcl
    • Directoryapi

      • terragrunt.hcl
  • Directorydata

    • Directorydb

      • terragrunt.hcl
• Directorydev

  • Directoryservices

    • Directoryweb

      • terragrunt.hcl
    • Directoryapi

      • terragrunt.hcl
  • Directorydata

    • Directorydb

      • terragrunt.hcl

Filter Expressions

There are several different types of filter expressions, and particular ways in which they can be combined to achieve different results. You can learn more about that below.

Filter Type	Description
Name	Match units and stacks by their name.
Path	Match units and stacks by their file system path.
Attribute	Match units and stacks by their configuration attributes.
Negated	Exclude units and stacks using the ! prefix.
Intersection	Use the | operator to refine results.
Union	Combine filter results using multiple --filter flags.
Graph	Filter units based on their dependency relationships using graph traversal operators.
Git	Filter units and stacks based on Git diffs using Git expressions.

Usage with Commands

The following commands all support the --filter flag using the same filtering syntax (note the section below on special interactions):

• find
• list
• run
• hcl fmt
• hcl validate
• stack run
• stack generate

This flag is intended to be a flexible way to target specific infrastructure that allows you to dry-run infrastructure targeting using discovery commands (like find and list) before running a command that actually affects infrastructure (like run).

Comparison with Queue Control Flags

The --filter flag provides a unified alternative to multiple queue control flags.

Legacy Flag	Filter Equivalent
--queue-include-dir=./path	--filter='./path'
--queue-exclude-dir=./path	--filter='!./path'
--queue-include-external	--filter='{./**}...'
--queue-include-units-reading=shared.hcl	--filter='reading=shared.hcl'

Queue flag aliases

If you are currently using those queue control flags, note that you are actually already using the equivalent filter expressions, as they are aliased internally.

You will generally have a better experience using the filter flag instead, as it provides a more powerful and flexible way to target infrastructure.

Special Interactions

Certain commands have special interactions with the --filter flag that are worth noting.

hcl fmt

Unlike when used for most commands, the --filter flag is used to filter on individual HCL files when used with the hcl fmt.

All other commands use --filter to filter on units and/or stacks (which are directories). As a result, only path-based filter expressions are supported. Attribute-based filters like type=unit or name=my-app are not applicable to file-level operations.

Example:

# Supported: Path-based expressions
terragrunt hcl fmt --filter './prod/**/*.hcl'

# Not supported: Attribute-based expressions
terragrunt hcl fmt --filter 'type=unit'  # This will not work

stack generate

When using --filter with stack generate, filter expressions will only be recognized if they explicitly target stacks. This is to ensure that filters are not over-applied, preventing any stack generation from occurring.

# Supported: Only generate the stacks that match the filter, as we are explicitly indicating that we are targeting stacks.
terragrunt stack generate --filter 'name=prod | type=stack'

# Not supported: This filter will be ignored, as we are not explicitly indicating that we are targeting stacks.
terragrunt stack generate --filter 'name=prod'  # This will not work

The reason for this is that stack generation can also be done automatically as part of other commands, like run, and thus we need to make it clear that we’re trying to control stack generation rather than run behavior.

# This will run any unit named 'vpc'
terragrunt run --all --filter 'vpc' -- plan

# This will run any unit named 'vpc', and prevent stack generation in any stack not named 'dev' (including any stacks named 'vpc')
terragrunt stack run --filter 'vpc' --filter 'name=dev | type=stack' -- apply