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

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

<Aside type="note" title="Filter Behavior for HCL Format">
The `--filter` flag works differently for `hcl fmt` compared to other commands. It filters on individual HCL files rather than units 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 filtering
terragrunt hcl fmt --filter './prod/**/*.hcl'

# Not supported: Attribute-based filtering
terragrunt hcl fmt --filter 'type=unit'  # This will not work
```
</Aside>

The `--filter` flag provides a path-based querying syntax for targeting specific HCL files to format.

## Usage

```bash
terragrunt hcl fmt --filter './prod/**'
```

### Path-Based Filtering
Match HCL files by their file system path:

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

# Format all HCL files in a specific directory
terragrunt hcl fmt --filter './modules/**/*.hcl'

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

### Negation
Exclude paths using the `!` prefix:

```bash
# Exclude by path
terragrunt hcl fmt --filter '!./prod/**'

# Exclude specific directories
terragrunt hcl fmt --filter '!./test/**'
```

### Intersection (Refinement)
Use the `|` operator to refine results:

```bash
# Format HCL files in prod directory, excluding tests
terragrunt hcl fmt --filter './prod/** | !./prod/test/**'

# Format specific file patterns
terragrunt hcl fmt --filter './**/*.hcl | !./**/test/**'
```

### Union (Multiple Filters)
Specify multiple `--filter` flags to combine results using OR logic:

```bash
# Format files in either dev or staging directories
terragrunt hcl fmt --filter './dev/**' --filter './staging/**'
```

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

