---
title: Overview
description: Learn how to use the --filter flag to target specific infrastructure
slug: features/filter
sidebar:
  order: 1
---

import FileTree from '@components/vendored/starlight/FileTree.astro';
import { Aside } from '@astrojs/starlight/components';

The `--filter` flag provides a sophisticated querying syntax for targeting specific [units](/features/units) and [stacks](/features/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:

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

Where the result of `find` above might have been:

```bash
$ 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:

<FileTree>
- prod
  - services
    - **web** \<-- Matched by the filter
      - terragrunt.hcl
    - api
      - terragrunt.hcl
  - data
    - db
      - terragrunt.hcl
- dev
  - services
    - web
      - terragrunt.hcl
    - api
      - terragrunt.hcl
  - data
    - db
      - terragrunt.hcl
</FileTree>

## 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](/features/filter/name) | Match units and stacks by their name. |
| [Path](/features/filter/path) | Match units and stacks by their file system path. |
| [Attribute](/features/filter/attributes) | Match units and stacks by their configuration attributes. |
| [Negated](/features/filter/combining#negated-expressions) | Exclude units and stacks using the `!` prefix. |
| [Intersection](/features/filter/combining#intersection-expressions) | Use the `\|` operator to refine results. |
| [Union](/features/filter/combining#union-expressions) | Combine filter results using multiple `--filter` flags. |
| [Graph](/features/filter/graph) | Filter units based on their dependency relationships using graph traversal operators. |
| [Git](/features/filter/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](#special-interactions)):

- [find](/reference/cli/commands/find)
- [list](/reference/cli/commands/list)
- [run](/reference/cli/commands/run)
- [hcl fmt](/reference/cli/commands/hcl/fmt)
- [hcl validate](/reference/cli/commands/hcl/validate)
- [stack run](/reference/cli/commands/stack/run)
- [stack generate](/reference/cli/commands/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'` |

<Aside type="tip" title="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.

</Aside>

## 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:

```bash
# 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.

```bash
# 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.

```bash
# 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
```
