You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There are several different types of filters, and particular ways in which they can be combined to achieve different results. You can learn more about that below.
74
+
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.
75
75
76
-
### Name-Based Filtering
76
+
| Filter Type | Description |
77
+
|-------------|-------------|
78
+
| Name-Based | Match units and stacks by their name. |
79
+
| Path-Based | Match units and stacks by their file system path. |
80
+
| Attribute-Based | Match units and stacks by their configuration attributes. |
81
+
| Negation | Exclude units and stacks using the `!` prefix. |
82
+
| Intersection | Use the `|` operator to refine results. |
83
+
| Union | Combine filter results using multiple `--filter` flags. |
84
+
| Graph-Based | Filter units based on their dependency relationships using graph traversal operators. |
85
+
| Git-Based | Filter units and stacks based on Git diffs using Git expressions. |
86
+
87
+
### Name-Based Expressions
77
88
78
89
Match units and stacks by their name. This is the simplest form of filtering.
Note that `app1` and `app2` were selected _within_ the `apps` directory. Filtering on names will match _any_ unit/stack that has a name that matches the filter.
100
111
</Aside>
101
112
102
-
### Path-Based Filtering
113
+
### Path-Based Expressions
103
114
104
115
Match units and stacks by their file system path.
105
116
@@ -143,7 +154,7 @@ Note that globs used in path-based filtering will not recursively match nested d
143
154
(That's why `./envs/stage/**` is used above)
144
155
</Aside>
145
156
146
-
### Attribute-Based Filtering
157
+
### Attribute-Based Expressions
147
158
148
159
Match units and stacks by their configuration attributes.
The result will be the components that are not units _and_ are named `unit1`.
367
+
368
+
As a result, you should be able to expect any negative filter to take effect, regardless of how other positive filters may result in the addition of results.
369
+
370
+
</Aside>
371
+
290
372
### Graph-Based Filtering
291
373
292
374
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 expressions require dependency/dependent discovery 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.
407
489
</Aside>
408
490
409
-
### Union (Multiple Filters)
491
+
### Git-Based Filtering
410
492
411
-
Specify multiple `--filter` flags to combine results using OR logic.
493
+
Match units and stacks based on changes between Git references. This is useful for targeting infrastructure that has been modified, added, or removed between commits, branches, or tags.
412
494
413
495
```bash
414
-
#Find components named 'unit1' OR 'stack1'
415
-
terragrunt find --filter unit1 --filter stack1
496
+
#Compare between two references
497
+
terragrunt find --filter '[main...HEAD]'
416
498
417
-
#Find components in ./envs/prod/* OR ./envs/stage/*
-**unit1**\<-- Matched by the first filter _and_ the second filter
428
-
- terragrunt.hcl
429
-
-**unit2**\<-- Matched by the second filter
430
-
- terragrunt.hcl
431
-
-**stack1**\<-- Matched by the first filter _and_ the second filter
432
-
- terragrunt.stack.hcl
433
-
-**stack2**\<-- Matched by the second filter
434
-
- terragrunt.stack.hcl
435
-
- stage
436
-
-**unit1**\<-- Matched by the first filter _and_ the second filter
437
-
- terragrunt.hcl
438
-
-**unit2**\<-- Matched by the second filter
439
-
- terragrunt.hcl
440
-
-**stack1**\<-- Matched by the first filter _and_ the second filter
441
-
- terragrunt.stack.hcl
442
-
-**stack2**\<-- Matched by the second filter
443
-
- terragrunt.stack.hcl
444
-
- dev
445
-
-**unit1**\<-- Matched by the first filter
446
-
- terragrunt.hcl
447
-
- unit2
448
-
- terragrunt.hcl
449
-
-**stack1**\<-- Matched by the first filter
450
-
- terragrunt.stack.hcl
451
-
-**stack2**\<-- Matched by the third filter
452
-
- terragrunt.stack.hcl
516
+
- .
517
+
-**modified-unit**\<-- Matched by [main...HEAD] (terragrunt.hcl was modified)
518
+
- terragrunt.hcl (modified)
519
+
-**new-unit**\<-- Matched by [main...HEAD] (terragrunt.hcl was added)
520
+
- terragrunt.hcl (added)
521
+
-**removed-unit**\<-- Matched by [main...HEAD] (terragrunt.hcl was removed)
522
+
- (directory removed)
523
+
- unchanged-unit
524
+
- terragrunt.hcl (unchanged)
453
525
</FileTree>
454
526
455
-
<Asidetype="caution"title="Unions of negated filters">
527
+
<Asidetype="note">
528
+
When using Git-based filtering and the `run` command, you are required to use one of the `plan` or `apply` commands, and not the `-destroy` flag.
456
529
457
-
When a filter query starts with a negation (`!`), the result is applied after _all_ positive filters have been applied.
530
+
This is because whether or not a unit will be destroyed is determined by logic relevant to inspecting changes in Git.
531
+
532
+
When units are added or modified between two Git references, they will be be planned or applied. When the units are removed between two Git references, they will be planned for destruction (with `plan -destroy) or destroyed (with `apply -destroy`).
533
+
534
+
In the scenario above, running the following:
458
535
459
-
This means that if you have a filter query like this:
The result will be the components that are not units _and_ are named `unit1`.
540
+
Will result in the following:
465
541
466
-
As a result, you should be able to expect any negative filter to take effect, regardless of how other positive filters may result in the addition of results.
542
+
-`modified-unit` will be planned (`tofu plan`)
543
+
-`new-unit` will be planned (`tofu plan`)
544
+
-`removed-unit` will be planned for destruction (`tofu plan -destroy`)
545
+
-`unchanged-unit` will be ignored
467
546
547
+
Note that you will also receive a warning when doing this that you must provide the `--filter-allow-destroy` flag to allow destruction to occur on `apply`. This is a safeguard to prevent accidental destruction of infrastructure.
468
548
</Aside>
469
549
470
-
## Usage with Commands
550
+
<Asidetype="tip"title="How it works">
471
551
472
-
The following commands all support the `--filter` flag, and use it to filter results in the same way:
552
+
When evaluating a Git-based filter, Terragrunt will first generate a worktree for every reference that needs to be evaluated, and assess the diffs between Git references.
e.g. For a filter like `[main...HEAD]`, Terragrunt will generate a worktree for `main` and one for `HEAD` in temporary directories, and use `git diff` to assess the diffs between the two references.
479
555
480
-
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`).
556
+
Then, for any unit that is discovered within those worktrees, Terragrunt will enqueue that unit for a run in the run queue _in the worktree where it was discovered_.
557
+
558
+
In the example above, the `modified-unit` will be discovered in a "to" temporary directory (e.g. `/tmp/.../terragrunt-worktree-HEAD.../modified-unit`), whereas the `removed-unit` would be discovered in the "from" temporary directory (e.g. `/tmp/.../terragrunt-worktree-main.../removed-unit`).
559
+
560
+
This is important to recognize, as it's how destroys will be possible despite the fact that the unit is no longer present in the current working directory. As a consequence, however, you may find that usage of absolute paths don't work how you expect, as you will be performing runs in the temporary directories created for the relevant worktrees.
481
561
482
-
<Asidetype="note">
483
-
Note that these commands _may_ have different logic for _discovery_, which is the process of surfacing the initial set of components to filter, but the filtering logic itself should be the same.
484
562
</Aside>
485
563
564
+
## Usage with Commands
565
+
566
+
The following commands all support the `--filter` flag using the same filtering syntax (note the section below on [special interactions](#special-interactions)):
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`).
575
+
486
576
## Comparison with Queue Control Flags
487
577
488
-
The `--filter` flag provides a unified alternative to multiple queue control flags:
578
+
The `--filter` flag provides a unified alternative to multiple queue control flags. These flags will be aliased to their equivalent filter expressions once the `filter-flag` experiment is stabilized:
0 commit comments