---
name: filter
description: Filter configurations using a flexible query language
type: list(string)
---

import {Aside} from '@astrojs/starlight/components';

The `--filter` flag provides a sophisticated querying syntax for targeting specific [units](/docs/features/units) and [stacks](/docs/features/stacks) in Terragrunt commands.

## Usage

```bash
terragrunt find --filter 'app*'
terragrunt list --filter './prod/** | type=unit'
terragrunt run --all --filter './prod/**' -- plan
terragrunt hcl fmt --filter './prod/**'
terragrunt hcl validate --filter 'type=unit'
```

### Name-Based Filtering

Match configurations by their name using exact matches or glob patterns:

```bash
# Exact match
terragrunt find --filter app1

# Glob pattern
terragrunt find --filter 'app*'
```

### Path-Based Filtering

Match configurations by their file system path:

```bash
# Relative paths with globs
terragrunt find --filter './envs/prod/**'

# Absolute paths
terragrunt find --filter '/absolute/path/to/envs/dev/apps/*'
```

### Attribute-Based Filtering

Match configurations by their configuration attributes:

```bash
# Filter by type
terragrunt find --filter 'type=unit'
terragrunt find --filter 'type=stack'

# Filter by external dependency status
terragrunt find --filter 'external=false'

# Filter by files read
terragrunt find --filter 'reading=shared.hcl'
terragrunt find --filter 'reading=common/*.hcl' # Globs supported!
terragrunt find --filter 'reading=config/**' # Double-wildcard globs are required filtering on files nested in subdirectories.
terragrunt find --filter 'reading=config/vars.tfvars'
```

<Aside type="tip" title="What does 'Reading' mean?">

The `reading` attribute filters configurations based on which files they themselves read. This is useful for finding all infrastructure that could potentially be impacted by shared configuration, and is particularly useful when a commonly included configuration (like `root.hcl`) is updated.

See the [mark_as_read function documentation](/docs/reference/hcl/functions/#mark_as_read) for more information on how Terragrunt tracks files that are read during parsing.

</Aside>

### Negation

Exclude configurations using the `!` prefix:

```bash
# Exclude by name
terragrunt find --filter '!app1'

# Exclude by path
terragrunt find --filter '!./prod/**'
```

### Intersection (Refinement)

Use the `|` operator to refine results:

```bash
# Find all units in prod directory
terragrunt find --filter './prod/** | type=unit'

# Chain multiple filters
terragrunt find --filter './dev/** | type=unit | !name=unit1'
```

### Git-Based Filtering

Filter configurations based on changes between Git references. For the common use case of comparing the default branch with `HEAD`, you can use the `--filter-affected` flag as a convenient shorthand:

```bash
# Find components affected by changes between main and HEAD
terragrunt find --filter-affected
```

For more control, use Git-based filter expressions directly:

```bash
# Compare between two references
terragrunt find --filter '[main...HEAD]'

# Shorthand: compare reference to HEAD
terragrunt find --filter '[main]'

# Compare between specific commits
terragrunt find --filter '[abc123...def456]'
```

For more details and examples, see the [Filters feature documentation](/docs/features/filter#git-based-expressions).

### Graph-Based Filtering

Filter configurations based on dependency relationships using graph traversal. Use ellipsis (`...`) to traverse the dependency graph and caret (`^`) to exclude the target from results.

**Syntax variants:**
- `foo...` - Include target and all dependencies (things it depends on)
- `...foo` - Include target and all dependents (things that depend on it)
- `...foo...` - Include target, dependencies, and dependents
- `^foo...` - Include only dependencies (exclude target)
- `...^foo` - Include only dependents (exclude target)
- `...^foo...` - Include dependencies and dependents (exclude target)

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

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

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

# Find dependencies of 'service' but exclude 'service' itself
terragrunt find --filter '^service...'

# Combine graph traversal with path filters (note the use of braces to escape the path)
terragrunt find --filter '{./apps/service}...'

# Combine graph traversal with attribute filters
terragrunt find --filter '...type=unit'

# Refine graph results with intersection
terragrunt find --filter 'service... | external=false'
```

<Aside type="note">
Graph expressions require dependency discovery to work correctly. When using graph expressions, Terragrunt automatically discovers dependency relationships between components. This may add some overhead compared to simple name or path filters.

For more detailed examples and explanations, see the [Filters feature documentation](/docs/features/filter#graph-based-expressions).
</Aside>

### Union (Multiple Filters)

Specify multiple `--filter` flags to combine results using OR logic:

```bash
# Find components named 'unit1' OR 'stack1'
terragrunt find --filter unit1 --filter stack1
```

### The filters file

Instead of specifying filters on the command line, you can store filter queries in a file. By default, Terragrunt automatically reads filter queries from the `.terragrunt-filters` file in your current working directory if it exists.

```bash
# Automatically reads .terragrunt-filters (no flag needed)
terragrunt find

# Use a custom filters file
terragrunt find --filters-file custom-filters.txt

# Disable automatic file reading
terragrunt find --no-filters-file
```

The filters file should contain one filter query per line. Empty lines and lines starting with `#` are ignored:

```text
# Production environment filters
type=unit
./prod/**

# Exclude test units
!name=test-*
```

## Supported Commands

Currently supported in:
- [find](/docs/reference/cli/commands/find)
- [list](/docs/reference/cli/commands/list)
- [run](/docs/reference/cli/commands/run)
- [hcl fmt](/docs/reference/cli/commands/hcl/fmt)
- [hcl validate](/docs/reference/cli/commands/hcl/validate)

Planned for future releases:
- [dag graph](/docs/reference/cli/commands/dag/graph)

## Learn More

For comprehensive examples and advanced usage patterns, see the [Filters feature documentation](/docs/features/filter).
